Implantar pacotes usando o Dynamics CRM Package Deployer e o Windows PowerShell

Artigo
02/23/2018

Publicado: fevereiro de 2017

Aplicável a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Dica

As informações fornecidas aqui são para versões do Dynamics 365 antes do Dynamics 365 (online), versão 9.0. Para obter a documentação mais recente, consulte Implantar pacotes usando o Dynamics CRM Package Deployer e o Windows PowerShell.

O Microsoft Dynamics CRM Package Deployer permite que os administradores implementem pacotes em um Dynamics 365 (local) ou uma instância do Microsoft Dynamics 365 (online). Um "pacote" pode consistir de todos ou qualquer um dos seguintes:

Um ou mais arquivos de solução do Dynamics 365.
Arquivos de dados simples ou exportados do Ferramenta de Migração de Configuração. Para obter mais informações sobre o Ferramenta de Migração de Configuração, consulte Gerenciar dados de configuração.
Um código personalizado que pode ser executado durante ou depois do pacote ser implantado no servidor do Microsoft Dynamics 365.
Conteúdo HTML específico para o pacote que pode ser exibido no início e no final do processo de implantação do pacote. Isso pode ser útil para fornecer uma descrição das soluções e dos arquivos que são implantados no pacote.

Desenvolvedores criam pacotes usando o modelo de implantação de pacote no Microsoft Visual Studio.Para obter mais informações:MSDN: Criar um pacote para o Package Deployer do CRM

Depois que um pacote é criado, você pode implantar executando o Implantação de Pacotes do CRM ou usando os cmdlets do Windows PowerShell para a ferramenta.

Importante

Antes de importar e executar um pacote em uma organização de produção, teste o pacote em uma imagem espelhada de não produção da organização de produção.

Sempre faça backup da organização de produção antes de implantar um pacote.

Neste tópico

Implantando pacotes usando o Ferramenta de Implantação de Pacotes

Use o Windows PowerShell para implantar pacotes

Solucionar problemas de implantação do pacote usando arquivos de log

Práticas recomendadas para implantar pacotes

Implantando pacotes usando o Ferramenta de Implantação de Pacotes

Você pode usar Ferramenta de Implantação de Pacotes (packagedeployer.exe) para implantar pacotes dos seguintes procedimentos.

Usar o Ferramenta de Implantação de Pacotes para implantar pacotes

Usar o Ferramenta de Implantação de Pacotes na linha de comandos

Usar o Ferramenta de Implantação de Pacotes para implantar pacotes

O Ferramenta de Implantação de Pacotes pode processar apenas um pacote por vez. Entretanto, oferece aos usuários a capacidade de selecionar um pacote para implantar entre vários pacotes disponíveis no diretório do Ferramenta de Implantação de Pacotes. Algumas das telas e ações na ferramenta são diferentes com base na definição do pacote. Você não precisa instalar o Ferramenta de Implantação de Pacotes. Basta baixar e executar.

Obtenha o pacote a ser implantado. Um pacote é uma coleção de arquivos e pastas criada na pasta de projeto no Visual Studio (<Project>\Bin\Debug) ao criar o pacote de projeto no Visual Studio. Copie os dados a seguir da sua pasta de depuração de projeto:
- Pasta <PackageName>: essa pasta contém as soluções, a configuração de importação, e o conteúdo do seu pacote.
- <PackageName>.dll: o assembly contém o código do seu pacote. Por padrão, o nome do assembly será igual ao nome do seu projeto do Visual Studio.
Para obter informações detalhadas sobre como criar um pacote usando o Visual Studio, consulte MSDN: Criar um pacote para a ferramenta Package Deployer.

