WindowsPrincipal.IsInRole 方法

参考

定义

命名空间:: System.Security.Principal

程序集:: System.Security.Principal.Windows.dll

程序集:: mscorlib.dll

包:: System.Security.Principal.Windows v5.0.0

重要

一些信息与预发行产品相关，相应产品在发行之前可能会进行重大修改。对于此处提供的信息，Microsoft 不作任何明示或暗示的担保。

确定当前主体是否属于指定的 Windows 用户组。

重载

IsInRole(Int32)	确定当前主体是否属于具有指定相对标识符 (RID) 的 Windows 用户组。
IsInRole(SecurityIdentifier)	确定当前主体是否属于具有指定的安全标识符 (SID) 的 Windows 用户组。
IsInRole(WindowsBuiltInRole)	确定当前主体是否属于具有指定 WindowsBuiltInRole 的 Windows 用户组。
IsInRole(String)	确定当前主体是否属于具有指定名称的 Windows 用户组。

注解

此方法有四个重载。出于性能原因， IsInRole(SecurityIdentifier) 强烈建议使用重载。

IsInRole(Int32)

确定当前主体是否属于具有指定相对标识符 (RID) 的 Windows 用户组。

public:
 virtual bool IsInRole(int rid);

public virtual bool IsInRole (int rid);

override this.IsInRole : int -> bool

abstract member IsInRole : int -> bool
override this.IsInRole : int -> bool

Public Overridable Function IsInRole (rid As Integer) As Boolean

参数

rid: Int32

Windows 用户组的 RID，在该用户组中检查主体的成员资格状态。

Boolean

如果当前主体是指定的 Windows 用户组的成员（即在特定的角色中），则为 true；否则为 false。

示例

下面的代码示例演示如何使用 IsInRole 方法。枚举 WindowsBuiltInRole 用作标识内置角色的 RID 的源。 RID 用于确定当前主体的角色。

public:
   static void DemonstrateWindowsBuiltInRoleEnum()
   {
      AppDomain^ myDomain = Thread::GetDomain();

      myDomain->SetPrincipalPolicy( PrincipalPolicy::WindowsPrincipal );
      WindowsPrincipal^ myPrincipal = dynamic_cast<WindowsPrincipal^>(Thread::CurrentPrincipal);

      Console::WriteLine( "{0} belongs to: ", myPrincipal->Identity->Name );

      Array^ wbirFields = Enum::GetValues( WindowsBuiltInRole::typeid );

      for each ( Object^ roleName in wbirFields )
      {
         try
         {
            Console::WriteLine( "{0}? {1}.", roleName,
               myPrincipal->IsInRole(  *dynamic_cast<WindowsBuiltInRole^>(roleName) ) );
         }
         catch ( Exception^ ) 
         {
            Console::WriteLine( "{0}: Could not obtain role for this RID.",
               roleName );
         }
      }
   }

using System;
using System.Threading;
using System.Security.Permissions;
using System.Security.Principal;

class SecurityPrincipalDemo
{
    public static void DemonstrateWindowsBuiltInRoleEnum()
    {
        AppDomain myDomain = Thread.GetDomain();

        myDomain.SetPrincipalPolicy(PrincipalPolicy.WindowsPrincipal);
        WindowsPrincipal myPrincipal = (WindowsPrincipal)Thread.CurrentPrincipal;
        Console.WriteLine("{0} belongs to: ", myPrincipal.Identity.Name.ToString());
        Array wbirFields = Enum.GetValues(typeof(WindowsBuiltInRole));
        foreach (object roleName in wbirFields)
        {
            try
            {
                // Cast the role name to a RID represented by the WindowsBuildInRole value.
                Console.WriteLine("{0}? {1}.", roleName,
                    myPrincipal.IsInRole((WindowsBuiltInRole)roleName));
                Console.WriteLine("The RID for this role is: " + ((int)roleName).ToString());
            }
            catch (Exception)
            {
                Console.WriteLine("{0}: Could not obtain role for this RID.",
                    roleName);
            }
        }
        // Get the role using the string value of the role.
        Console.WriteLine("{0}? {1}.", "Administrators",
            myPrincipal.IsInRole("BUILTIN\\" + "Administrators"));
        Console.WriteLine("{0}? {1}.", "Users",
            myPrincipal.IsInRole("BUILTIN\\" + "Users"));
        // Get the role using the WindowsBuiltInRole enumeration value.
        Console.WriteLine("{0}? {1}.", WindowsBuiltInRole.Administrator,
           myPrincipal.IsInRole(WindowsBuiltInRole.Administrator));
        // Get the role using the WellKnownSidType.
        SecurityIdentifier sid = new SecurityIdentifier(WellKnownSidType.BuiltinAdministratorsSid, null);
        Console.WriteLine("WellKnownSidType BuiltinAdministratorsSid  {0}? {1}.", sid.Value, myPrincipal.IsInRole(sid));
    }

