Ferramenta SolutionPackager

O SolutionPackager é uma ferramenta que pode decompor reversivelmente um ficheiro de solução comprimido do Microsoft Dataverse em múltiplos ficheiros XML e outros ficheiros. Pode então facilmente gerir estes ficheiros utilizando um sistema de controlo de origem. As seguintes secções mostram como executar a ferramenta e como utilizá-la com soluções geridas e não geridas.

Onde encontrar a ferramenta SolutionPackager

A ferramenta SolutionPackager é distribuída como parte do Microsoft. CrmSdk.CoreTools Pacote NuGet. Para instalar o programa, siga estes passos.

1. Transferir o pacote NuGet.
2. Altere a extensão do nome de ficheiro do pacote de .nupkg para .zip.
3. Extraia os conteúdos do ficheiro comprimido (zip).

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

Argumentos da linha de comandos do SolutionPackager

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

Formatos de ficheiro de controlo de versões

O SolutionPackager suporta dois layouts de pastas ao extrair e empacotar soluções.

Formato XML (legado)

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

Formato de controlo de código fonte YAML

Introduzido juntamente com a integração Dataverse Git, este formato armazena metadados da solução como ficheiros YAML distribuídos numa hierarquia estruturada de pastas. É o formato escrito quando fazem-se os commit de soluções usando a integração nativa do Git no Power Apps.

Vantagens em relação ao formato XML

• Produz diferenciais por componente mais limpos e legíveis no controlo de versões
• Suporta múltiplas soluções numa única pasta de repositório
• Os ficheiros de aplicações .msapp Canvas e os fluxos modernos são suportados apenas neste formato
• O remapeamento do nome do tipo de plug-in está ativado por defeito

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 controlo de origem YAML da solução

Regras de deteção automática de formato

Empacotamento de uma pasta em formato YAML

O comando seguinte empacota uma pasta em formato YAML.

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

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

O comando seguinte empacota uma solução especificada numa pasta de múltiplas soluções.

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

Utilize o argumento de comando /map

O seguinte debate detalha a utilização do argumento /map para a ferramenta SolutionPackager.

Os ficheiros que estão integrados num sistema de compilação automatizado, como os ficheiros .xap do Silverlight e as assemblagens de plug-ins, normalmente não são verificados no controlo da origem. Os recursos Web podem já estar presentes no controlo de origens em localizações que não são diretamente compatíveis com a ferramenta SolutionPackager. Ao incluir o parâmetro /map, a ferramenta SolutionPackager pode ser direcionada para ler e criar o pacote destes ficheiros a partir de localizações alternativas, e não a partir de dentro da pasta Extract, como normalmente seria feito. O parâmetro /map tem de especificar o nome e o caminho para um ficheiro XML que contenha diretivas de mapeamento. Essas diretivas instruem o SolutionPackager a corresponder ficheiros pelo respetivo nome e caminho, e indicam a localização alternativa para localizar o ficheiro correspondido. As seguintes informações aplicam-se da mesma forma a todas as diretivas.

• Podem ser listadas várias diretivas, incluindo aquelas que correspondem a ficheiros idênticos. As diretivas listadas no início do ficheiro têm precedência sobre as diretivas listadas posteriormente.

• Se um ficheiro for correspondido a qualquer diretiva, tem de ser encontrado em pelo menos uma localização alternativa. Se não forem encontradas alternativas correspondentes, o SolutionPackager emite um erro.

• Os caminhos da pasta e do ficheiro 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 com uma sintaxe %variable%.

• Um coringa de pasta "**" pode ser usado para significar "em qualquer subpasta". Só pode ser usado como a parte final de um caminho, por exemplo: "c:\folderA\**".

• Os caracteres universais do nome do ficheiro podem ser usados apenas nas formas "*.ext" ou "*.*". Não é suportado nenhum outro padrão.

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

Mapeamento de pastas

As informações que se seguem fornecem informações detalhadas sobre o mapeamento de pastas.

Formato XML

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

Descrição

Os caminhos de ficheiros que correspondem à "pastaA" são alterados para "pastaB".

• A hierarquia de subpastas sob cada uma delas tem de corresponder exatamente.

• Não são suportados carateres universais.

• Não podem ser especificados quaisquer nomes de ficheiros.

  Exemplos

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

Mapeamento Ficheiro para Ficheiro

As informações que se seguem fornecem mais detalhes sobre o mapeamento de ficheiro para ficheiro.

Formato XML

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

Descrição

Qualquer ficheiro que corresponda ao map parâmetro é lido a partir do nome e do caminho especificados no parâmetro to.

Para o parâmetro map:

• Tem de especificar um nome de ficheiro. O caminho é opcional. Se não for especificado nenhum caminho, poderão ser correspondidos os ficheiros de qualquer pasta.

• Não são suportados carateres universais de nome de ficheiro.

• O curinga da pasta é suportado.

  Para o parâmetro to:

• Tem de especificar um nome de ficheiro e caminho.

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

• Os wildcards para nomes de ficheiros não são suportados.

• É suportado o curinga da pasta.

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 do pacote acima NuGet, cr886_PluginPackageTest.nupkg não será substituído se o ficheiro já existir na localização especificada.

Mapeamento de ficheiro para caminho

O texto a seguir fornece informações detalhadas sobre o mapeamento ficheiro-para-caminho.

Formato XML

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

Descrição

Qualquer ficheiro que corresponda ao parâmetro map é lido a partir do caminho especificado no parâmetro to.

Para o parâmetro map:

• Tem de especificar um nome de ficheiro. O caminho é opcional. Se não for especificado nenhum caminho, os ficheiros de qualquer pasta poderão ser encontrados.