Neste tópico, suponhamos que a pasta do pacote e o assembly da pasta de depuração do projeto do Visual Studio (<Projeto>\Bin\Debug) foram copiados para a pasta c:\DeployPackage.
Baixe o SDK do Microsoft Dynamics CRM. Execute o arquivo executável baixado para extrair os conteúdos do pacote.
Procure na pasta SDK\Tools\PackageDeployer e copie a pasta do pacote e o assembly da pasta c:\DeployPackage para a pasta SDK\Tools\PackageDeployer.
Após copiar todos os arquivos, execute a ferramenta clicando duas vezes no arquivo do PackageDeployer.exe na pasta do SDK\Tools\PackageDeployer.
Clique em Continuar na tela principal da ferramenta.
Na tela Conectar-se ao Microsoft Dynamics 365, forneça os detalhes de autenticação para conectar o seu servidor do Dynamics 365 onde deseja implementar o pacote. Se houver várias organizações no servidor e você deseja selecionar a organização para onde deseja importar o pacote, marque a caixa de seleção Sempre exibir lista de organizações disponíveis. Clique em Logon.
Se houver várias organizações no seu servidor do Dynamics 365, selecione uma organização do Dynamics 365 à qual se conectar.
Selecione o pacote a ser implantado e clique em Avançar.
Siga as instruções nas telas subsequentes para concluir a implantação do seu pacote.

As telas aparecem baseadas na definição do pacote selecionado para implantação. Para uma implementação do pacote de ponta a ponta que usa o Ferramenta de Implantação de Pacotes, consulte o tópico para a implementação dos pacotes do Unified Service Desk: Implementar a amostra dos aplicativos do Unified Service Desk para o CRM Server usando o Package Deployer

Usar o Ferramenta de Implantação de Pacotes na linha de comandos

Os personalizadores e administradores do sistema podem aprovar parâmetros, como o código do idioma regional para o packagedeployer.exe na linha de comandos. Esses parâmetros podem ser configurados executando o Ferramenta de Implantação de Pacotes na linha de comandos.

Dica

Esse recurso foi introduzido pela primeira vez no Atualização 0.1 do Microsoft Dynamics CRM Online 2016.

Os parâmetros disponíveis estão nesta tabela.

Parâmetro	Descrição	Valor Padrão
RuntimePackageSettings	Instrui o packagedeployer.exe a aceitar parâmetros da linha de comandos, como LCID e SkipChecks.	Não aplicável
LCID=localeID	Especifica a ID de localidade, como 1033 para inglês dos Estados Unidos ou 1036 para francês da França, a partir das IDs de localidade disponíveis no pacote. Se não for especificado, o idioma padrão será usado.	Usar o idioma padrão
SkipChecks=true/false	Esse parâmetro deve ser usado somente quando o ambiente de destino não contiver nenhuma outra solução ou personalização. Quando definido como true, a importação da solução ignorará algumas verificações de segurança, o que pode melhorar o desempenho da importação.	Falso

O exemplo a seguir instrui o Implantação de Pacotes do CRM a ignorar as verificações de segurança e define o idioma para importação como polonês.

packagedeployer.exe /Settings:"SkipChecks=true|lcid=1045"

Dica

Use o caractere de barra vertical | para separar parâmetros ao executar o packagedeployer.exe na linha de comandos com vários parâmetros.

Para saber mais sobre os parâmetros e os valores a serem passados para o packagedeployer.exe, confira MSDN: Criar pacotes para o Package Deployer do CRM

Use o Windows PowerShell para implantar pacotes

O Ferramenta de Implantação de Pacotes também oferece suporte do Windows PowerShell para implantar pacotes.

Execute as etapas a seguir para usar os cmdlets do PowerShell para implantar pacotes:

Pré-requisitos

Registrar o cmdlets

Use o cmdlet do para recuperar pacotes

Use o cmdlet para se conectar à instância do Dynamics 365

Use o cmdlet para implantar pacotes

Obter ajuda detalhou sobre cmdlets

Pré-requisitos

Aqui estão os pré-requisitos para usar os cmdlets do PowerShell:

PowerShell 3.0 ou posterior é necessário para implantar um pacote usando o PowerShell. Para verificar a sua versão do PowerShell, execute uma janela do PowerShell, então execute o seguinte comando: $Host
Defina a política de execução para executar os scripts do PowerShell assinados. Para isso, execute uma janela do PowerShell como administrador, então execute o seguinte comando: Set-ExecutionPolicy -ExecutionPolicy AllSigned

Registrar o cmdlets

