Working with groups
In Microsoft 365 there's the concept of Microsoft 365 group with owners and members and there are SharePoint groups. The latter is the main topic of this page as SharePoint groups is the common model to used to grant users or other groups access to a SharePoint site.
In the remainder of this article you'll see a lot of context
use: in this case this is a PnPContext
which was obtained via the PnPContextFactory
as explained in the overview article and show below:
using (var context = await pnpContextFactory.CreateAsync("SiteToWorkWith"))
{
// See next chapter on how to use the PnPContext for working with lists
}
SharePoint Groups
SharePoint groups are defined at the web level and by default does each web has an owners group, a members group and a visitors group. Adding users to those default created groups is a commonly used model, but you can also add a new group with it's role definitions and users.
Getting groups
To get the groups on a web you query the SiteGroups
property which return a collection of ISharePointGroup
instances. If you want to work with the default groups you can get a reference to these groups via the AssociatedOwnerGroup
, AssociatedMemberGroup
or AssociatedVisitorGroup
properties of an IWeb
.
// Option A: Load the default groups
await context.Web.LoadAsync(p => p.AssociatedMemberGroup, p => p.AssociatedOwnerGroup, p => p.AssociatedVisitorGroup);
await foreach(var user in context.Web.AssociatedOwnerGroup.Users.AsAsyncEnumerable())
{
// do something with the user/group
}
// Option B: load all the groups with their users
await context.Web.LoadAsync(p => p.SiteGroups.QueryProperties(u => u.Users));
foreach(var group in context.Web.SiteGroups.AsRequested())
{
// do something with the group
}
Adding a group with a custom role definition
Adding a new SharePoint group is done via the usual Add
methods. When a group is added you also need to assign a role to it (see Configuring roles) otherwise the users added to group will not have any permissions on the SharePoint site. The AddRoleDefinitions
methods are equivalent to using the methods provided via the ISecurableObject
interface on IWeb
.
// Add a new role definition for our new group, a limited reader role
var roleDefinition = await context.Web.RoleDefinitions.AddAsync(roleDefName, Model.SharePoint.RoleType.Reader, new Model.SharePoint.PermissionKind[] { Model.SharePoint.PermissionKind.Open });
// Add the new SharePoint group
var siteGroup = await context.Web.SiteGroups.AddAsync("Limited readers");
// Add the role definition to our group
await siteGroup.AddRoleDefinitionsAsync(roleDefinition.Name);
Editing a group
To update a group you first change the needed properties and then call one of the Update
methods.
Note
As a group's description cannot contain html characters the provided html is turned into text automatically. Also is the description length automatically truncated at 511 characters. Futhermore updating a group's description will not show this description in the group's "About Me", for that you need to update the group's row in the User Information List as shown in the sample code.
// First get the group to update
var siteGroup = await context.Web.SiteGroups.FirstOrDefaultAsync(g => g.Title == "Limited readers");
// Update the group, e.g. the Description property
siteGroup.Description = "Group for users with limited read access to this site";
await siteGroup.UpdateAsync();
// Update "About Me" in group overview page requires updating the group row in the user information list
await context.Web.EnsurePropertiesAsync(p => p.SiteUserInfoList);
var item = await context.Web.SiteUserInfoList.Items.GetByIdAsync(siteGroup.Id);
item["Notes"] = "This is my custom description";
await item.UpdateAsync();
Deleting a group
To delete a group use one of the Delete
methods.
// First get the group to delete
var siteGroup = await context.Web.SiteGroups.FirstOrDefaultAsync(g => g.Title == "Limited readers");
// Delete the group
await siteGroup.DeleteAsync();
Adding users/groups to a group
Once a group has been created adding users or other groups is a common task which can be done using one of the AddUser
methods. Note that you can also add special user accounts representing "Everyone", Azure AD security groups or Microsoft 365 Groups by specifying the correct login name. The User page will provide more details on this.
// First get the group to add users to
var siteGroup = await context.Web.SiteGroups.FirstOrDefaultAsync(g => g.Title == "Limited readers");
// Get the user to add
var currentUser = await context.Web.GetCurrentUserAsync();
// Add the user: Option A
await siteGroup.Users.AddAsync(currentUser.LoginName)
// Add the user: Option B
await siteGroup.AddUserAsync(currentUser.LoginName);
Listing the users in a group
To query the users in a group you need to load/get the Users
property of the group.
// Notice how the users are loaded
var myGroup = await context.Web.SiteGroups.QueryProperties(p => p.Users).FirstOrDefaultAsync(g => g.Title == "Limited readers");
foreach(var user in myGroup.Users.AsRequested())
{
// do something with the group user
}
Removing users/groups from a group
Removing users from a group is done using the RemoveUser
methods.
// First get the group to remove users from
var siteGroup = await context.Web.SiteGroups.FirstOrDefaultAsync(g => g.Title == "Limited readers");
// Get the user to remove
var currentUser = await context.Web.GetCurrentUserAsync();
// Remove the user: Option A
await siteGroup.Users.AsRequested().FirstOrDefault(p => p.LoginName == currentUser.LoginName).DeleteAsync();
// Remove the user: Option B
await siteGroup.RemoveUserAsync(currentUser.Id);
Setting the owner of a group
If you provision groups you might want to set a user as owner of the group. For that you can use one of the `` methods:
// First get the group to set the owner for
var siteGroup = await context.Web.SiteGroups.FirstOrDefaultAsync(g => g.Title == "Limited readers");
// Get a user to set as owner, here we just take the first user defined in the site
var siteUser = await context.Web.SiteUsers.FirstOrDefaultAsync(p => p.PrincipalType == PrincipalType.User);
// Set the group owner
await siteGroup.SetUserAsOwnerAsync(siteUser.Id);
Microsoft 365 groups
Note
This only works for Teams site with group. Otherwise it will return an exception.
When a site is connected to a Microsoft 365 group then the Microsoft 365 group's owners are also site collection administrators and are part of the site's default "Owners" SharePoint group. The Microsoft's 365 group members will be automatically part of the site's default "Members" SharePoint group. Important to understand is that the Microsoft 365 group's owners and members complement the existing SharePoint security model, meaning it's perfectly possible to define add a SharePoint group with members in a Microsoft 365 group connected site (e.g. a team site). Important to understand is the permissions set of the SharePoint site via SharePoint groups do not apply to the Microsoft 365 group and it's other connected resources (e.g. a mailbox, Yammer group etc). Go here to learn more.
Getting the group
To get the group on a context you query the Group
property which return a model of IGraphGroup
instances.
// To get all properties
var group = await context.Group.GetAsync();
// To only return the Id property
var group = await context.Group.GetAsync(x => x.Id);