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

(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 Guest	0x202

內建本地組	RID
BUILTIN\Administrators	0x220
BUILTIN\Users	0x221
BUILTIN\Guest	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 測試傳回 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\Guest
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)

參數

傳回

實作

範例

備註

另請參閱

適用於

其他資源