    public static void Main()
    {
        DemonstrateWindowsBuiltInRoleEnum();
    }
}

Imports System.Threading
Imports System.Security.Permissions
Imports System.Security.Principal

Class SecurityPrincipalDemo

    Public Shared Sub DemonstrateWindowsBuiltInRoleEnum()
        Dim myDomain As AppDomain = Thread.GetDomain()

        myDomain.SetPrincipalPolicy(PrincipalPolicy.WindowsPrincipal)
        Dim myPrincipal As WindowsPrincipal = CType(Thread.CurrentPrincipal, WindowsPrincipal)
        Console.WriteLine("{0} belongs to: ", myPrincipal.Identity.Name.ToString())
        Dim wbirFields As Array = [Enum].GetValues(GetType(WindowsBuiltInRole))
        Dim roleName As Object
        For Each roleName In wbirFields
            Try
                ' Cast the role name to a RID represented by the WindowsBuildInRole value.
                Console.WriteLine("{0}? {1}.", roleName, myPrincipal.IsInRole(CType(roleName, WindowsBuiltInRole)))
                Console.WriteLine("The RID for this role is: " + Fix(roleName).ToString())

            Catch
                Console.WriteLine("{0}: Could not obtain role for this RID.", roleName)
            End Try
        Next roleName
        ' Get the role using the string value of the role.
        Console.WriteLine("{0}? {1}.", "Administrators", myPrincipal.IsInRole("BUILTIN\" + "Administrators"))
        Console.WriteLine("{0}? {1}.", "Users", myPrincipal.IsInRole("BUILTIN\" + "Users"))
        ' Get the role using the WindowsBuiltInRole enumeration value.
        Console.WriteLine("{0}? {1}.", WindowsBuiltInRole.Administrator, myPrincipal.IsInRole(WindowsBuiltInRole.Administrator))
        ' Get the role using the WellKnownSidType.
        Dim sid As New SecurityIdentifier(WellKnownSidType.BuiltinAdministratorsSid, Nothing)
        Console.WriteLine("WellKnownSidType BuiltinAdministratorsSid  {0}? {1}.", sid.Value, myPrincipal.IsInRole(sid))

    End Sub

    Public Shared Sub Main()
        DemonstrateWindowsBuiltInRoleEnum()

    End Sub
End Class

注解

测试新创建的角色信息（如新用户或新组）时，必须注销并登录以强制在域中传播角色信息。否则可能会导致 IsInRole 测试返回 false。

出于性能原因，建议将 IsInRole(SecurityIdentifier) 重载作为确定用户角色的首选重载。

注意

在 Windows Vista 中，用户帐户控制 (UAC) 决定用户的特权。如果您是内置的 Administrators 组的成员，将为您分配两个运行时访问令牌：一个标准用户访问令牌和一个管理员访问令牌。默认情况下，您拥有标准用户角色。尝试执行需要管理权限的任务时，可以使用“同意”对话框动态提升角色。执行 IsInRole 方法的代码不显示“同意”对话框。如果你是标准用户角色，则代码返回 false，即使你位于内置管理员组中。在执行代码之前，可以通过右键单击应用程序图标并指示要以管理员身份运行来提升特权。

相对标识符 (RID) 是 Windows 用户组的安全标识符 (SID) 的组件，并且受支持以帮助防止跨平台本地化问题。许多用户帐户、本地组和全局组的默认 RID 值在所有版本的 Windows 中都是恒定的。

例如，BUILTIN\Administrators 角色的 RID 0x220。如果当前主体是管理员，则使用 0x220 作为方法的 IsInRole 输入参数会导致 true 返回。

下表列出了默认 RID 值。

内置用户	RID
DOMAINNAME\Administrator	0x1F4
DOMAINNAME\Guest	0x1F5

内置全局组	RID
DOMAINNAME\Domain Admins	0x200
DOMAINNAME\Domain Users	0x201
DOMAINNAME\Domain Guests	0x202

内置本地组	RID
BUILTIN\Administrators	0x220
BUILTIN\Users	0x221
BUILTIN\Guests	0x222
BUILTIN\Account 运算符	0x224
BUILTIN\Server 运算符	0x225
BUILTIN\Print 运算符	0x226
BUILTIN\Backup 运算符	0x227
BUILTIN\Replicator	0x228

适用于

IsInRole(SecurityIdentifier)

确定当前主体是否属于具有指定的安全标识符 (SID) 的 Windows 用户组。

public:
 virtual bool IsInRole(System::Security::Principal::SecurityIdentifier ^ sid);

public virtual bool IsInRole (System.Security.Principal.SecurityIdentifier sid);

[System.Runtime.InteropServices.ComVisible(false)]
public virtual bool IsInRole (System.Security.Principal.SecurityIdentifier sid);

override this.IsInRole : System.Security.Principal.SecurityIdentifier -> bool

[<System.Runtime.InteropServices.ComVisible(false)>]
abstract member IsInRole : System.Security.Principal.SecurityIdentifier -> bool
override this.IsInRole : System.Security.Principal.SecurityIdentifier -> bool

[<System.Runtime.InteropServices.ComVisible(false)>]
override this.IsInRole : System.Security.Principal.SecurityIdentifier -> bool

Public Overridable Function IsInRole (sid As SecurityIdentifier) As Boolean

参数

sid: SecurityIdentifier

唯一标识 Windows 用户组的 SecurityIdentifier。

Boolean

如果当前主体是指定的 Windows 用户组的成员，则为 true；否则为 false。

属性: ComVisibleAttribute

例外

ArgumentNullException

sid 为 null。

SecurityException

Windows 返回了 Win32 错误。

示例

下面的代码示例演示如何使用 WindowsPrincipal.IsInRole(SecurityIdentifier) 方法。枚举 BuiltinAdministratorsSid 值用于确定当前主体是否为管理员。有关完整的代码示例，请参阅 WindowsPrincipal.IsInRole(Int32) 方法。

// Get the role using the WellKnownSidType.
SecurityIdentifier sid = new SecurityIdentifier(WellKnownSidType.BuiltinAdministratorsSid, null);
Console.WriteLine("WellKnownSidType BuiltinAdministratorsSid  {0}? {1}.", sid.Value, myPrincipal.IsInRole(sid));

    ' Get the role using the WellKnownSidType.
    Dim sid As New SecurityIdentifier(WellKnownSidType.BuiltinAdministratorsSid, Nothing)
    Console.WriteLine("WellKnownSidType BuiltinAdministratorsSid  {0}? {1}.", sid.Value, myPrincipal.IsInRole(sid))

End Sub

注解

唯 SecurityIdentifier 一标识 Windows 上的用户或组。测试新创建的角色信息（如新用户或新组）时，必须注销并登录以强制在域中传播角色信息。否则可能会导致 IsInRole 测试返回 false。

注意

出于性能原因，这是确定用户角色时首选的重载。

适用于

IsInRole(WindowsBuiltInRole)

确定当前主体是否属于具有指定 WindowsBuiltInRole 的 Windows 用户组。

public:
 virtual bool IsInRole(System::Security::Principal::WindowsBuiltInRole role);

public virtual bool IsInRole (System.Security.Principal.WindowsBuiltInRole role);

override this.IsInRole : System.Security.Principal.WindowsBuiltInRole -> bool

abstract member IsInRole : System.Security.Principal.WindowsBuiltInRole -> bool
override this.IsInRole : System.Security.Principal.WindowsBuiltInRole -> bool

Public Overridable Function IsInRole (role As WindowsBuiltInRole) As Boolean

参数

role: WindowsBuiltInRole

WindowsBuiltInRole 值之一。

Boolean

如果当前主体是指定的 Windows 用户组的成员，则为 true；否则为 false。

例外

ArgumentException

role 不是有效的 WindowsBuiltInRole 值。

示例

下面的示例使用 WindowsBuiltInRole 枚举来确定当前主体是否为 Administrator。有关完整的代码示例，请参阅 WindowsPrincipal.IsInRole(Int32) 方法。

// Get the role using the WindowsBuiltInRole enumeration value.
Console.WriteLine("{0}? {1}.", WindowsBuiltInRole.Administrator,
   myPrincipal.IsInRole(WindowsBuiltInRole.Administrator));

' Get the role using the WindowsBuiltInRole enumeration value.
Console.WriteLine("{0}? {1}.", WindowsBuiltInRole.Administrator, myPrincipal.IsInRole(WindowsBuiltInRole.Administrator))

注解

测试新创建的角色信息（如新用户或新组）时，必须注销并登录以强制在域中传播角色信息。否则可能会导致 IsInRole 测试返回 false。

出于性能原因，建议将 IsInRole(SecurityIdentifier) 重载作为确定用户角色的首选重载。

注意

适用于

IsInRole(String)

确定当前主体是否属于具有指定名称的 Windows 用户组。

public:
 override bool IsInRole(System::String ^ role);

public:
 virtual bool IsInRole(System::String ^ role);

public override bool IsInRole (string role);

public virtual bool IsInRole (string role);

override this.IsInRole : string -> bool

abstract member IsInRole : string -> bool
override this.IsInRole : string -> bool

Public Overrides Function IsInRole (role As String) As Boolean

Public Overridable Function IsInRole (role As String) As Boolean

参数

role: String

要对其检查成员身份的 Windows 用户组的名称。

Boolean

如果当前主体是指定的 Windows 用户组的成员，则为 true；否则为 false。

实现

IsInRole(String)

示例

下面的代码示例演示如何使用 WindowsPrincipal.IsInRole(String) 方法。

字符串 BUILTIN\Administrators 和 BUILTIN\Users 用于确定当前主体是管理员还是用户。有关完整的代码示例，请参阅 WindowsPrincipal.IsInRole(Int32) 方法。

// Get the role using the string value of the role.
Console.WriteLine("{0}? {1}.", "Administrators",
    myPrincipal.IsInRole("BUILTIN\\" + "Administrators"));
Console.WriteLine("{0}? {1}.", "Users",
    myPrincipal.IsInRole("BUILTIN\\" + "Users"));

' Get the role using the string value of the role.
Console.WriteLine("{0}? {1}.", "Administrators", myPrincipal.IsInRole("BUILTIN\" + "Administrators"))
Console.WriteLine("{0}? {1}.", "Users", myPrincipal.IsInRole("BUILTIN\" + "Users"))

注解

测试新创建的角色信息（如新用户或新组）时，必须注销并登录以强制在域中传播角色信息。否则可能会导致 IsInRole 测试返回 false。

出于性能原因，建议将 IsInRole(SecurityIdentifier) 重载作为确定用户角色的首选重载。

注意

对于内置角色， role 字符串应采用“BUILTIN\RoleNameHere”格式。例如，若要测试 Windows 管理员角色的成员身份，表示该角色的字符串应为“BUILTIN\Administrators”。请注意，可能需要对反斜杠进行转义。下表列出了内置角色。

注意

字符串格式的 BUILTIN 角色的拼写不同于枚举中使用的 WindowsBuiltInRole 拼写。例如，枚举中管理员的拼写为“Administrator”，而不是“Administrators”。使用此重载时，请使用下表中角色的拼写。

内置本地组
BUILTIN\Administrators
BUILTIN\Users
BUILTIN\Guests
BUILTIN\Account 运算符
BUILTIN\Server 运算符
BUILTIN\Print 运算符
BUILTIN\Backup 运算符
BUILTIN\Replicator

对于特定于计算机的角色， role 字符串应采用“MachineName\RoleNameHere”格式。

对于特定于域的角色， role 字符串的格式应为“DomainName\RoleNameHere”;例如 "SomeDomain\Domain Users“。

注意

在 .NET Framework 版本 1.0 中 role ，参数区分大小写。在 .NET Framework 版本 1.1 及更高版本中， role 参数不区分大小写。

另请参阅

WindowsBuiltInRole

适用于

通过

WindowsPrincipal.IsInRole 方法

定义

重载

注解

IsInRole(Int32)

参数

返回

示例

注解

适用于

IsInRole(SecurityIdentifier)

参数

返回

例外

示例

注解

适用于

IsInRole(WindowsBuiltInRole)

参数

返回

例外

示例

注解

适用于

IsInRole(String)

参数

返回

实现

示例

注解

另请参阅

适用于

其他资源