Compartilhar via

Obter uma lista de usuários de email usando o Shell de Gerenciamento do Exchange

  • Artigo

Saiba como usar cmdlets do Shell de Gerenciamento do Exchange para criar uma ferramenta que retorna uma lista de usuários de caixa de correio do Exchange.

Aplica-se a: Exchange Online | Exchange Server 2013 | Office 365

Obter uma lista de usuários do Exchange Online, do Exchange Online como parte do Office 365 ou de uma versão do Exchange a partir do Exchange 2013 usando uma ferramenta gerenciada que chama um cmdlet do Shell de Gerenciamento do Exchange é um processo de duas etapas. Primeiro, você estabelece um runspace remoto em um servidor Exchange; em seguida, execute o cmdlet para recuperar as informações do usuário no runspace remoto.

Para se conectar ao runspace remoto, você precisa autenticar com o servidor Exchange usando o esquema de autenticação que atende aos requisitos de segurança da sua organização.

Este artigo fornece exemplos de código que você pode usar para configurar um runspace remoto e executar um cmdlet do Shell de Gerenciamento do Exchange para obter uma lista de usuários de um servidor Exchange.

Pré-requisitos para obter uma lista de usuários de caixa de correio

Para executar essa tarefa, você precisa de uma referência aos seguintes namespaces:

  • System.Collections.ObjectModel
  • System.Management.Automation
  • System.Management.Automation.Remoting
  • System.Management.Automation.Runspaces

Observação

Ao usar o Visual Studio para criar um aplicativo, você deve adicionar uma referência ao assembly System.Management.Automation.dll ao projeto. O assembly pode ser encontrado em um dos seguintes locais:

  • Para sistemas operacionais Windows XP e Windows Vista, o Windows PowerShell de instalação ($PSHOME).
  • Para os sistemas operacionais Windows 7 e Windows 8, a seguinte pasta: Windows\assembly\GAC_MSIL\System.Management.Automation.

Não carregue o snap-in Gerenciamento do Exchange 2013 no runspace em computadores que executam aplicativos que automatizam cmdlets do Shell de Gerenciamento do Exchange. Em vez disso, o aplicativo deve criar um runspace remoto, conforme descrito posteriormente neste artigo.

Conectar-se a um runspace remoto em um servidor Exchange

O método que você usa para se conectar a um runspace remoto para usar um cmdlet do Shell de Gerenciamento do Exchange varia de acordo com o esquema de autenticação que você está usando. Esta seção fornece exemplos de código que mostram como se conectar a um runspace remoto quando você está usando um método de autenticação listado na tabela a seguir.

Método de autenticação Aplica-se a URI
Conecte-se a um runspace remoto no Exchange Online usando a autenticação básica Servidores do Exchange Online https://outlook.office365.com/PowerShell-LiveID
https://<server>/PowerShell-LiveID
Conectar-se a um runspace remoto usando a autenticação de certificado Servidores locais do Exchange Online e do Exchange https://outlook.office365.com/PowerShell
https://<server>/PowerShell
http://<server>/PowerShell
Conectar a um runspace remoto em um servidor Exchange usando a autenticação Kerberos Servidores locais do Exchange Online e do Exchange https://<server>/PowerShell
http://<server>/PowerShell

Conectar-se a um runspace remoto no Exchange Online usando a autenticação básica

O exemplo de código a seguir define o método GetUsersUsingBasicAuth, que cria um runspace do Shell de Gerenciamento do Exchange em um servidor remoto do Exchange Online usando a autenticação básica. O método chama o método GetUserInformation, conforme definido na seção Obter uma lista de usuários de caixa de correio de um runspace remoto, para retornar uma lista de usuários no servidor remoto.

Esse método requer os seguintes parâmetros:

  • liveIDConnectionUri – Uma cadeia de caracteres que contém o URI do servidor Exchange Online que autenticará o aplicativo. Se o Exchange Online estiver em execução no Office 365, o URI será https://outlook.office365.com/PowerShell-LiveID; caso contrário, o URI será https://<servername>/PowerShell-LiveID.
  • schemaUri – Uma cadeia de caracteres que contém o URI do documento de esquema que define o esquema do Shell de Gerenciamento do Exchange. O URI do esquema é https://schemas.microsoft.com/powershell/Microsoft.Exchange.
  • credenciais – um objeto PSCredential que contém as credenciais do usuário que está executando o aplicativo.
  • contagem – o número de usuários da caixa de correio do Exchange a ser retornado.
