Share via

WindowsPrincipal.IsInRole Methode

  • Referenz

Definition

Namespace:
System.Security.Principal
Assembly:
System.Security.Principal.Windows.dll
Assembly:
mscorlib.dll
Paket:
System.Security.Principal.Windows v5.0.0

Bestimmt, ob der aktuelle Prinzipal zu einer angegebenen Windows-Benutzergruppe gehört.

Überlädt

IsInRole(Int32)

Bestimmt, ob der aktuelle Prinzipal zur Windows-Benutzergruppe mit der angegebenen relativen ID (RID) gehört.
IsInRole(SecurityIdentifier)

Bestimmt, ob der aktuelle Prinzipal zur Windows-Benutzergruppe mit der angegebenen Sicherheits-ID (SID) gehört.
IsInRole(WindowsBuiltInRole)

Bestimmt, ob der aktuelle Prinzipal zu der Windows-Benutzergruppe mit der angegebenen WindowsBuiltInRole gehört.
IsInRole(String)

Bestimmt, ob der aktuelle Prinzipal zu der Windows-Benutzergruppe mit dem angegebenen Namen gehört.

Hinweise

Es gibt vier Überladungen für diese Methode. Aus Leistungsgründen wird die IsInRole(SecurityIdentifier) Überladung dringend empfohlen.

IsInRole(Int32)

Bestimmt, ob der aktuelle Prinzipal zur Windows-Benutzergruppe mit der angegebenen relativen ID (RID) gehört.

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

Parameter

rid
Int32

Die RID der Windows-Benutzergruppe, die auf den Status der Mitgliedschaft des Prinzipals geprüft werden soll.

Gibt zurück

Boolean

true, wenn der aktuelle Prinzipal Mitglied der angegebenen Windows-Benutzergruppe ist, d. h. in einer bestimmten Rolle, andernfalls false.

Beispiele

Im folgenden Codebeispiel wird die Verwendung der IsInRole Methoden veranschaulicht. Die WindowsBuiltInRole Enumeration wird als Quelle für die RIDs verwendet, die die integrierten Rollen identifizieren. Die RIDs werden verwendet, um die Rollen des aktuellen Prinzipals zu bestimmen.

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

Hinweise

Beim Testen auf neu erstellte Rolleninformationen, z. B. einen neuen Benutzer oder eine neue Gruppe, ist es wichtig, sich abzumelden und sich anzumelden, um die Weitergabe von Rolleninformationen innerhalb der Domäne zu erzwingen. Dies kann dazu führen, dass der IsInRole Test zurückgibt false.

Aus Leistungsgründen wird die IsInRole(SecurityIdentifier) Überladung als bevorzugte Überladung zur Bestimmung der Rolle des Benutzers empfohlen.

Hinweis

Unter Windows Vista werden die Berechtigungen eines Benutzers über die Benutzerkontensteuerung (User Account Control, UAC) bestimmt. Als Mitglied der integrierten Administratorgruppe sind Ihnen zwei Zugriffstoken für die Laufzeit zugewiesen: ein Standardbenutzertoken und ein Administratorzugriffstoken. Standardmäßig verwenden Sie die Standardbenutzerrolle. Wenn Sie versuchen, eine Aufgabe auszuführen, die Administratorrechte erfordert, können Sie Ihre Rolle mithilfe des Dialogfelds Zustimmung dynamisch erhöhen. Der Code, der die IsInRole -Methode ausführt, zeigt das Dialogfeld Zustimmung nicht an. Der Code gibt false zurück, wenn Sie sich in der Standardbenutzerrolle befinden, auch wenn Sie sich in der Gruppe Integrierte Administratoren befinden. Sie können Ihre Berechtigungen erhöhen, bevor Sie den Code ausführen, indem Sie mit der rechten Maustaste auf das Anwendungssymbol klicken und angeben, dass Sie als Administrator ausgeführt werden möchten.

Relative Bezeichner (Relative Identifiers, RIDs) sind Komponenten der Sicherheits-ID (SID) einer Windows-Benutzergruppe und werden unterstützt, um plattformübergreifende Lokalisierungsprobleme zu verhindern. Viele Benutzerkonten, lokale Gruppen und globale Gruppen verfügen über einen RID-Standardwert, der für alle Windows-Versionen konstant ist.

Beispielsweise ist die RID für die Rolle BUILTIN\Administrators 0x220. Wenn 0x220 als Eingabeparameter für die IsInRole Methode true verwendet wird, wird zurückgegeben, wenn der aktuelle Prinzipal ein Administrator ist.

In den folgenden Tabellen sind die RID-Standardwerte aufgeführt.

Integrierte Benutzer RID
DOMAINNAME\Administrator 0x1F4
DOMAINNAME\Gast 0x1F5
Integrierte globale Gruppen RID
DOMAINNAME\Domänenadministratoren 0x200
DOMAINNAME\Domänenbenutzer 0x201
DOMAINNAME\Domänengäste 0x202
Integrierte lokale Gruppen RID
BUILTIN\Administrators 0x220
BUILTIN\Users 0x221
BUILTIN\Guests 0x222
BUILTIN\Kontooperatoren 0x224
VORDEFINIERT\Server-Operatoren 0x225
BUILTIN\Print-Operatoren 0x226
VORDEFINIERT\Sicherungs-Operatoren 0x227
BUILTIN\Replicator 0x228