Você deve registrar os cmdlets do Windows PowerShell para o Ferramenta de Implantação de Pacotes, antes de poder usá-los. Para registrar os cmdlets:

Caso ainda não esteja familiarizado, baixe o pacote de SDK do Dynamics 365 pelo Centro de Download da Microsoft e execute o arquivo do pacote para extrair o conteúdo do pacote. Suponhamos que você tenha extraído o pacote para a pasta do c:\CRM no computador. O Ferramenta de Implantação de Pacotes e outros arquivos necessários serão disponibilizados no seguinte local: c:\CRM\SDK\Tools\PackageDeployer.
Inicie o Windows PowerShell no computador com privilégios elevados (executar como administrador).
No prompt da janela do Windows PowerShell, altere seu diretório para a pasta do Windows PowerShell na pasta do PackageDeployer. Neste caso:
```
cd c:\CRM\SDK\Tools\PackageDeployer\PowerShell
```
Execute o script do RegisterXRMTooling.ps1 para registrar o conjunto do Package Deployer do Windows PowerShell (dll) e instalar o snap-in do Windows PowerShell para o Ferramenta de Implantação de Pacotes. Para fazer isso, para digite o comando a seguir e pressione ENTER:
```
.\RegisterXRMTooling.ps1
```
Adicione o snap-in do Windows PowerShell para a ferramenta XRM. Isso registrará os seguintes cmdlets: Get-CrmConnection e Get-CrmOrganizations.
```
Add-PSSnapin Microsoft.Xrm.Tooling.Connector
```
Adicione o snap-in do Windows PowerShell para o Package Deployer. Isso registrará os seguintes cmdlets: Get-CrmPackages e Import-CrmPackage.
```
Add-PSSnapin Microsoft.Xrm.Tooling.PackageDeployment
```

Você está pronto para usar os cmdlets do Windows PowerShell. Para listar os cmdlets registrados, execute o comando a seguir no prompt da janela do Windows PowerShell:

Get-Help “Crm”

Use o cmdlet do para recuperar pacotes

Antes de usar o cmdlet, verifique se você copiou o pacote para a pasta PackageDeployer (nesse caso, c:\CRM\SDK\Tools\PackageDeployer). Um pacote é um conjunto de arquivos e pastas criado na pasta de projeto no Visual Studio (<Project>\Bin\Debug) ao criar o projeto no Visual Studio. Copie todo o conteúdo da sua pasta de depuração do projeto para a pasta PackageDeployer. Para obter informações detalhadas sobre como criar um pacote usando o Visual Studio, consulte MSDN: Criar um pacote para o Package Deployer do CRM.

Na janela do PowerShell, use o seguinte cmdlet para retornar uma lista de pacotes disponíveis para importar a pasta especificada (nesse caso, c:\CRM\SDK\Tools\PackageDeployer):
```
Get-CrmPackages –PackageDirectory c:\CRM\SDK\Tools\PackageDeployer
```
Se você quiser informações sobre o pacote em uma pasta, use o cmdlet Get-CrmPackages com o parâmetro –PackageName para especificar o nome do assembly na pasta que contém a definição do pacote.
```
Get-CrmPackages –PackageDirectory c:\CRM\SDK\Tools\PackageDeployer –PackageName SampleCRMPackage.dll
```
O local de assembly de pacote pode ser armazenado em uma variável usando o cmdlet Get-CrmPackages. Em seguida, ele pode ser reutilizado no cmdlet Import-CrmPackage para especificar um valor para o parâmetro PackageDirectory. Por exemplo, você pode armazenar informações de um ou mais pacotes retornados do cmdlet Get-CrmPackages em uma variável chamada $MyPackages.
```
$MyPackages = Get-CrmPackages –PackageDirectory c:\CRM\SDK\Tools\PackageDeployer 
```
Para exibir todos os pacotes.
```
$MyPackages
```
Para exibir somente o terceiro pacote.
```
$MyPackages[2].PackageAssemblyLocation
```
Em seguida, você poderá fazer referência a cada pacote na matriz de 0 a n. Por exemplo, este cmdlet importa o primeiro pacote encontrado no $MyPackages.
```
Import-CrmPackage -CrmConnection $CRMConn -PackageDirectory $MyPackages[0].PackageAssemblyLocation
```
Dica

