Share via


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

Data Retrieval Overview

SharePoint Client Object Creation

SharePoint 2010 Client Object Model Guidelines

Common Programming Tasks in the Managed Client Object Model

Other Resources

Client Class Library