共用方式為


WindowsPrincipal.IsInRole 方法

定義

判斷目前的主體是否屬於指定的 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 是用來檢查主體的成員狀態。

傳回

如果目前主體是指定之 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 使用者群組。

傳回

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

屬性

例外狀況

sidnull

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

注意

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

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

適用於

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 值。

傳回

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

例外狀況

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 群組的成員,系統會將兩個執行階段存取語彙基元 (Token) 指派給您:標準使用者存取語彙基元及管理員存取語彙基元。 根據預設,您會屬於標準使用者角色。 當您嘗試執行需要系統管理許可權的工作時,您可以使用 [同意] 對話框動態提升角色。 執行 方法的程式 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 使用者群組的名稱。

傳回

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

實作

範例

下列程式代碼範例示範 如何使用 WindowsPrincipal.IsInRole(String) 方法。

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

針對內建角色, 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 參數不區分大小寫。

另請參閱

適用於