O parâmetro PackageAssemblyLocation e a capacidade de exibir o local da pasta e o nome do pacote foram introduzidos pela primeira vez com o Atualização de dezembro de 2016 para Dynamics 365 (online e local).Para obter mais informações:Dynamics 365 SDK

Use o cmdlet para se conectar à instância do Dynamics 365

Forneça suas credenciais para se conectar à instância do Microsoft Dynamics 365 (online) ou Dynamics 365 (local). Executar o seguinte comando solicitará que você digite seu nome de usuário e senha para se conectar à instância do Dynamics 365 e iremos armazenar na variável do $Cred e usá-lo posteriormente para conectar ao seu servidor do Dynamics 365.
```
$Cred = Get-Credential
```
Use o seguinte comando para obter uma conexão para sua instância do Microsoft Dynamics 365 (online) ou Dynamics 365 (local). Iremos armazenar informações de conexão na variável $CRMConn:
- Se estiver se conectando a uma instância do Dynamics 365 (local):
```
$CRMConn = Get-CrmConnection -ServerUrl http://<your_CRM_Server> -OrganizationName <your_Org_Name> -Credential $Cred
```
- Se estiver se conectando a um servidor do Microsoft Dynamics 365 (online):
```
$CRMConn = Get-CrmConnection -DeploymentRegion NorthAmerica –OnlineType Office365 –OrganizationName <your_Org_Name> -Credential $Cred
```
  Dica
  
  Para o parâmetro DeploymentRegion, valores válidos são NorthAmerica, EMEA, APACSouthAmerica, Oceania, JPN e NorthAmerica2. Os valores válidos do parâmetro OnlineType são Office365 e LiveID.
Suas credenciais fornecidas são validadas ao executar o comando na etapa 2.

Use o cmdlet para implantar pacotes

Em seguida, use as informações de conexão do Dynamics 365 armazenadas na variável $CRMConn para implantar pacotes da instância do Dynamics 365. O comando deploysa package a seguir, desmonta o pacote na pasta c:\UnpackedFiles, e registra informações no arquivo de log da pasta c:\MyLogFiles.

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

Dica

Os parâmetros CrmConnection, PackageDirectory e PackageName são obrigatórios.
Em vez de especificar manualmente a pasta do pacote, você pode usar uma variável com o parâmetro PackageDirectory.Para obter mais informações:Use o cmdlet do para recuperar pacotes
Para o parâmetro PackageName, é necessário especificar o nome do assembly que contém a definição do pacote.
Não é necessário especificar o parâmetro UnpackFilesDirectory se seu pacote não desempacotar arquivos durante a implantação do pacote. Ao definir um pacote no Visual Studio, você especifica se deve descompactar arquivos usando o parâmetro agentdesktopzipfile no arquivo ImportConfig.xml .exe.Para obter mais informações:MSDN: Criar um pacote para o Package Deployer do CRM
O parâmetro Verbose é opcional e é usado para exibir um log detalhado de atividades executadas durante o processo de implantação do pacote.
O parâmetro opcional RuntimePackageSettings pode ser usado em conjunto com os seguintes parâmetros:
- O parâmetro LCID=localeID especifica a ID de localidade, como 1033 para inglês dos Estados Unidos ou 1036 para francês da França, a partir das IDs de localidade disponíveis no pacote. Se não for especificado, o idioma padrão será usado.
- O
  
  parâmetro SkipChecks=true/false só deve ser usado quando o ambiente de destino não contém nenhuma outra solução ou personalização. Quando definido como true, a importação da solução ignorará algumas verificações de segurança, o que pode melhorar o desempenho da importação.
A pasta especificada ao usar o parâmetro LogWriteDirectory já deve existir, e o usuário que executa o cmdlet Import-CrmPackage deve ter permissão para gravação na pasta. Além disso, é necessário o parâmetro Verbose (Detalhado) ao usar o parâmetro LogWriteDirectory.

