Share via

WindowsPrincipal.IsInRole Método

  • Referência

Definição

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

Determina se a entidade de segurança atual pertence a um grupo de usuário do Windows especificado.

Sobrecargas

IsInRole(Int32)

Determina se a entidade de segurança atual pertence ao grupo de usuários do Windows com o RID (identificador relativo) especificado.
IsInRole(SecurityIdentifier)

Determina se a entidade de segurança atual pertence ao grupo de usuários do Windows com o SID (identificador de segurança) especificado.
IsInRole(WindowsBuiltInRole)

Determina se a entidade atual pertence ao grupo de usuários do Windows com o WindowsBuiltInRole especificado.
IsInRole(String)

Determina se a entidade de segurança atual pertence ao grupo de usuários do Windows com o nome especificado.

Comentários

Há quatro sobrecargas para esse método. Por motivos de desempenho, a IsInRole(SecurityIdentifier) sobrecarga é altamente recomendada.

IsInRole(Int32)

Determina se a entidade de segurança atual pertence ao grupo de usuários do Windows com o RID (identificador relativo) especificado.

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

Parâmetros

rid
Int32

O RID do grupo de usuários do Windows no qual o status de associação da entidade de segurança deve ser verificado.

Retornos

Boolean

true se a entidade de segurança atual for membro do grupo de usuários do Windows especificado, ou seja, em uma função específica, caso contrário, false.

Exemplos

O exemplo de código a seguir demonstra o uso dos IsInRole métodos. A WindowsBuiltInRole enumeração é usada como a origem dos RIDs que identificam as funções internas. Os RIDs são usados para determinar as funções da entidade de segurança atual.

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

Comentários

Ao testar as informações de função recém-criadas, como um novo usuário ou um novo grupo, é importante fazer logoff e fazer logon para forçar a propagação de informações de função dentro do domínio. Não fazer isso pode fazer com que o IsInRole teste retorne false.

Por motivos de desempenho, a IsInRole(SecurityIdentifier) sobrecarga é recomendada como a sobrecarga preferível para determinar a função do usuário.

Observação

No Windows Vista, o UAC (Controle de Conta de Usuário) determina os privilégios de um usuário. Se for um membro do grupo Administradores Internos, você receberá dois tokens de acesso do tempo de execução: um token de acesso do usuário padrão e um token de acesso do administrador. Por padrão, você está na função de usuário padrão. Ao tentar executar uma tarefa que requer privilégios administrativos, você pode elevar dinamicamente sua função usando a caixa de diálogo Consentimento. O código que executa o IsInRole método não exibe a caixa de diálogo Consentimento. O código retornará false se você estiver na função de usuário padrão, mesmo que você esteja no grupo Administradores Internos. Você pode elevar seus privilégios antes de executar o código clicando com o botão direito do mouse no ícone do aplicativo e indicando que deseja executar como administrador.

Os RIDs (identificadores relativos) são componentes do SID (identificador de segurança) de um grupo de usuários do Windows e têm suporte para ajudar a evitar problemas de localização multiplataforma. Muitas contas de usuário, grupos locais e grupos globais têm um valor RID padrão que é constante em todas as versões do Windows.

Por exemplo, o RID para a função BUILTIN\Administrators é 0x220. Usar 0x220 como o parâmetro de entrada para o IsInRole método resultará no true retorno se a entidade de segurança atual for um administrador.

As tabelas a seguir listam os valores RID padrão.

Usuários internos RID
DOMAINNAME\Administrator 0x1F4
DOMAINNAME\Guest 0x1F5
Grupos globais internos RID
DOMAINNAME\Domain Admins 0x200
DOMAINNAME\Domain Users 0x201
DOMAINNAME\Domain Guests 0x202
Grupos locais internos RID
BUILTIN\Administradores 0x220
BUILTIN\Users 0x221
BUILTIN\Guests 0x222
OPERADORES BUILTIN\Account 0x224
BUILTIN\Operadores de servidor 0x225
OPERADORES BUILTIN\Print 0x226
BUILTIN\Operadores de Backup 0x227
BUILTIN\Replicator 0x228

