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 群組的成員，系統會將兩個執行階段存取語彙基元 (Token) 指派給您：標準使用者存取語彙基元及管理員存取語彙基元。根據預設，您會屬於標準使用者角色。當您嘗試執行需要系統管理許可權的工作時，您可以使用 [同意] 對話方塊來動態提升角色。執行方法的程式碼 IsInRole 不會顯示 [同意] 對話方塊。如果您是標準使用者角色，則程式碼會傳回 false，即使您是在內建的 Administrators 群組中也一樣。您可以在執行程式碼之前，以滑鼠右鍵按一下應用程式圖示，並指出您想要以系統管理員身分執行，以提升您的許可權。

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

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

下表列出預設 RID 值。

內建使用者	RID
DOMAINNAME\Administrator	0x1F4
DOMAINNAME\Guest	0x1F5

內建的全域群組	RID
DOMAINNAME\Domain 系統管理員	0x200
DOMAINNAME\Domain 使用者	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

SecurityIdentifier，可唯一識別 Windows 使用者群組。

傳回

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(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(SecurityIdentifier) 建議使用多載作為判斷使用者角色的較理想多載。

注意

針對內建角色，字串的 role 格式應為「內建 \ RoleNameHere」。例如，若要測試 Windows 系統管理員角色中的成員資格，代表角色的字串應該是 "BUILTIN\Administrators"。請注意，反斜線可能需要經過轉義。下表列出內建角色。

注意

字串格式的內建角色拼寫，與列舉中使用的拼寫不同 WindowsBuiltInRole 。例如，在列舉中，系統管理員的拼寫是「系統管理員」，而不是「系統管理員」。使用此多載時，請使用下表中的角色拼寫。

內建本機群組
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)

參數

傳回

實作

範例

備註

另請參閱

適用於

其他資源