Ferramenta SolutionPackager

SolutionPackager é uma ferramenta que pode decompor reversivelmente um arquivo de solução compactado Microsoft Dataverse em vários arquivos XML e outros arquivos. Você pode gerenciar facilmente esses arquivos usando um sistema de controle do código-fonte. As seções a seguir mostram como executar a ferramenta e como usá-la com soluções gerenciadas e não gerenciadas.

Onde encontrar a ferramenta SolutionPackager

A ferramenta SolutionPackager é distribuída como parte do Microsoft. CrmSdk.CoreTools pacote NuGet. Para instalar o programa, siga estas etapas.

1. Baixe o pacote NuGet.
2. Renomeie a extensão de nome de arquivo do pacote de .nupkg para .zip.
3. Extraia o conteúdo do arquivo compactado (zip).

Encontre o executável SolutionPackager na pasta <extracted-folder-name>/contents/bin/coretools. Execute o programa na pasta coretools ou adicione essa pasta ao seu PATH.

Argumentos de linha de comando SolutionPackager

O SolutionPackager é uma ferramenta de linha de comando que pode ser invocada com os parâmetros identificados na tabela a seguir.

Formatos de arquivo de controle do código-fonte

O SolutionPackager dá suporte a dois layouts de pasta ao extrair e empacotar soluções.

Formato XML (herdado)

O formato original. Os metadados da solução são armazenados em Other\Solution.xml e Other\Customizations.xml, e todos os arquivos de componentes são extraídos em uma hierarquia de pastas simples ao lado desses arquivos. Esse formato é o formato padrão ao extrair um .zip arquivo sem mais configuração.

Formato de controle do código-fonte YAML

Introduzido junto com a integração do Dataverse Git, esse formato armazena metadados de solução como arquivos YAML distribuídos em uma hierarquia de pastas estruturadas. É o formato escrito quando você confirma soluções usando a integração nativa do Git no Power Apps.

Vantagens em relação ao formato XML

• Produz diferenças mais limpas e legíveis por componente no controle do código-fonte
• Dá suporte a várias soluções em uma única pasta de repositório
• Arquivos de aplicativo Canvas .msapp e fluxos modernos são suportados apenas neste formato
• O remapeamento de nomes de tipos de plug-ins está habilitado por padrão

Estrutura de pastas necessária

<rootFolder>/
├── solutions/
│   └── <SolutionUniqueName>/
│       ├── solution.yml              (solution metadata)
│       ├── solutioncomponents.yml    (paths to all component files)
│       ├── rootcomponents.yml        (root-level components)
│       └── missingdependencies.yml   (dependency info)
├── publishers/
│   └── <PublisherUniqueName>/
│       └── publisher.yml             (publisher definition)
├── entities/                         (entity components, if present)
├── workflows/                        (classic workflows, if present)
├── modernflows/                      (Power Automate cloud flows, if present)
├── canvasapps/                       (canvas app .msapp files, if present)
└── [other component folders]/

Mais informações: Referência do formato de controle do código-fonte YAML da solução

Formatar regras de detecção automática

Empacotando uma pasta de formato YAML

O comando a seguir empacota uma pasta de formato YAML.

SolutionPackager.exe /action:Pack /zipfile:MySolution.zip /folder:C:\repos\myrepo

Empacotamento de uma pasta de múltiplas soluções

O comando a seguir empacota uma solução especificada em uma pasta de várias soluções.

SolutionPackager.exe /action:Pack /zipfile:SolutionA.zip /folder:C:\repos\myrepo /SolutionName:SolutionA

Use o argumento de comando do /mapa

A seguinte discussão detalha o uso do argumento /map para a ferramenta SolutionPackager.

Os arquivos que são internos em um sistema de compilação automatizado, como arquivos .xap do Silverlight e assemblies de plug-in, geralmente não são verificados no controle do código-fonte. Os recursos da Web podem já estar presentes no controle do código-fonte em locais que não sejam diretamente compatíveis com a ferramenta SolutionPackager. Incluindo o parâmetro /map, a ferramenta SolutionPackager pode ser direcionada para ler e empacotar esses arquivos a partir de locais alternados e não de dentro da pasta Extrair como normalmente seria feito. O parâmetro /map deve especificar o nome e o caminho para um arquivo XML contendo diretivas de mapeamento. Essas diretivas instruem o SolutionPackager a corresponder os arquivos por nome e caminho e indicam o local alternativo para localizar o arquivo correspondente. As seguintes informações se aplicam às políticas de forma igual.