public Collection<PSObject> GetUsersUsingBasicAuth(
    string liveIDConnectionUri, string schemaUri, PSCredential credentials, int count)
{
    WSManConnectionInfo connectionInfo = new WSManConnectionInfo(
        new Uri(liveIDConnectionUri),
        schemaUri, credentials);
    connectionInfo.AuthenticationMechanism = AuthenticationMechanism.Basic;
    using (Runspace runspace = RunspaceFactory.CreateRunspace(connectionInfo))
    {
        return GetUserInformation(count, runspace);
    }
}

  Function GetUsersUsingBasicAuth( _
    ByVal LiveIDConnectionUri As String, ByVal ScehmaUri As String, _
    ByVal Credentials As PSCredential, ByVal Count As Integer) As Collection(Of PSObject)
    Dim ConnectionInfo As WSManConnectionInfo = _
        New WSManConnectionInfo(New Uri(LiveIDConnectionUri), ScehmaUri, Credentials)
    ConnectionInfo.AuthenticationMechanism = AuthenticationMechanism.Basic
    Dim RemoteRunspace As Runspace
    RemoteRunspace = RunspaceFactory.CreateRunspace(ConnectionInfo)
    Return GetUserInformation(Count, RemoteRunspace)
  End Function

Conectar-se a um runspace remoto usando a autenticação de certificado

O exemplo de código a seguir define o método GetUsersUsingCertificate, que cria um runspace do Shell de Gerenciamento do Exchange em um servidor remoto usando um certificado. O método chama o método GetUserInformation, conforme definido na seção Obter uma lista de usuários de caixa de correio de um runspace remoto, para retornar uma lista de usuários no servidor remoto.

Esse método requer os seguintes parâmetros:

  • impressão digital – uma cadeia de caracteres que contém a impressão digital do certificado usado para autenticar o aplicativo.

  • certConnectionUri – Uma cadeia de caracteres que contém o URI do servidor que autenticará o certificado. O URI será um dos listados na tabela a seguir.

    Tabela 1. URIs certConnectionUri

    Server URI
    Servidor Exchange sem usar SSL http://<servername>/PowerShell
    Servidor Exchange usando SSL https://<servername>/PowerShell
    Exchange Online como parte do Office 365 https://outlook.office365.com/PowerShell

  • schemaUri – Uma cadeia de caracteres que contém o URI do documento de esquema que define o esquema do Shell de Gerenciamento do Exchange. O URI do esquema é https://schemas.microsoft.com/powershell/Microsoft.Exchange.

  • contagem – o número de usuários da caixa de correio do Exchange a ser retornado.

public Collection<PSObject> GetUsersUsingCertificate(
    string thumbprint, string certConnectionUri, string schemaUri, int count)
{
    WSManConnectionInfo connectionInfo = new WSManConnectionInfo(
        new Uri(certConnectionUri),
        schemaUri,
        thumbprint)
    using (Runspace runspace = RunspaceFactory.CreateRunspace(connectionInfo))
    {
        return GetUserInformation(count, runspace);
    }
}

  Function GetUsersUsingCertificate( _
    ByVal Thumbprint As String, ByVal CertConnectionUri As String, _
    ByVal SchemaUri As String, ByVal Count As Integer) As Collection(Of PSObject)
    Dim ConnectionInfo As WSManConnectionInfo
    ConnectionInfo = New WSManConnectionInfo(New Uri(CertConnectionUri), SchemaUri, Thumbprint)
    Dim RemoteRunspace As Runspace
    RemoteRunspace = RunspaceFactory.CreateRunspace(ConnectionInfo)
    Return GetUserInformation(Count, RemoteRunspace)
  End Function

Conectar-se a um runspace remoto em um servidor Exchange usando a autenticação Kerberos

