Deploy packages using CRM Package Deployer and Windows PowerShell

  • Article

 

Applies To: Dynamics CRM 2013

Microsoft Dynamics CRM Package Deployer is a new tool for Microsoft Dynamics CRM Online Spring ‘14 and Microsoft Dynamics CRM 2013 Service Pack 1 (SP1) (on-premises) that enables administrators to deploy packages on a Microsoft Dynamics CRM instance or organization. A “package” can consist of any or all of the following:

  • One or more CRM solution files.

  • Flat files or exported data files from the Configuration Migration tool. For information about the Configuration Migration tool, see Manage your configuration data.

  • Custom code that can run during or after the package is deployed to Microsoft Dynamics CRM.

  • HTML content specific to the package that can display at the beginning and end of the package deployment process. This can be useful to provide a description of the solutions and files that are deployed in the package.

Developers create packages by using the package deployment template in Microsoft Visual Studio. More information: Create a package for the Package Deployer tool

After a package is created, you can deploy it either by running CRM Package Deployer or by using Windows PowerShell cmdlets for the tool.

In This Topic

Use CRM Package Deployer tool to deploy packages

Use Windows PowerShell to deploy packages

Troubleshoot package deployment issues by using log files

Best practices for deploying packages

Use CRM Package Deployer tool to deploy packages

The Package Deployer tool can only process one package at a time. However, it provides users with the ability to select a package to deploy from multiple packages available in the Package Deployer tool directory. Some of the screens and actions in the tool differ based on the package definition. You do not have to install the Package Deployer tool. Just download and run it.

  1. Obtain the package to be deployed. A package is a collection of files and folders that is created in your Visual studio project folder (<Project>\Bin\Debug) when you build your package project in Visual Studio. Copy the following from your project debug folder:

    • <PackageName> folder: This folder contains the solutions, import configuration, and the contents for your package.

    • <PackageName>.dll: The assembly contains the code for your package. By default, the name of the assembly is the same as your Visual Studio project name.

    For detailed information about building a package by using Visual Studio, see Create a package for the Package Deployer tool.

    For this topic, let us assume that the package folder and assembly from the Visual Studio project debug folder (<Project>\Bin\Debug) are copied to the c:\DeployPackage folder.

  2. Download the Microsoft Dynamics CRM 2013 Service Pack 1 (SP1) SDK download package file, and run the downloaded executable file to extract the contents of the package.

  3. Browse to the SDK\Tools\PackageDeployer folder, and copy the package folder and assembly from the c:\DeployPackage folder to the SDK\Tools\PackageDeployer folder.

  4. After the files are copied, run the tool by double-clicking the PackageDeployer.exe file in the SDK\Tools\PackageDeployer folder.

  5. Choose Continue on the main screen of the tool.

  6. In the Connect to Microsoft Dynamics CRM screen, provide authentication details to connect to your CRM server where you want to deploy the package. If you have multiple organizations, and want to select the organization where you want to deploy the package, select the Always display list of available orgs check box. Choose Login.

  7. If you have multiple organizations on your CRM server, and you selected the Always display list of available orgs check box, the next screen lets you choose the organization that you want to connect to. Select a CRM organization to connect to.

  8. The next screen will prompt you to select a package to be deployed. Select your package name, and choose Next.

    Select your package in the Package Deployer Tool

  9. Follow the instructions on the subsequent screens to complete the deployment of your package.

    The screens appear based on the definition of the package that you selected for deployment. For an end-to-end package deployment that uses the Package Deployer tool, see the topic for the deployment of Unified Service Desk packages: Deploy sample Unified Service Desk applications to CRM server using Package Deployer

Use Windows PowerShell to deploy packages

The Package Deployer tool also provides Windows PowerShell support to deploy packages.

Perform the following steps to use the PowerShell cmdlets to deploy packages:

Prerequisites

Register the cmdlets

Use the cmdlet to retrieve packages

Use the cmdlet to connect to your CRM server

Use the cmdlet to deploy packages

Get detailed help on cmdlets

Prerequisites

Here are the prerequisites for using the PowerShell cmdlets:

  • PowerShell 3.0 or later is required to deploy a package by using PowerShell. To check your PowerShell version, run a PowerShell window, and then run the following command: $Host

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

Register the cmdlets

You must register the Windows PowerShell cmdlets for the Package Deployer tool before you can use it. To register the cmdlets:

  1. If you haven’t already done so, download the CRM SDK package from the Microsoft Download Center, and run the package file to extract the contents of the package. Let’s assume that you extracted the package to the c:\CRM folder on your computer. The Package Deployer tool and the other required files become available at the following location: c:\CRM\SDK\Tools\PackageDeployer.

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

  3. At the prompt in the Windows PowerShell window, change your directory to the Windows PowerShell folder under the PackageDeployer folder. In this case:

    cd c:\CRM\SDK\Tools\PackageDeployer\PowerShell

  4. Run the RegisterXRMTooling.ps1 script to register the Package Deployer Windows PowerShell assembly (dll), and install the Windows PowerShell snap-in for the Package Deployer tool. To do so, type the following command, and press ENTER:

    .\RegisterXRMTooling.ps1

  5. Add the Windows PowerShell snap-in for XRM tooling. This will register the following cmdlets: Get-CrmConnection and Get-CrmOrganizations.

    Add-PSSnapin Microsoft.Xrm.Tooling.Connector

  6. Add the Windows PowerShell snap-in for Package Deployer. This will register the following cmdlets: Get-CrmPackages and Import-CrmPackage.

    Add-PSSnapin Microsoft.Xrm.Tooling.PackageDeployment

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 packages

