Udostępnij za pośrednictwem

  • Artykuł

Calling Exchange Management Shell Cmdlets from Managed Code

This section contains three examples that show how methods can use Exchange Management Shell cmdlets from an application.

The examples in this section use the following methods:

  • GetUsersUsingBasicAuth – Creates an Exchange Management Shell runspace on a remote server by using Windows basic authentication. This method returns a collection of PSObject instances that represent Microsoft Exchange Server 2010 mailbox users.

  • GetUsersUsingCertificate – Creates an Exchange Management Shell runspace on a remote server by using certificate authentication. This method returns a collection of PSObject instances that represent Exchange mailbox users.

  • GetUsersUsingKerberos – Creates an Exchange Management Shell runspace on a remote server by using Kerberos authentication. This method returns a collection of PSObject instances that represent Exchange mailbox users.

  • GetUsersUsingNegotiatedAuth – Creates an Exchange Management Shell runspace on a remote server by using negotiated authentication. This method returns a collection of PSObject instances that represent Exchange mailbox users.

  • GetUserInformation – Returns a collection of PSObject instances that represent Exchange mailbox users. This method is called by both the GetUsersUsingLiveID and GetUsersUsingCertificate methods.

The examples in this section require a reference to the following namespaces:

  • System.Collections.ObjectModel

  • System.Management.Automation

  • System.Management.Automation.Remoting

  • System.Management.Automation.Runspaces

Note

When you are using Microsoft Visual Studio to create an application, you must add a reference to the System.Mangagement.Automation.dll assembly to the project. The assembly can be found in one of the following locations:

  • For the Windows XP and Windows Vista operating systems, in the Windows PowerShell installation directory ($PSHOME).

  • For the Windows 7 operating system, in the following folder: Windows\assembly\GAC_MSIL\System.Management.Automation.

Getting a List of Mailbox Users by Using Basic Authentication

The following code example shows a method that creates an Exchange Management Shell runspace on a remote server. The method then calls the GetUserInformation method to return a list of users on the remote server.

This method requires the following parameters:

  • liveIDConnectionUri – A string that contains the URI of the server that will authenticate the application.

  • schemaUri – A string that contains the URI of the schema document that defines the Exchange Management Shell schema.

  • credentials – A PSCredential object that contains the credentials of the user who is running the application.

  • count – The number of Exchange mailbox users to return.

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

Note

The following is the URI of the Exchange Management Shell schema: https://schemas.microsoft.com/powershell/Microsoft.Exchange.

Getting a List of Mailbox Users by Using Certificate Authentication

The following code example shows a method that creates an Exchange Management Shell runspace on a remote server. The method then calls the GetUserInformation method to return a list of users on the remote server.

This method requires the following parameters:

  • thumbprint – A string that contains the thumbprint of the certificate that is used to authenticate the application.

  • certConnectionUri – A string that contains the URI of the server that will authenticate the certificate.

  • schemaUri – A string that contains the URI of the schema document that defines the Exchange Management Shell schema.

  • count – The number of Exchange mailbox users to return.

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

Note

The following is the URI of the Exchange Management Shell schema: https://schemas.microsoft.com/powershell/Microsoft.Exchange.

Getting a List of Mailbox Users by Using Kerberos Authentication

The following code example shows a method that creates an Exchange Management Shell runspace on a remote server. The method then calls the GetUserInformation method to return a list of users on the remote server.

This method requires the following parameters:

  • kerberosUri – A string that contains the URI of the Kerberos server that will authenticate the application.

  • schemaUri – A string that contains the URI of the schema document that defines the Exchange Management Shell schema.

  • credentials – A PSCredential object that contains the credentials of the user who is running the application.

  • count – The number of Exchange mailbox users to return.

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

Getting a List of Users by Using Negotiated Authentication

The following code example shows a method that creates an Exchange Management Shell runspace on a remote server. The method then calls the GetUserInformation method to return a list of users on the remote server.

This method requires the following parameters:

  • targetUri – A string that contains the URI of the server that will authenticate the application.

  • schemaUri – A string that contains the URI of the schema document that defines the Exchange Management Shell schema.

  • credentials – A PSCredential object that contains the credentials of the user who is running the application.

  • count – The number of Exchange mailbox users to return.

public Collection<PSObject> GetUsersUsingNegotiatedAuth(int count, PSCredential credential)
{
  WSManConnectionInfo connectionInfo = new WSManConnectionInfo(
    new Uri(targetUri),
    schemaUri, credentials);

   connectionInfo.AuthenticationMechanism = AuthenticationMechanism.Negotiate;

  using (Runspace runspace = RunspaceFactory.CreateRunspace(connectionInfo))
  {
    return GetUserInformation(count, runspace);
  }
}

  Function GetUsersUsingNegotiatedAuth( _
    ByVal targetUri 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(targetUri), ScehmaUri, Credentials)
    ConnectionInfo.AuthenticationMechanism = AuthenticationMechanism.Negotiated

    Dim RemoteRunspace As Runspace
    RemoteRunspace = RunspaceFactory.CreateRunspace(ConnectionInfo)

    Return GetUserInformation(Count, RemoteRunspace)

  End Function

Getting a List of Users from a Remote Runspace

The following code example shows a method that returns a collection of PSObject instances that represent Exchange mailbox users. This method is called by the GetUsersUsingBasicAuth, GetUsersUsingCertificate, and GetUsersUsingKerberos methods to return the list of users from the remote server.

This method requires the following parameters:

  • count – The number of Exchange mailbox users to return.

  • runspace – The remote runspace that is established for the remote Exchange server.

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

The GetUserInformation method will return no more than count mailbox users. To simplify the code for this example, the method does not filter or otherwise limit the mailbox users that are returned.