• Várias diretivas podem ser listadas, inclusive as que combinam arquivos idênticos. Diretivas listadas no início do arquivo têm prioridade sobre as listadas posteriormente.

• Se o arquivo é combinado com qualquer diretiva, ele deve ser encontrado pelo menos em um local alternativo. Se não forem encontradas alternativas correspondentes, o SolutionPackager emitirá um erro.

• A pasta e os caminhos do arquivo podem ser absolutos ou relativos. Os caminhos relativos são sempre avaliados a partir da pasta especificada pelo parâmetro /folder.

• As variáveis de ambiente podem ser especificadas usando uma sintaxe %variable%.

• Uma coringa de pasta "**" pode ser utilizada para indicar "em qualquer subpasta". Ele só pode ser usado como a parte final de um caminho, por exemplo: "c:\folderA\**".

• Curingas de nome de arquivo podem ser usados somente nos formulários "*.ext" ou "*.*". Nenhum outro padrão possui suporte.

  Os três tipos de mapeamento de diretivas estão descritos aqui, juntamente com um exemplo que mostra como usá-los.

Mapeamento de pasta

Veja a seguir informações detalhadas sobre o mapeamento de pasta.

Formato Xml

<Folder map="folderA" to="folderB" />

Descrição

Os caminhos de arquivo que correspondem a "folderA" são alternados para "folderB".

• A hierarquia das subpastas em cada uma deve corresponder de forma exata.

• Os caracteres curingas da pasta não têm suporte.

• Nenhum nome de arquivo pode ser especificado.

  Exemplos

  <Folder map="folderA" to="folderB" />  
  <Folder map="folderA\folderB" to="..\..\folderC\" />  
  <Folder map="WebResources\subFolder" to="%base%\WebResources" />  
  

Mapeamento de arquivo a arquivo

Veja a seguir informações mais detalhadas sobre o mapeamento de arquivo para arquivo.

Formato Xml

<FileToFile map="path\filename.ext" to="path\filename.ext" />

Descrição

Qualquer arquivo que corresponda ao parâmetro map é lido a partir do nome e o caminho especificado no parâmetro to.

Para o parâmetro map:

• Um nome do arquivo deve ser especificado. O caminho é opcional. Se nenhum caminho for especificado, os arquivos de qualquer pasta podem ser correspondidos.

• Os caracteres curingas do nome do arquivo não possuem suporte.

• O caractere curinga da pasta possui suporte.

  Para o parâmetro to:

• Um nome do arquivo e caminho devem ser especificados.

• O nome do arquivo pode ser diferente do nome no parâmetro map.

• Os caracteres curingas do nome do arquivo não possuem suporte.

• O caractere curinga da pasta possui suporte.

Exemplos

  <FileToFile map="assembly.dll" to="c:\path\folder\assembly.dll" />  
  <FileToFile map="PluginAssemblies\**\this.dll" to="..\..\Plugins\**\that.dll" />  
  <FileToFile map="Webresrouces\ardvark.jpg" to="%SRCBASE%\CrmPackage\WebResources\JPG format\aardvark.jpg" />  

  <FileToFile
    map="pluginpackages\cr886_PluginPackageTest\package\cr886_PluginPackageTest.nupkg"
    to="myplg\bin\Debug\myplg.1.0.0.nupkg" /> 

No exemplo de pacote NuGet acima, cr886_PluginPackageTest.nupkg não é substituído, se o arquivo já existir no local especificado.

Mapeamento do arquivo ao caminho

Veja a seguir informações detalhadas sobre o mapeamento de arquivo para caminho.

Formato Xml

<FileToPath map="path\filename.ext" to="path" />

Descrição

