Use PowerShell cmdlets for XRM tooling to connect to CRM

  • Article

 

Applies To: Dynamics CRM 2013

XRM tooling provides you with couple of Windows PowerShell cmdlets to connect to Microsoft Dynamics CRM and retrieve organizations that the current user has access to: Get-CrmConnection and Get-CrmOrganizations.

In This Topic

Prerequisites

Register the cmdlets

Use the cmdlet to retrieve organizations from your CRM server

Use the cmdlet to connect to CRM

Prerequisites

  • You need a version of PowerShell that is no earlier than version 3.0 to use the XRM tooling cmdlets. To check your PowerShell version, open a PowerShell window and run the following command: $Host

  • Set the execution policy to run the signed PowerShell scripts. To do so, open a PowerShell window as an administrator and run the following command: Set-ExecutionPolicy -ExecutionPolicy AllSigned

Register the cmdlets

You must register the PowerShell cmdlets for XRM tooling before you can use it.

  1. Download the CRM SDK package, and run the package file to extract the contents of the package. Let’s assume that you extracted the package to the c:\ drive on your computer. The PowerShell assembly (Microsoft.Xrm.Tooling.CrmConnector.Powershell.dll) and the script (RegisterXRMTooling.ps1) for registering the cmdlets become available at the following location: c:\SDK\bin.

  2. Start Windows PowerShell on your computer with elevated privileges (run as administrator).

  3. At the prompt in the PowerShell window, change your directory to the folder that contains the PowerShell dll file and the script for registering the cmdlets. In this case:

    cd c:\SDK\bin

  4. Run the RegisterXRMTooling.ps1 script to register the XRM Tooling PowerShell assembly, and install the Windows PowerShell snap-in. Type the following command, and press ENTER:

    .\RegisterXRMTooling.ps1

  5. Add the Windows PowerShell snap-in for XRM tooling. This registers the Get-CrmConnection and Get-CrmOrganizations cmdlets.

    Add-PSSnapin Microsoft.Xrm.Tooling.Connector

You are now ready to use these Windows PowerShell cmdlets. To list the cmdlets that you registered, run the following command at the prompt in the Windows PowerShell window:

Get-Help “Crm”

Use the cmdlet to retrieve organizations from your CRM server

Use the Get-CrmOrganizations cmdlet to retrieve the organizations that you have access to.

  1. Provide your credentials to connect to your Microsoft Dynamics CRM (on-premises) or Microsoft Dynamics CRM Online instance. Running the following command will prompt you to type your user name and password to connect to the CRM instance, and it will be stored in the $Cred variable.

    $Cred = Get-Credential

  2. Use the following command to retrieve your organizations, and store the information in the $CRMOrgs variable:

    • If you’re connecting to the Microsoft Dynamics CRM (on-premises) server:

      $CRMOrgs = Get-CrmOrganizations –ServerUrl http://<CRM_Server_Host> –Credential $Cred

    • If you’re connecting to the Microsoft Dynamics CRM Online instance:

      $CRMOrgs = Get-CrmOrganizations -Credential $Cred -DeploymentRegion NorthAmerica –OnlineType Office365

      Note

      For the DeploymentRegion parameter, valid values are NorthAmerica, EMEA, and APAC. For the OnlineType parameter, valid values are Office365 and LiveID.

    • If you’re connecting to the CRM server using the claims-based authentication against the specified Home realm:

      $CRMOrgs = Get-CrmOrganizations –ServerUrl http://<CRM_Server_Host> –Credential $Cred –HomRealmURL http://<Identity_Provider_Address>

  3. Your supplied credentials are validated when you run the command in step 2. On successful execution of the command, type the following command, and press ENTER to display the organizations that you have access to:

    $CRMOrgs

    List of organizations returned by the cmdlet

    Tip

    You can use the variable used to store the retrieved CRM organizations (in this case $CRMOrgs) with the Get-CrmConnection cmdlet to connect to CRM. To specify the org name, use the following command: $CRMOrgs.UniqueName.

    If there is more than one organization value stored in the $CRMOrgs variable, you can refer to the nth organization using the following command: $CRMOrgs[n-1]. For example, to refer to the unique name of the third organization in the $CRMOrgs variable (”MyOrg”), use the following command: $CRMOrgs[2].UniqueName. For more information about values in an array in PowerShell, see Accessing Values in an Array.

Use the cmdlet to connect to CRM

Use the Get-CrmConnection cmdlet to connect to a CRM instance. The cmdlet lets you either use the XRM tooling common login control to specify your credentials and connect to CRM or lets you specify your credentials as inline parameters. For more information about the common login control, see Use the XRM tooling common login control in your client applications.

Connect to CRM using the common login control

  1. If you want to use the common login control to provide your credentials to connect to your CRM instance, use the following command. The connection information is stored in the $CRMConn variable so that you can use it later.

    $CRMConn = Get-CrmConnection -InteractiveMode

  2. The LoginControl dialog box appears. Provide your credentials to connect to your CRM instance, and click Login.

Connect to CRM by specifying credentials inline

  1. Use the following command to get a connection to your Microsoft Dynamics CRM (on-premises) or Microsoft Dynamics CRM Online instance. We are using the $Cred variable that was created earlier to store the credential while retrieving the organizations. The connection information will be stored in the $CRMConn variable:

    • If you’re connecting to the Microsoft Dynamics CRM (on-premises) server:

      $CRMConn = Get-CrmConnection –ServerUrl http://<CRM_Server_Host> -Credential $Cred -OrganizationName <OrgName>

    • If you’re connecting to the Microsoft Dynamics CRM Online instance:

      $CRMConn = Get-CrmConnection -Credential $Cred -DeploymentRegion NorthAmerica –OnlineType Office365 –OrganizationName <OrgName>

      Note

      For the DeploymentRegion parameter, valid values are NorthAmerica, EMEA, and APAC. For the OnlineType parameter, valid values are Office365 and LiveID.

    • If you’re connecting to the CRM server using the claims-based authentication against the specified Home realm:

      $CRMConn = Get-CrmConnection –ServerUrl http://<CRM_Server_Host> -Credential $Cred -OrganizationName <OrgName> –HomRealmURL http://<Identity_Provider_Address>

    Note

    For the OrganizationName parameter in all the preceding commands, you can either specify the organization unique name or friendly name. You can also use the organization unique name or friendly name that you retrieved using the Get-CrmOrganizations cmdlet and stored in the $CRMOrgs variable. For example: $CRMOrgs[x].UniqueName or $CRMOrgs[x].FriendlyName.

  2. Your supplied credentials are validated when you run the command in step 2. On successful execution of the cmdlet, type the following command, and press ENTER to display the connection information and status:

    $CRMConn

    CRM connection information and status

See Also

Use XRM tooling to connect to CRM
Build Windows client applications using the XRM tools