Before you can use the cmdlet, ensure that you have copied your package to the PackageDeployer folder (in this case, c:\CRM\SDK\Tools\PackageDeployer). A package is a collection of files and folders that is created in your Visual Studio project folder (<Project>\Bin\Debug) when you build your project in Visual Studio. Copy the entire contents of your project debug folder to the PackageDeployer folder. For detailed information about building a package using Visual Studio, see Create a package for the Package Deployer tool.

  1. In the PowerShell window, use the following cmdlet to return a list of packages available for import in the specified directory (in this case, c:\CRM\SDK\Tools\PackageDeployer):

    Get-CrmPackages –PackageDirectory c:\CRM\SDK\Tools\PackageDeployer

  2. If you want information about a package in a directory, you can use the Get-CrmPackages cmdlet along with the –PackageName parameter to specify the name of the assembly in the directory that contains the package definition.

    Get-CrmPackages –PackageDirectory c:\CRM\SDK\Tools\PackageDeployer –PackageName SampleCRMPackage.dll

Use the cmdlet to connect to your CRM server

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

    $Cred = Get-Credential

  2. Use the following command to get a connection to your Microsoft Dynamics CRM Online or Microsoft Dynamics CRM (on-premises) instance. We will store the connection information in the $CRMConn variable:

    • If you are connecting to the Microsoft Dynamics CRM (on-premises) instance:

      $CRMConn = Get-CrmConnection -ServerUrl http://<your_CRM_Server> -OrganizationName <your_Org_Name> -Credential $Cred

    • If you are connecting to the Microsoft Dynamics CRM Online server:

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

      Note

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

  3. Your supplied credentials are validated when you run the command in step 2.

Use the cmdlet to deploy packages

Next, use the CRM connection information stored in the $CRMConn variable to deploy packages to the CRM instance. Run the following command to deploy your package:

Import-CrmPackage –CrmConnection $CRMConn –PackageDirectory c:\CRM\SDK\Tools\PackageDeployer –PackageName SampleCRMPackage.dll –UnpackFilesDirectory c:\UnpackedFiles -Verbose

Note

  • CrmConnection, PackageDirectory, and PackageName parameters are mandatory.

  • For the PackageName parameter, you have to specify the name of the assembly that contains the package definition.

  • You do not need to specify the UnpackFilesDirectory parameter if your package does not unpack files during package deployment. While defining a package in Visual Studio, you specify whether to unpack files using the agentdesktopzipfile parameter in the ImportConfig.xml file. More information: Create a package for the Package Deployer tool

  • The Verbose parameter is optional, and is used to display a detailed log of the activities performed during the package deployment process.

Get detailed help on cmdlets

In the PowerShell window, use the Get-Help cmdlet with a cmdlet name to view a detailed help for the cmdlet. For example, to get detailed help for the Import-CrmPackage cmdlet:

Get-Help Import-CrmPackage -full

Troubleshoot package deployment issues by using log files

The Package Deployer tool provides logging support to get detailed information about errors that can occur when someone signs in to the Microsoft Dynamics CRM instance using the tool and deploying packages. The tool generates three log files that are available at the following location on the computer where you run the tool: c:\Users\<UserName>\AppData\Roaming\Microsoft\PackageDeployer\<Version>.

  • Login_ErrorLog.log: Provides information about the issues that occurred when you use the tool to sign in to the CRM instance. If there are any issues during sign in, a message appears on the tool’s login screen with a link to this log file. The message states that an error occurred while processing the login request and the user can view the error log. You can choose the link in the message to view this log file. The log file is created the first time you encounter any sign-in issues in the tool. Thereafter, the log file is used to log information about a sign-in issue, whenever it occurs.

  • PackageDeployer.log: Provides detailed information about each task performed in the tool during the deployment of the packages. You can view the log file from the tool by choosing the View Log File link at the bottom of the screen.

  • ComplexImportDetail.log: Provides detailed information about the data imported in the last deployment by using the tool. Each time you deploy a package using this tool, the existing details from the log file are moved to a file called ComplexImportDetail._old.log in the same directory, and the ComplexImportDetail.log file displays information about the latest import done using the tool.

Best practices for deploying packages

While deploying packages, CRM administrators must:

  • Insist on a signed package assembly so that they can track an assembly back to its source.

  • Test the package on a pre-production instance (preferably a mirror image of the production instance) before running it on a production server.

  • Back up the production instance before deploying a package.

See Also

Create a package for the Package Deployer tool
Administration Guide for Microsoft Dynamics CRM 2013

© 2016 Microsoft Corporation. All rights reserved. Copyright