Aplica-se a

IsInRole(SecurityIdentifier)

Determina se a entidade de segurança atual pertence ao grupo de usuários do Windows com o SID (identificador de segurança) especificado.

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

Parâmetros

sid
SecurityIdentifier

Um SecurityIdentifier que identifica exclusivamente um grupo de usuários do Windows.

Retornos

Boolean

true se a entidade de segurança atual for membro do grupo de usuários do Windows especificado; caso contrário, false.

Atributos
ComVisibleAttribute

Exceções

ArgumentNullException

sid é null.

SecurityException

O Windows retornou um erro do Win32.

Exemplos

O exemplo de código a seguir demonstra o uso do WindowsPrincipal.IsInRole(SecurityIdentifier) método . O BuiltinAdministratorsSid valor de enumeração é usado para determinar se a entidade de segurança atual é um administrador. Para obter o exemplo de código completo, consulte o WindowsPrincipal.IsInRole(Int32) método .

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

Comentários

O SecurityIdentifier identifica exclusivamente um usuário ou grupo no Windows. Ao testar as informações de função recém-criadas, como um novo usuário ou um novo grupo, é importante fazer logoff e fazer logon para forçar a propagação de informações de função dentro do domínio. Não fazer isso pode fazer com que o IsInRole teste retorne false.

Observação

No Windows Vista, o UAC (Controle de Conta de Usuário) determina os privilégios de um usuário. Se for um membro do grupo Administradores Internos, você receberá dois tokens de acesso do tempo de execução: um token de acesso do usuário padrão e um token de acesso do administrador. Por padrão, você está na função de usuário padrão. Ao tentar executar uma tarefa que requer privilégios administrativos, você pode elevar dinamicamente sua função usando a caixa de diálogo Consentimento. O código que executa o IsInRole método não exibe a caixa de diálogo Consentimento. O código retornará false se você estiver na função de usuário padrão, mesmo que você esteja no grupo Administradores Internos. Você pode elevar seus privilégios antes de executar o código clicando com o botão direito do mouse no ícone do aplicativo e indicando que deseja executar como administrador.

Por motivos de desempenho, essa é a sobrecarga preferível para determinar a função de um usuário.

Aplica-se a

IsInRole(WindowsBuiltInRole)

Determina se a entidade atual pertence ao grupo de usuários do Windows com o WindowsBuiltInRole especificado.

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

Parâmetros

role
WindowsBuiltInRole

Um dos valores de WindowsBuiltInRole.

Retornos

Boolean

true se a entidade de segurança atual for membro do grupo de usuários do Windows especificado; caso contrário, false.

Exceções

ArgumentException

role não é um valor WindowsBuiltInRole válido.

Exemplos

O exemplo a seguir usa a WindowsBuiltInRole enumeração usada para determinar se a entidade de segurança atual é um Administrator. Para obter o exemplo de código completo, consulte o WindowsPrincipal.IsInRole(Int32) método .

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

Comentários

Ao testar as informações de função recém-criadas, como um novo usuário ou um novo grupo, é importante fazer logoff e fazer logon para forçar a propagação de informações de função dentro do domínio. Não fazer isso pode fazer com que o IsInRole teste retorne false.

Por motivos de desempenho, a IsInRole(SecurityIdentifier) sobrecarga é recomendada como a sobrecarga preferível para determinar a função do usuário.

Observação