• São suportados carateres universais de nome de ficheiro.

• O uso de curinga em nomes de pasta é suportado.

Para o parâmetro to:

• Tem de especificar um caminho.

• É suportado o padrão curinga da pasta.

• Não tem de especificar um nome de ficheiro.

  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" />  

Exemplo de mapeamento

O seguinte exemplo de código XML mostra um ficheiro de mapeamento completo que permite à ferramenta SolutionPackager ler qualquer recurso Web e as duas assemblagens geradas predefinidas de um projeto do Developer Toolkit denominado 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 geridas e não geridas

Um ficheiro de solução comprimido (.zip) do Dataverse pode ser exportado num dos dois tipos, como aqui mostrado.

Solução gerenciada
Uma solução concluída pronta para ser importada para uma organização. Uma vez importados, os componentes não podem ser adicionados nem removidos, embora possam opcionalmente permitir personalizações adicionais. Isto é recomendado quando o desenvolvimento da solução estiver completo.

Solução não gerenciada
Uma solução aberta sem restrições sobre o que pode ser adicionado, removido ou modificado. Isto é recomendado durante o desenvolvimento de uma solução.

O formato de um ficheiro de solução comprimido será diferente com base no respetivo tipo, gerido ou não gerido. O SolutionPackager pode processar ficheiros de solução comprimidos de qualquer tipo. No entanto, a ferramenta não consegue converter um tipo para outro. A única forma de converter ficheiros de solução para um tipo diferente, por exemplo, de não geridos para geridos, é através da importação do ficheiro .zip da solução não gerida num servidor do Dataverse e, em seguida, ao exportar a solução como uma solução gerida.

O SolutionPackager pode processar os ficheiros de soluções .zip não-geridos e geridos como um conjunto combinado através do parâmetro /PackageType:Both. Para executar esta operação, é necessário exportar a sua solução duas vezes em cada tipo, ao atribuir o nome aos ficheiros .zip da seguinte forma.

A ferramenta assumirá a presença do ficheiro .zip gerido na mesma pasta que o ficheiro não gerido, e extrairá ambos os ficheiros para uma única pasta, mantendo as diferenças onde existem componentes geridos e não geridos.

Depois de uma solução ter sido descompactada como não gerida e gerida, torna-se possível, a partir dessa mesma pasta, empacotar ambas, ou cada tipo individualmente, utilizando o parâmetro /PackageType para especificar qual o tipo a criar. Ao especificar ambos os ficheiros, serão produzidos dois ficheiros .zip usando a convenção de nomenclatura acima. Se o parâmetro /PackageType estiver em falta ao criar o pacote a partir de uma pasta gerida e não gerida dupla, a predefinição é produzir um único ficheiro .zip não gerido.

Resolução de Problemas

Mensagem apresentada ao usar o Visual Studio para editar ficheiros de recursos

Se usar Visual Studio para editar fsiles de recursos criados pelo empacotador da solução, pode 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." Isto acontece porque Visual Studio substitui as etiquetas de metadados do ficheiro de recurso por etiquetas de dados.

Solução

1. Abra o ficheiro de recursos no seu editor de texto favorito, e localize e atualize as seguintes etiquetas:

   <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. Mude o nome do nó de <data> para <metadata>.

   Por exemplo, esta sequência:

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

   Muda para:

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

   Isto permite ao Empacotador de Soluções ler e importar o ficheiro de recursos. Este problema só foi observado ao utilizar o editor de Recursos do Visual Studio.

Erro: "Não é possível encontrar o ficheiro requerido ...\Other\Customizations.xml" com uma pasta YAML

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

Causa: A ferramenta deteta o formato YAML de controlo de versões procurando por uma solutions/ subpasta contendo *solution.yml ficheiros. Quando esse diretório está ausente, a ferramenta recorre silenciosamente ao formato XML (legacy) e espera Other\Customizations.xml. A mensagem de erro resultante refere-se a um ficheiro XML e não menciona o YAML, o que é enganador.

Correção: Reorganize a pasta para que os ficheiros de manifestos YAML fiquem nos caminhos corretos:

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

Se obtiveste a pasta a partir de um commit de integração Git ou pac solution clone, a estrutura da pasta já deve estar correta. Uma pasta que contém apenas os ficheiros YAML de topo sem o solutions/ subdiretório representa uma extração incompleta e não pode ser empacotada diretamente.

Aviso: componente declarado em rootcomponents.yml não tem ficheiros fonte

Este aviso aparece quando um componente, como uma aplicação canvas, está listado em rootcomponents.yml, mas não existem ficheiros de origem correspondentes na pasta de componentes esperada (por exemplo, canvasapps/<schema-name>/).

Efeito: A ferramenta continua a ter sucesso (código de saída 0) e produz um ficheiro válido .zip , mas o componente declarado é omitido da solução empacotada.

Causa: A pasta era produzida por um extrato parcial, ou os ficheiros fonte do componente não estavam incluídos no repositório. Por exemplo, apenas os ficheiros do manifesto da solução eram comprometidos e não a própria aplicação canvas.

Correção: Assegure que todos os componentes declarados têm rootcomponents.yml os ficheiros fonte correspondentes presentes na pasta. Para aplicações canvas, o ficheiro .msapp deve existir sob canvasapps/<schema-name>/. Se faltar algum ficheiro, reexporte a solução completa do Dataverse e descompacte-a novamente, ou use pac solution clone para obter uma extração completa.

Consulte também

• Usar o controle do código-fonte com arquivos de solução
• sConceitos de solução