Gilt für:

IsInRole(SecurityIdentifier)

Bestimmt, ob der aktuelle Prinzipal zur Windows-Benutzergruppe mit der angegebenen Sicherheits-ID (SID) gehört.

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

Parameter

sid
SecurityIdentifier

Ein SecurityIdentifier, der eine Windows-Benutzergruppe eindeutig identifiziert.

Gibt zurück

Boolean

true, wenn der aktuelle Prinzipal Mitglied der angegebenen Windows-Benutzergruppe ist, andernfalls false.

Attribute
ComVisibleAttribute

Ausnahmen

ArgumentNullException

sid ist null.

SecurityException

Windows hat einen Win32-Fehler zurückgegeben.

Beispiele

Im folgenden Codebeispiel wird die Verwendung der WindowsPrincipal.IsInRole(SecurityIdentifier) -Methode veranschaulicht. Der BuiltinAdministratorsSid Enumerationswert wird verwendet, um zu bestimmen, ob der aktuelle Prinzipal ein Administrator ist. Das vollständige Codebeispiel finden Sie in der WindowsPrincipal.IsInRole(Int32) -Methode.

// 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

Hinweise

Der SecurityIdentifier identifiziert einen Benutzer oder eine Gruppe unter Windows eindeutig. Beim Testen auf neu erstellte Rolleninformationen, z. B. einen neuen Benutzer oder eine neue Gruppe, ist es wichtig, sich abzumelden und sich anzumelden, um die Weitergabe von Rolleninformationen innerhalb der Domäne zu erzwingen. Dies kann dazu führen, dass der IsInRole Test zurückgibt false.

Hinweis

Unter Windows Vista werden die Berechtigungen eines Benutzers über die Benutzerkontensteuerung (User Account Control, UAC) bestimmt. Als Mitglied der integrierten Administratorgruppe sind Ihnen zwei Zugriffstoken für die Laufzeit zugewiesen: ein Standardbenutzertoken und ein Administratorzugriffstoken. Standardmäßig verwenden Sie die Standardbenutzerrolle. Wenn Sie versuchen, eine Aufgabe auszuführen, die Administratorrechte erfordert, können Sie Ihre Rolle mithilfe des Dialogfelds Zustimmung dynamisch erhöhen. Der Code, der die IsInRole -Methode ausführt, zeigt das Dialogfeld Zustimmung nicht an. Der Code gibt false zurück, wenn Sie sich in der Standardbenutzerrolle befinden, auch wenn Sie sich in der Gruppe Integrierte Administratoren befinden. Sie können Ihre Berechtigungen erhöhen, bevor Sie den Code ausführen, indem Sie mit der rechten Maustaste auf das Anwendungssymbol klicken und angeben, dass Sie als Administrator ausgeführt werden möchten.

Aus Leistungsgründen ist dies die bevorzugte Überladung, um die Rolle eines Benutzers zu bestimmen.

Gilt für:

IsInRole(WindowsBuiltInRole)

Bestimmt, ob der aktuelle Prinzipal zu der Windows-Benutzergruppe mit der angegebenen WindowsBuiltInRole gehört.

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

Parameter

role
WindowsBuiltInRole

Einer der WindowsBuiltInRole-Werte.

Gibt zurück

Boolean

true, wenn der aktuelle Prinzipal Mitglied der angegebenen Windows-Benutzergruppe ist, andernfalls false.

Ausnahmen

ArgumentException

role ist kein gültiger WindowsBuiltInRole-Wert.

Beispiele

Im folgenden Beispiel wird die WindowsBuiltInRole Enumeration verwendet, um zu bestimmen, ob der aktuelle Prinzipal ein Administratorist. Das vollständige Codebeispiel finden Sie in der WindowsPrincipal.IsInRole(Int32) -Methode.

// 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))

Hinweise

Beim Testen auf neu erstellte Rolleninformationen, z. B. einen neuen Benutzer oder eine neue Gruppe, ist es wichtig, sich abzumelden und sich anzumelden, um die Weitergabe von Rolleninformationen innerhalb der Domäne zu erzwingen. Dies kann dazu führen, dass der IsInRole Test zurückgibt false.

Aus Leistungsgründen wird die IsInRole(SecurityIdentifier) Überladung als bevorzugte Überladung zur Bestimmung der Rolle des Benutzers empfohlen.

Hinweis