Qualquer arquivo que corresponda com o parâmetro map é lido a partir do caminho especificado no parâmetro to.

Para o parâmetro map:

• Um nome do arquivo deve ser especificado. O caminho é opcional. Se nenhum caminho for especificado, os arquivos de qualquer pasta podem ser correspondidos.

• Os caracteres curingas do nome do arquivo possuem suporte.

• O caractere curinga da pasta possui suporte.

Para o parâmetro to:

• É necessário especificar um caminho.

• O caractere curinga da pasta possui suporte.

• Um nome do arquivo não deve ser especificado.

  Exemplos

  <FileToPath map="assembly.dll" to="c:\path\folder" />  
  <FileToPath map="PluginAssemblies\**\this.dll" to="..\..\Plugins\bin\**" />  
  <FileToPath map="*.jpg" to="%SRCBASE%\CrmPackage\WebResources\JPG format\" />  
  <FileToPath map="*.*" to="..\..\%ARCH%\%TYPE%\drop" />  

Mapeamento de exemplo

O exemplo do código XML a seguir mostra um arquivo de mapeamento completo que habilita a ferramenta SolutionPackager a ler qualquer recurso da Web e os dois assemblies padrão gerados de um projeto do Kit de Ferramentas para Desenvolvedores chamado CRMDevTookitSample.

<?xml version="1.0" encoding="utf-8"?>  
<Mapping>  
       <!-- Match specific named files to an alternate folder -->  
       <FileToFile map="CRMDevTookitSamplePlugins.dll" to="..\..\Plugins\bin\**\CRMDevTookitSample.plugins.dll" />  
       <FileToFile map="CRMDevTookitSampleWorkflow.dll" to="..\..\Workflow\bin\**\CRMDevTookitSample.Workflow.dll" />  
       <!-- Match any file in and under WebResources to an alternate set of subfolders -->  
       <FileToPath map="WebResources\*.*" to="..\..\CrmPackage\WebResources\**" />  
       <FileToPath map="WebResources\**\*.*" to="..\..\CrmPackage\WebResources\**" />  
</Mapping>  

Soluções gerenciadas e não gerenciadas

Um arquivo compactado (.zip) da solução do Dataverse pode ser exportado em um dos dois tipos, conforme mostrado aqui.

Solução gerenciada
Uma solução concluída pronta para ser importada a uma organização. Depois de importados, os componentes não podem ser adicionados ou removidos, embora, opcionalmente, possam permitir uma personalização adicional. Isso é recomendável quando o desenvolvimento da solução for concluída.

Solução não gerenciada
Uma solução em aberto sem restrições em que pode ser adicionada, removida ou alterada. Isso é recomendável durante o desenvolvimento de uma solução.

O formato de um arquivo de solução compactado será diferente com base no seu tipo, gerenciado ou não gerenciado. O SolutionPackager pode processar arquivos da solução compactados de qualquer tipo. No entanto, a ferramenta não pode converter um tipo em outro. A única maneira de converter arquivos de solução para um tipo diferente, por exemplo de não gerenciado para gerenciado, é importando o arquivo .zip de solução não gerenciada para um servidor do Dataverse e depois exportando a solução como uma solução gerenciada.

O SolutionPackager pode processar arquivos .zip de solução gerenciada e não gerenciada como um conjunto combinado por meio do parâmetro /PackageType:Both. Para executar essa operação, é necessário exportar a sua solução duas vezes como cada tipo, nomeando os arquivos .zip conforme a seguir.

A ferramenta assumirá a presença de arquivo .zip gerenciado na mesma pasta que o arquivo não gerenciado e extrairá ambos os arquivos em para uma única pasta que preserva as diferenças onde existam componentes gerenciados e não gerenciados.

Depois que uma solução foi extraída como gerenciada e não gerenciada, será possível, a partir de uma única pasta, empacotar as duas, ou cada tipo individualmente, usando o parâmetro /PackageType para especificar qual tipo a ser criado. Ao especificar ambas, os dois arquivos .zip serão gerados, usando a convenção de nomenclatura, conforme acima. Se o parâmetro PackageType estiver ausente durante o empacotamento a partir de uma pasta gerenciada e não gerenciada, o padrão é gerar um único arquivo .zip não gerenciado.