O parâmetro LogWriteDirectory foi introduzido pela primeira vez com o Atualização de dezembro de 2016 para Dynamics 365 (online e local).Para obter mais informações:Dynamics 365 SDK

O comando de exemplo a seguir importa um pacote denominado SampleCRMPackage e especifica o inglês dos Estados Unidos (1033) como o idioma para importação do pacote.

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

Obter ajuda detalhou sobre cmdlets

Na janela PowerShell, use o cmdlet Get-Help com um nome de cmdlet para exibir a ajuda detalhada do cmdlet. Por exemplo, para obter ajuda detalhada para o cmdlet Import-CrmPackage:

Get-Help Import-CrmPackage -full

Para visualizar a ajuda online para cmdlets, consulte Referência do PowerShell do CRM.

Solucionar problemas de implantação do pacote usando arquivos de log

O Ferramenta de Implantação de Pacotes oferece suporte de registro para obter informações detalhadas sobre os erros que podem ocorrer quando alguém efetua login na instância do Microsoft Dynamics 365 usando a ferramenta e implantando pacotes. Por padrão, a ferramenta gera três arquivos de log que estão disponíveis no seguinte local no computador onde você executa a ferramenta: c:\Users\<UserName>\AppData\Roaming\Microsoft\Microsoft Dynamics CRM Package Deployer\<Versão>. Para especificar uma pasta diferente, use o parâmetro do cmdlet -LogWriteDirectory PowerShell.Para obter mais informações:Use o cmdlet do para recuperar pacotes

Login_ErrorLog.log: fornece informações sobre os problemas que ocorreram ao usar a ferramenta para efetuar login na instância do Dynamics 365. Se houver problemas durante a entrada, uma mensagem aparece na tela de logon da ferramenta com um link para este arquivo de log. A mensagem indica que um erro ocorreu ao processar a solicitação de logon e o usuário pode exibir o log de erros. Você pode clicar no link na mensagem para exibir este arquivo de log. O arquivo de log é criado na primeira vez que você encontra qualquer problemas de login na ferramenta. Depois disso, o arquivo de log é usado para registrar as informações sobre problemas de login, sempre que ocorrerem.
PackageDeployer.log: fornece informações detalhadas sobre cada tarefa executada na ferramenta durante a implementação dos pacotes. Você pode exibir o arquivo de log da ferramenta clicando no link Exibir Arquivo de Log na parte inferior da tela.
ComplexImportDetail.log: fornece informações detalhadas sobre os dados importados na última implementação usando a ferramenta. Cada vez que implementar um pacote usando esta ferramenta, os detalhes existentes do arquivo de registro são movidos para um arquivo chamado ComplexImportDetail._old.log no mesmo diretório, e o arquivo do ComplexImportDetail.log exibe as informações sobre a última importação feita usando a ferramenta.

Práticas recomendadas para implantar pacotes

Para implantar pacotes, os administradores do Dynamics 365 devem:

Insista em um assembly de pacote assinado para que possa rastrear um assembly de volta para sua origem.
Teste o pacote em uma instância pré-produção (preferivelmente uma imagem espelhada da instância de produção) antes de executar em um servidor de produção.
Faça o backup da instância de produção antes de implantar um pacote.

Confira Também

MSDN: Criar um pacote para o Package Deployer do CRM
Administrando Dynamics 365

Implantar pacotes usando o Dynamics CRM Package Deployer e o Windows PowerShell

Neste tópico

Implantando pacotes usando o Ferramenta de Implantação de Pacotes

Usar o Ferramenta de Implantação de Pacotes para implantar pacotes

Usar o Ferramenta de Implantação de Pacotes na linha de comandos

Use o Windows PowerShell para implantar pacotes

Pré-requisitos

Registrar o cmdlets

Use o cmdlet do para recuperar pacotes

Use o cmdlet para se conectar à instância do Dynamics 365

Use o cmdlet para implantar pacotes

Obter ajuda detalhou sobre cmdlets

Solucionar problemas de implantação do pacote usando arquivos de log

Práticas recomendadas para implantar pacotes

Confira Também

Recursos adicionais