Unter Windows Vista werden die Berechtigungen eines Benutzers über die Benutzerkontensteuerung (User Account Control, UAC) bestimmt. Als Mitglied der integrierten Administratorgruppe sind Ihnen zwei Zugriffstoken für die Laufzeit zugewiesen: ein Standardbenutzertoken und ein Administratorzugriffstoken. Standardmäßig verwenden Sie die Standardbenutzerrolle. Wenn Sie versuchen, eine Aufgabe auszuführen, die Administratorrechte erfordert, können Sie Ihre Rolle mithilfe des Dialogfelds Zustimmung dynamisch erhöhen. Der Code, der die IsInRole -Methode ausführt, zeigt das Dialogfeld Zustimmung nicht an. Der Code gibt false zurück, wenn Sie sich in der Standardbenutzerrolle befinden, auch wenn Sie sich in der Gruppe Integrierte Administratoren befinden. Sie können Ihre Berechtigungen erhöhen, bevor Sie den Code ausführen, indem Sie mit der rechten Maustaste auf das Anwendungssymbol klicken und angeben, dass Sie als Administrator ausführen möchten.

Gilt für:

IsInRole(String)

Bestimmt, ob der aktuelle Prinzipal zu der Windows-Benutzergruppe mit dem angegebenen Namen gehört.

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

Parameter

role
String

Der Name der Windows-Benutzergruppe, für die die Mitgliedschaft überprüft werden soll.

Gibt zurück

Boolean

true, wenn der aktuelle Prinzipal Mitglied der angegebenen Windows-Benutzergruppe ist, andernfalls false.

Implementiert

IsInRole(String)

Beispiele

Im folgenden Codebeispiel wird die Verwendung der WindowsPrincipal.IsInRole(String) -Methode veranschaulicht.

Die Zeichenfolgen BUILTIN\Administrators und BUILTIN\Users werden verwendet, um zu bestimmen, ob der aktuelle Prinzipal ein Administrator oder ein Benutzer ist. Das vollständige Codebeispiel finden Sie in der WindowsPrincipal.IsInRole(Int32) -Methode.

// 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"))

Hinweise

Beim Testen auf neu erstellte Rolleninformationen, z. B. einen neuen Benutzer oder eine neue Gruppe, ist es wichtig, sich abzumelden und anzumelden, um die Weitergabe von Rolleninformationen innerhalb der Domäne zu erzwingen. Andernfalls kann der IsInRole Test dazu führen, dass zurückgegeben wird false.

Aus Leistungsgründen wird die IsInRole(SecurityIdentifier) Überladung als bevorzugte Überladung zur Bestimmung der Rolle des Benutzers empfohlen.

Hinweis

Unter Windows Vista werden die Berechtigungen eines Benutzers über die Benutzerkontensteuerung (User Account Control, UAC) bestimmt. Als Mitglied der integrierten Administratorgruppe sind Ihnen zwei Zugriffstoken für die Laufzeit zugewiesen: ein Standardbenutzertoken und ein Administratorzugriffstoken. Standardmäßig verwenden Sie die Standardbenutzerrolle. Wenn Sie versuchen, eine Aufgabe auszuführen, die Administratorrechte erfordert, können Sie Ihre Rolle mithilfe des Dialogfelds Zustimmung dynamisch erhöhen. Der Code, der die IsInRole -Methode ausführt, zeigt das Dialogfeld Zustimmung nicht an. Der Code gibt false zurück, wenn Sie sich in der Standardbenutzerrolle befinden, auch wenn Sie sich in der Gruppe Integrierte Administratoren befinden. Sie können Ihre Berechtigungen erhöhen, bevor Sie den Code ausführen, indem Sie mit der rechten Maustaste auf das Anwendungssymbol klicken und angeben, dass Sie als Administrator ausführen möchten.

Bei integrierten Rollen sollte die role Zeichenfolge das Format "BUILTIN\RoleNameHere" aufweisen. Um z. B. die Mitgliedschaft in der Windows-Administratorrolle zu testen, sollte die Zeichenfolge, die die Rolle darstellt, "BUILTIN\Administrators" lauten. Beachten Sie, dass der umgekehrte Schrägstrich möglicherweise mit Escapezeichen versehen werden muss. In der folgenden Tabelle sind die integrierten Rollen aufgeführt.

Hinweis

Die Schreibweise für die BUILTIN-Rollen im Zeichenfolgenformat unterscheidet sich von der Schreibweise, die in der WindowsBuiltInRole Enumeration verwendet wird. Beispielsweise lautet die Schreibweise für einen Administrator in der Enumeration "Administrator", nicht "Administratoren". Wenn Sie diese Überladung verwenden, verwenden Sie die Schreibweise für die Rolle aus der folgenden Tabelle.

Integrierte lokale Gruppen
BUILTIN\Administrators
BUILTIN\Users
BUILTIN\Gäste
BUILTIN\Kontooperatoren
VORDEFINIERT\Server-Operatoren
BUILTIN\Print-Operatoren
VORDEFINIERT\Sicherungs-Operatoren
BUILTIN\Replicator

Für computerspezifische Rollen sollte die role Zeichenfolge das Format "MachineName\RoleNameHere" aufweisen.

Für domänenspezifische Rollen sollte die role Zeichenfolge das Format "DomainName\RoleNameHere" aufweisen, "SomeDomain\Domain Usersz. B. ".

Hinweis

In der .NET Framework Version 1.0 wird beim role Parameter die Groß-/Kleinschreibung beachtet. In der .NET Framework Version 1.1 und höher wird beim role Parameter die Groß-/Kleinschreibung nicht beachtet.

Weitere Informationen

Gilt für: