WindowsPrincipal.IsInRole 方法

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

參數

傳回

如果目前主體是指定之 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) 建議多載作為判斷使用者角色的最好多載。

(RID) 的相對識別碼是 Windows 使用者群組的安全性識別碼元件 (SID) ，且支援協助防止跨平臺當地語系化問題。 許多用戶帳戶、本地組和全域群組都有預設 RID 值，在所有版本的 Windows 中都是固定的。

例如，BUILTIN\Administrators 角色的 RID 會0x220。 如果目前的主體是系統管理員，則使用 0x220 作為方法的輸入參數 IsInRole 會導致 true 傳回。

下表列出預設 RID 值。

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

參數

傳回

如果目前的主體是指定 Windows 使用者群組的成員，則為 true，否則為 false。

屬性

ComVisibleAttribute

例外狀況

範例

下列程式代碼範例示範 如何使用 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。

基於效能考慮，這是判斷使用者角色的最好多載。

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

參數

傳回

如果目前的主體是指定 Windows 使用者群組的成員，則為 true，否則為 false。

例外狀況

範例

下列範例會 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) 建議多載作為判斷使用者角色的最好多載。

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

參數

傳回

如果目前的主體是指定 Windows 使用者群組的成員，則為 true，否則為 false。

實作

範例

下列程式代碼範例示範 如何使用 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”。 請注意，反斜杠可能需要逸出。 下表列出內建角色。

對於電腦特定角色， role 字串的格式應該是 “MachineName\RoleNameHere”。

若為網域特定角色， role 字串的格式應該是 “DomainName\RoleNameHere”，例如 “ "SomeDomain\Domain Users。

另請參閱

• WindowsBuiltInRole