O exemplo de código a seguir define o método GetUsersUsingKerberos, que cria um runspace do Shell de Gerenciamento do Exchange em um servidor remoto usando a autenticação Kerberos. O método chama o método GetUserInformation, conforme definido na seção Obter uma lista de usuários de caixa de correio de um runspace remoto, para retornar uma lista de usuários no servidor remoto.

Esse método requer os seguintes parâmetros:

  • kerberosUri – uma cadeia de caracteres que contém o URI do servidor Kerberos que autenticará o aplicativo. O URI será um dos listados na tabela a seguir.

    Tabela 2. URIs kerberosUri

    Server URI
    Servidor Exchange sem usar SSL http://<servername>/PowerShell
    Servidor Exchange usando SSL https://<servername>/PowerShell

  • schemaUri – Uma cadeia de caracteres que contém o URI do documento de esquema que define o esquema do Shell de Gerenciamento do Exchange. O URI do esquema é https://schemas.microsoft.com/powershell/Microsoft.Exchange.

  • credenciais – um objeto PSCredential que contém as credenciais do usuário que está executando o aplicativo.

  • contagem – o número de usuários da caixa de correio do Exchange a ser retornado.

public Collection<PSObject> GetUsersUsingKerberos(
    string kerberosUri, string schemaUri, PSCredential credentials, int count)
{
    WSManConnectionInfo connectionInfo = new WSManConnectionInfo(
        new Uri(kerberosUri),
        schemaUri, credentials);
    connectionInfo.AuthenticationMechanism = AuthenticationMechanism.Kerberos;
    using (Runspace runspace = RunspaceFactory.CreateRunspace(connectionInfo))
    {
        return GetUserInformation(count, runspace);
    }
}

  Function GetUsersUsingKerberos( _
    ByVal KerberosUri As String, ByVal ScehmaUri As String, _
    ByVal Credentials As PSCredential, ByVal Count As Integer) As Collection(Of PSObject)
    Dim ConnectionInfo As WSManConnectionInfo = _
        New WSManConnectionInfo(New Uri(KerberosUri), ScehmaUri, Credentials)
    ConnectionInfo.AuthenticationMechanism = AuthenticationMechanism.Kerberos
    Dim RemoteRunspace As Runspace
    RemoteRunspace = RunspaceFactory.CreateRunspace(ConnectionInfo)
    Return GetUserInformation(Count, RemoteRunspace)
  End Function

Obter uma lista de usuários de caixa de correio de um runspace remoto

O exemplo de código a seguir define o método GetUserInformation, que retorna uma coleção de instâncias do PSObject que representam os usuários da caixa de correio do Exchange. Esse método é chamado pelos métodos GetUsersUsingBasicAuth, GetUsersUsingCertificate e GetUsersUsingKerberos para retornar a lista de usuários do servidor remoto.

Esse método requer os seguintes parâmetros:

  • contagem – o número de usuários da caixa de correio do Exchange a ser retornado.
  • runspace – o runspace remoto estabelecido para o servidor remoto do Exchange.
public Collection<PSObject> GetUserInformation(int count, Runspace runspace)
{
    using (PowerShell powershell = PowerShell.Create())
    {
        powershell.AddCommand("Get-Users");
        powershell.AddParameter("ResultSize", count);
        runspace.Open();
        powershell.Runspace = runspace;
        return powershell.Invoke();
    }
}

Function GetUserInformation(ByVal Count As Integer, ByVal RemoteRunspace As Runspace) As Collection(Of PSObject)
    Dim RemotePowerShell As PowerShell = PowerShell.Create
    RemotePowerShell.AddCommand("Get-Users")
    RemotePowerShell.AddParameter("ResultSize", Count)
    ' Open the remote runspace on the server.
    RemoteRunspace.Open()
    ' Associate the runspace with the Exchange Management Shell.
    RemotePowerShell.Runspace = RemoteRunspace
    ' Invoke the Exchange Management Shell to run the command.
    Return RemotePowerShell.Invoke
End Function

O método GetUserInformation não retornará mais do que contar usuários de caixa de correio. Para simplificar o código para este exemplo, o método não filtra nem limita os usuários de caixa de correio retornados.

Confira também