WindowsPrincipal.IsInRole Method (String)
Updated: July 2010
Determines whether the current principal belongs to the Windows user group with the specified name.
Assembly: mscorlib (in mscorlib.dll)
- Type: System.String
The name of the Windows user group for which to check membership.
Return ValueType: System.Boolean
true if the current principal is a member of the specified Windows user group; otherwise, false.
The primary use of this overload is to test for roles in custom user groups, not built-in user groups. When testing for newly created role information, such as a new user or a new group, it is important to log out and log in to force the propagation of role information within the domain. Not doing so can cause the IsInRole test to return false. This method is not supported on Windows 98 or Windows Millennium Edition.
For performance reasons, the IsInRole(SecurityIdentifier) overload is recommended as the preferable overload for determining the user's role.
In Windows Vista and later, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. When you attempt to perform a task that requires administrative privileges, you can dynamically elevate your role by using the Consent dialog box. The code that executes the IsInRole method does not display the Consent dialog box. The code returns false if you are in the standard user role, even if you are in the Built-in Administrators group. You can elevate your privileges before you execute the code by right-clicking the application icon and indicating that you want to run as an administrator.
Do not use this overload for built-in roles; use the IsInRole overload instead to avoid mistakes in role name spelling.
For machine-specific roles, the role string should be in the form "MachineName\RoleNameHere".
For domain-specific roles, the role string should be in the form "DomainName\RoleNameHere"; for example, "SomeDomain\Domain Users".
In the .NET Framework version 1.0, the role parameter is case-sensitive. In the .NET Framework version 1.1 and later, the role parameter is case-insensitive.
The following code example demonstrates the use of the method.
To use the example, create a custom local group by using the net localgroup command. You must log off and log back on to add the user to the group.
C:\windows\system32>net localgroup customGroup /add C:\windows\system32>net localgroup customGroup <username> /add
Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98
The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.