How to: Work with Roles
Applies to: SharePoint Foundation 2010
Available in SharePoint Online
Through the client object model, you can create custom role definitions within site collections, and you can assign new or existing users and groups to specific roles for Web sites, lists, and list items. Similar to the way you use the SPRoleDefinitionBindingCollection class in the server object model, you add a user or group, together with a RoleDefinitionBindingCollection object, to the collection of role assignments for a specific object.
Creating a role definition
To create a role definition in the collection of role definitions for a site collection, use the BasePermissions class (JavaScript: BasePermissions) to define a permission set, use the RoleDefinitionCreationInformation class (JavaScript: RoleDefinitionCreationInformation) to define a role that includes the permission set, and then add the new role to the collection of role definitions. The following example shows how to create a role for creating and managing alerts. The Order property (JavaScript: order) specifies that the new role be displayed fourth in order among custom role definitions listed on the Permissions Levels page of the site collection.
using System;
using Microsoft.SharePoint.Client;
namespace Microsoft.SDK.SharePointServices.Samples
{
class CreateRoleDefinition
{
static void Main()
{
ClientContext oClientContext = new ClientContext("http://MyServer/sites/MySiteCollection");
Web oWebsite = clientContext.Web;
BasePermissions permissions = new BasePermissions();
permissions.Set(PermissionKind.CreateAlerts);
permissions.Set(PermissionKind.ManageAlerts);
RoleDefinitionCreationInformation roleCreationInfo = new RoleDefinitionCreationInformation();
roleCreationInfo.BasePermissions = permissions;
roleCreationInfo.Description = "A new role with create and manage alerts permission";
roleCreationInfo.Name = "Create and Manage Alerts";
roleCreationInfo.Order = 4;
RoleDefinition oRoleDefinition = oWebsite.RoleDefinitions.Add(roleCreationInfo);
clientContext.ExecuteQuery();
Console.WriteLine("{0} role created.", oRoleDefinition.Name);
}
}
}
Imports System
Imports Microsoft.SharePoint.Client
Namespace Microsoft.SDK.SharePointServices.Samples
Class CreateRoleDefinition
Shared Sub Main()
Dim siteUrl As String = "http://MyServer/sites/MySiteCollection"
Dim oWebsite As Web = clientContext.Web
Dim permissions As New BasePermissions()
permissions.Set(PermissionKind.CreateAlerts)
permissions.Set(PermissionKind.ManageAlerts)
Dim roleCreationInfo As New RoleDefinitionCreationInformation()
roleCreationInfo.BasePermissions = permissions
roleCreationInfo.Description = "A new role with create and manage alerts permission"
roleCreationInfo.Name = "Create and Manage Alerts"
roleCreationInfo.Order = 4
Dim oRoleDefinition As RoleDefinition = oWebsite.RoleDefinitions.Add(roleCreationInfo)
clientContext.ExecuteQuery()
Console.WriteLine("{0} role created.", oRoleDefinition.Name)
End Sub
End Class
End Namespace
Assigning a user to a role on a Web site
To assign a user to a particular role on a Web site, you create a RoleDefinitionBindingCollection object for the Web site context, add a role definition to the binding collection object, and then use the Add(Principal, RoleDefinitionBindingCollection) method to add the user together with the binding collection to the role assignments for the Web site. The following example assigns an existing site collection user to the role defined in the previous example.
using System;
using Microsoft.SharePoint.Client;
namespace Microsoft.SDK.SharePointServices.Samples
{
class AddUserToRole
{
static void Main()
{
ClientContext oClientContext = new ClientContext("http://MyServer/sites/MySiteCollection/MyWebSite");
Web oWebsite = clientContext.Web;
Principal oUser = oWebsite.SiteUsers.GetByLoginName(@"DOMAIN\alias");
RoleDefinition oRoleDefinition = oWebsite.RoleDefinitions.GetByName("Create and Manage Alerts");
RoleDefinitionBindingCollection collRoleDefinitionBinding = new RoleDefinitionBindingCollection(clientContext);
collRoleDefinitionBinding.Add(oRoleDefinition);
RoleAssignment oRoleAssignment = oWebsite.RoleAssignments.Add(oUser, collRoleDefinitionBinding);
clientContext.Load(oUser,
user => user.Title);
clientContext.Load(oRoleDefinition,
role => role.Name);
clientContext.ExecuteQuery();
Console.WriteLine("{0} added with {1} role.", oUser.Title, oRoleDefinition.Name);
}
}
}
Imports System
Imports Microsoft.SharePoint.Client
Namespace Microsoft.SDK.SharePointServices.Samples
Class AddUserToRole
Shared Sub Main()
Dim siteUrl As String = "http://MyServer/sites/MySiteCollection"
Dim oWebsite As Web = clientContext.Web
Dim oUser As Principal = oWebsite.SiteUsers.GetByLoginName("domain\alias")
Dim oRoleDefinition As RoleDefinition = oWebsite.RoleDefinitions.GetByName("Create and Manage Alerts")
Dim collRoleDefinitionBinding As New RoleDefinitionBindingCollection(clientContext)
collRoleDefinitionBinding.Add(oRoleDefinition)
Dim oRoleAssignment As RoleAssignment = oWebsite.RoleAssignments.Add(oUser, collRoleDefinitionBinding)
clientContext.Load(oUser, _
Function(user) user.Title)
clientContext.Load(oRoleDefinition, _
Function(role) role.Name)
clientContext.ExecuteQuery()
Console.WriteLine("{0} added with {1} role.", oUser.Title, oRoleDefinition.Name)
End Sub
End Class
End Namespace
Creating a SharePoint group and adding the group to a role
In the same way that you create most other objects through the client object model, use the GroupCreationInformation class to define a new group, and then use the Add(GroupCreationInformation) method to add the group to the collection of site groups in a site collection. And just as you assign users to a role, you assign a group to a particular role on a Web site by creating a RoleDefinitionBindingCollection object for the Web site context, adding a role definition to the binding collection object, and then using the Add(Principal, RoleDefinitionBindingCollection) method to add the group together with the binding collection to the role assignments for the Web site. The following example creates a group and assigns it the Contribute role on the Web site.
using System;
using Microsoft.SharePoint.Client;
namespace Microsoft.SDK.SharePointServices.Samples
{
class CreateGroupAddToRole
{
static void Main()
{
ClientContext oClientContext = new ClientContext("http://MyServer/sites/MySiteCollection/MyWebSite");
Web oWebsite = clientContext.Web;
GroupCreationInformation groupCreationInfo = new GroupCreationInformation();
groupCreationInfo.Title = "My New Group";
groupCreationInfo.Description = "Description of new group.";
Group oGroup = oWebsite.SiteGroups.Add(groupCreationInfo);
RoleDefinitionBindingCollection collRoleDefinitionBinding = new RoleDefinitionBindingCollection(clientContext);
RoleDefinition oRoleDefinition = oWebsite.RoleDefinitions.GetByType(RoleType.Contributor);
collRoleDefinitionBinding.Add(oRoleDefinition);
oWebsite.RoleAssignments.Add(oGroup, collRoleDefinitionBinding);
clientContext.Load(oGroup,
group => group.Title);
clientContext.Load(oRoleDefinition,
role => role.Name);
clientContext.ExecuteQuery();
Console.WriteLine("{0} created and assigned {1} role.", oGroup.Title, oRoleDefinition.Name); }
}
}
Imports System
Imports Microsoft.SharePoint.Client
Namespace Microsoft.SDK.SharePointServices.Samples
Class CreateGroupAddToRole
Shared Sub Main()
Dim siteUrl As String = "http://MyServer/sites/MySiteCollection"
Dim oWebsite As Web = clientContext.Web
Dim groupCreationInfo As New GroupCreationInformation()
groupCreationInfo.Title = "My New Group "
groupCreationInfo.Description = "Description of new group."
Dim oGroup As Group = oWebsite.SiteGroups.Add(groupCreationInfo)
Dim collRoleDefinitionBinding As New RoleDefinitionBindingCollection(clientContext)
Dim oRoleDefinition As RoleDefinition = oWebsite.RoleDefinitions.GetByType(RoleType.Contributor)
collRoleDefinitionBinding.Add(oRoleDefinition)
oWebsite.RoleAssignments.Add(oGroup, collRoleDefinitionBinding)
clientContext.Load(oGroup, _
Function(group) group.Title)
clientContext.Load(oRoleDefinition, _
Function(role) role.Name)
clientContext.ExecuteQuery()
Console.WriteLine("{0} created and assigned {1} role.", oGroup.Title, oRoleDefinition.Name)
End Sub
End Class
End Namespace
For information and examples about how to work with client objects within the context of the Microsoft SharePoint Foundation 2010 Silverlight object model, see Using the Silverlight Object Model.
See Also
Concepts
How to: Work with Users and Groups
How to: Break Role Assignment Inheritance
Authorization, Users, and Groups
SharePoint Client Object Creation
SharePoint 2010 Client Object Model Guidelines
Common Programming Tasks in the Managed Client Object Model