WindowsPrincipal.IsInRole 方法

参考

定义

命名空间:: System.Security.Principal

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

程序集:

程序集:: mscorlib.dll

重要

一些信息与预发行产品相关，相应产品在发行之前可能会进行重大修改。对于此处提供的信息，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，即使你是"内置管理员"组。执行代码之前，可以通过右键单击应用程序图标并指示要以管理员角色运行，来提升权限。

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

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

下表列出了默认的 RID 值。

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

内置全局组	RID
DOMAINNAME\Domain Admins	0x200
DOMAINNAME\Domain Users	0x201
DOMAINNAME\Domain 来宾	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) ，建议使用重载作为首选重载来确定用户的角色。

备注

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

适用于

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) 建议重载重载，作为确定用户角色的首选重载。

备注

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

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

备注

采用字符串格式的内置角色的拼写与枚举中使用的拼写不同 WindowsBuiltInRole 。例如，枚举中的管理员拼写为 "管理员"，而不是 "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)

参数

返回

实现

示例

注解

另请参阅

适用于

其他资源