Solução de Problemas

Mensagem exibida ao usar Visual Studio para editar arquivos de recurso

Se você usar Visual Studio para editar fsiles de recurso criados pelo empacotador de solução, poderá receber uma mensagem ao reempacotar semelhante a esta: "Failed to determine version id of the resource file <filename>.resx the resource file must be exported from the solutionpackager.exe tool in order to be used as part of the pack process." Isso acontece porque Visual Studio substitui as marcas de metadados do arquivo de recurso por marcas de dados.

Solução alternativa

1. Abra o arquivo de recurso no seu editor de texto favorito e localize e atualize as seguintes guias:

   <data name="Source LCID" xml:space="preserve">  
   <data name="Source file" xml:space="preserve">  
   <data name="Source package type" xml:space="preserve">  
   <data name="SolutionPackager Version" mimetype="application/x-microsoft.net.object.binary.base64">  
   
   

2. Altere o nome do nó de <data> para <metadata>.

   Por exemplo, esta cadeia de caracteres:

   <data name="Source LCID" xml:space="preserve">  
     <value>1033</value>  
   </data>  
   
   

   Altera para:

   <metadata name="Source LCID" xml:space="preserve">  
     <value>1033</value>  
   </metadata>  
   
   

   Isso permite que o embalador da solução leia e importe o arquivo de recurso. Esse problema só foi observado ao usar o editor de recursos do Visual Studio.

Erro: "Não é possível localizar o arquivo necessário ...\Other\Customizations.xml" com uma pasta YAML

Esse erro aparece quando você executa SolutionPackager (ou pac solution pack) em uma pasta que contém arquivos YAML, como solution.yml, mas esses arquivos são colocados na raiz da pasta em vez de dentro da subpasta necessária solutions/<SolutionUniqueName>/ .

Causa: A ferramenta detecta o formato de controle do código-fonte YAML procurando uma solutions/ subpasta que *solution.yml contém arquivos. Quando esse diretório está ausente, a ferramenta retorna silenciosamente ao formato XML (herdado) e espera Other\Customizations.xml. A mensagem de erro resultante refere-se a um arquivo XML e não menciona YAML, o que é enganoso.

Corrigir: Reorganizar a pasta para que os arquivos de manifesto YAML estejam nos caminhos corretos:

<rootFolder>/
  solutions/<YourSolutionUniqueName>/   ← move solution.yml here
    solution.yml
    solutioncomponents.yml
    rootcomponents.yml
    missingdependencies.yml
  publishers/<YourPublisherUniqueName>/
    publisher.yml

Se você obteve a pasta de uma confirmação de integração do Git ou pac solution clone, a estrutura de pastas já deve estar correta. Uma pasta que contém apenas os arquivos YAML de nível superior sem o solutions/ subdiretório representa um extrato incompleto e não pode ser empacotada diretamente.

Aviso: o componente declarado em rootcomponents.yml não tem arquivos de origem

Esse aviso é exibido quando um componente, como um aplicativo de tela, é listado em rootcomponents.yml, mas não há arquivos de origem correspondentes na pasta de componente esperada (por exemplo, canvasapps/<schema-name>/).

Efeito: A ferramenta ainda é bem-sucedida (código de saída 0) e produz um arquivo válido .zip, mas o componente declarado é omitido do pacote da solução.

Causa: A pasta foi produzida por um extrato parcial ou os arquivos de origem do componente não foram incluídos no repositório. Por exemplo, somente os arquivos de manifesto da solução foram commitados, e não o aplicativo de tela em si.

Corrigir: Verifique se todos os componentes declarados rootcomponents.yml têm arquivos de origem correspondentes presentes na pasta. Para aplicativos de tela, o .msapp arquivo deve existir em canvasapps/<schema-name>/. Se houver arquivos ausentes, exporte novamente a solução completa do Dataverse e descompacte-a novamente ou use pac solution clone para obter um extrato completo.

Consulte também

• Usar o Controle do Código-Fonte com Arquivos de Solução
• conceitos de solução