No Windows Vista, o UAC (Controle de Conta de Usuário) determina os privilégios de um usuário. Se for um membro do grupo Administradores Internos, você receberá dois tokens de acesso do tempo de execução: um token de acesso do usuário padrão e um token de acesso do administrador. Por padrão, você está na função de usuário padrão. Ao tentar executar uma tarefa que requer privilégios administrativos, você pode elevar dinamicamente sua função usando a caixa de diálogo Consentimento. O código que executa o IsInRole método não exibe a caixa de diálogo Consentimento. O código retornará false se você estiver na função de usuário padrão, mesmo que você esteja no grupo Administradores Internos. Você pode elevar seus privilégios antes de executar o código clicando com o botão direito do mouse no ícone do aplicativo e indicando que deseja executar como administrador.

Aplica-se a

IsInRole(String)

Determina se a entidade de segurança atual pertence ao grupo de usuários do Windows com o nome especificado.

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

Parâmetros

role
String

O nome do grupo de usuários do Windows para o qual verificar a associação.

Retornos

Boolean

true se a entidade de segurança atual for membro do grupo de usuários do Windows especificado; caso contrário, false.

Implementações

IsInRole(String)

Exemplos

O exemplo de código a seguir demonstra o uso do WindowsPrincipal.IsInRole(String) método .

As cadeias de caracteres e BUILTIN\Users são usadas BUILTIN\Administrators para determinar se a entidade de segurança atual é um administrador ou um usuário. Para obter o exemplo de código completo, consulte o WindowsPrincipal.IsInRole(Int32) método .

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

Comentários

Ao testar informações de função recém-criadas, como um novo usuário ou um novo grupo, é importante fazer logoff e fazer logon para forçar a propagação de informações de função dentro do domínio. Não fazer isso pode fazer com que o IsInRole teste retorne false.

Por motivos de desempenho, a IsInRole(SecurityIdentifier) sobrecarga é recomendada como a sobrecarga preferível para determinar a função do usuário.

Observação

No Windows Vista, o UAC (Controle de Conta de Usuário) determina os privilégios de um usuário. Se for um membro do grupo Administradores Internos, você receberá dois tokens de acesso do tempo de execução: um token de acesso do usuário padrão e um token de acesso do administrador. Por padrão, você está na função de usuário padrão. Ao tentar executar uma tarefa que exige privilégios administrativos, você pode elevar dinamicamente sua função usando a caixa de diálogo Consentimento. O código que executa o IsInRole método não exibe a caixa de diálogo Consentimento. O código retornará false se você estiver na função de usuário padrão, mesmo que você esteja no grupo Administradores Internos. Você pode elevar seus privilégios antes de executar o código clicando com o botão direito do mouse no ícone do aplicativo e indicando que deseja executar como administrador.

Para funções internas, a role cadeia de caracteres deve estar no formato "BUILTIN\RoleNameHere". Por exemplo, para testar a associação na função de administrador do Windows, a cadeia de caracteres que representa a função deve ser "BUILTIN\Administrators". Observe que a barra invertida pode precisar ser escapada. A tabela a seguir lista as funções internas.

Observação

A ortografia das funções BUILTIN no formato de cadeia de caracteres difere da ortografia usada na WindowsBuiltInRole enumeração . Por exemplo, a ortografia de um administrador na enumeração é "Administrador", não "Administradores". Ao usar essa sobrecarga, use a ortografia para a função da tabela a seguir.

Grupos locais internos
BUILTIN\Administradores
BUILTIN\Users
BUILTIN\Guests
OPERADORES BUILTIN\Account
BUILTIN\Operadores de servidor
OPERADORES BUILTIN\Print
BUILTIN\Operadores de Backup
BUILTIN\Replicator

Para funções específicas do computador, a role cadeia de caracteres deve estar no formato "MachineName\RoleNameHere".

Para funções específicas do domínio, a role cadeia de caracteres deve estar no formato "DomainName\RoleNameHere"; por exemplo, "SomeDomain\Domain Users".

Observação

No .NET Framework versão 1.0, o role parâmetro diferencia maiúsculas de minúsculas. No .NET Framework versão 1.1 e posterior, o role parâmetro não diferencia maiúsculas de minúsculas.

Confira também

Aplica-se a