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 seções a seguir mostram como executar a ferramenta e como usá-la com soluções gerenciadas e não gerenciadas.

Importante

A ferramenta SolutionPackager já não é a forma recomendada de desempacotar e empacotar soluções. As capacidades da ferramenta SolutionPackager estão incorporadas na CLI da Power Platform. O pac solution comando tem muitos verbos, incluindo unpack, pack, clone, e sync que incorporam as mesmas capacidades subjacentes da ferramenta SolutionPackager.

Onde encontrar a ferramenta SolutionPackager

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

  1. Transfira 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

O SolutionPackager é uma ferramenta de linha de comandos. Pode invocá-lo usando os parâmetros descritos na tabela seguinte.

Argumento Description
/action: {Extract|Pack} Required. A ação a ser executada. A ação pode ser extrair um ficheiro de solução .zip para uma pasta ou empacotar uma pasta em um ficheiro .zip.
/zipfile: <caminho do arquivo> Required. O caminho e o nome de um ficheiro .zip da solução. Ao extrair, o ficheiro tem de existir e de ser legível. Durante a embalagem, o ficheiro é substituído.
/folder: <caminho da pasta> Required. O caminho para uma pasta. Ao extrair, essa pasta é criada e preenchida com arquivos de componentes. Ao empacotar, essa pasta já deve existir e conter arquivos de componentes extraídos anteriormente.
/packagetype: {Não gerenciado|Gerido|Ambos} Opcional. O tipo de pacote a processar. O valor predefinido é Unmanaged. Omita este argumento na maioria dos casos porque a ferramenta pode ler o tipo de pacote dentro do ficheiro .zip ou dos ficheiros componentes. Durante a extração e se especificar Both, os ficheiros .zip da solução gerida e não gerida têm de estar presentes e são processados para uma única pasta. Durante a criação do pacote e se especificar Both, os ficheiros .zip da solução gerida e não gerida são produzidos a partir de uma pasta. Para mais informações, consulte a secção sobre como trabalhar com as soluções geridas e não geridas mais à frente neste artigo.
/allowWrite:{Sim|Não} Opcional. O valor predefinido é Sim. Use este argumento apenas durante uma extração. Quando especificas /allowWrite:No, a ferramenta executa todas as operações mas não escreve nem apaga quaisquer ficheiros. Pode avaliar a operação de extração em segurança sem substituir ou eliminar quaisquer ficheiros existentes.
/allowDelete:{Yes|No|Pedir} Opcional. O valor predefinido é Prompt. Use este argumento apenas durante uma extração. Quando especificas /allowDelete:Yes, a ferramenta apaga automaticamente quaisquer ficheiros presentes na pasta especificada pelo parâmetro /folder que não sejam esperados. Quando especificas /allowDelete:No, a ferramenta não apaga nenhum ficheiro. Quando especifica /allowDelete:Prompt, o utilizador é solicitado através da consola a permitir ou negar todas as operações de eliminação. Se especificar /allowWrite:No, a ferramenta não apaga nenhum ficheiro, mesmo que /allowDelete:Yes for também especificado.
/clobber Opcional. Use este argumento apenas durante uma extração. Quando especificar /clobber, a ferramenta substitui ou elimina ficheiros com o atributo só de leitura definido. Quando não especificado, a ferramenta não sobrescreve nem elimina ficheiros com o atributo de apenas leitura.
/errorlevel: {Off|Error|Warning|Info|Verbose} Opcional. O valor predefinido é Info. Este argumento indica o nível de informações de registo para a saída.
/map: <caminho do arquivo> Opcional. O caminho e o nome de um ficheiro .xml que contém diretivas de mapeamento de ficheiros. Quando usada durante uma extração, a ferramenta lê, a partir de locais alternativos especificados no ficheiro de mapeamento, ficheiros normalmente lidos na pasta especificada pelo parâmetro /folder. Durante uma operação de empacotamento, a ferramenta não grava ficheiros que correspondam às diretivas.
/nologo Opcional. Suprimir a faixa em runtime.
/log: <caminho do arquivo> Opcional. Um caminho e um nome para um arquivo de log. Se o ficheiro já existir, são anexadas novas informações de registo ao ficheiro.
<@ caminho do arquivo> Opcional. Um caminho e um nome para um arquivo que contém argumentos de linha de comando para a ferramenta.
/sourceLoc: <cadeia> Opcional. Esse argumento gera um arquivo de recurso de modelo e é válido somente na extração.

Os valores possíveis são auto ou um código LCID/ISO para o idioma que você deseja exportar. Quando utiliza este argumento, a ferramenta extrai os recursos de cadeia da região determinada como um ficheiro .resx neutro. Se especificares auto ou apenas a forma longa ou curta da opção, usa-se a localização base ou a solução. Você pode usar a forma curta do comando: /src.
/localize Opcional. Extraia ou mescle todos os recursos de cadeia de caracteres em arquivos .resx. Você pode usar a forma curta do comando: /loc. A opção de localização suporta componentes partilhados para ficheiros .resx. Para mais informações, consulte Utilizar recursos Web RESX.
/SolutionName: <nome> Opcional. O nome único da solução a empacotar ou extrair quando a pasta de origem contém múltiplas soluções sob solutions/*/solution.yml. É necessário quando são detetadas mais do que uma solução. Aplica-se apenas ao formato de controlo de código-fonte YAML. Podes usar a forma abreviada do comando: /sn.
/remapPluginTypeNames Opcional. Quando especificado, a ferramenta remapeia os nomes de tipo totalmente qualificados dos plug-ins com base nas assemblies incluídas na solução. Ativado por predefinição no formato de controlo de origem YAML. Podes usar a forma abreviada do comando: /fp.

Formatos de ficheiros de controlo de código fonte

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

Formato XML (legado)

O formato original. A ferramenta armazena metadados da solução em Other\Solution.xml e Other\Customizations.xml. A ferramenta extrai todos os ficheiros de componentes para uma hierarquia de pastas plana juntamente com esses ficheiros. Este formato é o formato predefinido ao extrair um ficheiro .zip sem configuração adicional.

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 consolida soluções utilizando a integração nativa do Git no Power Apps.

Vantagens em relação ao formato XML

  • Produz diffs por componente mais limpos e legíveis no controlo de código fonte.
  • Suporta múltiplas soluções numa única pasta de repositório.
  • Os ficheiros .msapp de aplicações de tela e os fluxos modernos só são suportados neste formato.
  • O remapeamento do nome do tipo de plug-in está ativado por predefiniçã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]/

Importante

A presença de uma solutions/ subpasta contendo *solution.yml ficheiros indica o formato YAML. Se colocar os seus ficheiros de manifesto YAML (solution.yml, solutioncomponents.yml, e assim sucessivamente) na raiz da pasta em vez de sob solutions/<SolutionUniqueName>/, a ferramenta não deteta o formato YAML. A ferramenta recorre ao caminho XML e reporta um erro enganador sobre um ficheiro Customizations.xml em falta. Consulte Resolução de Problemas para informações sobre como resolver este problema.

Mais informações: Referência do formato de controlo de origem YAML da solução

Regras de deteção automática de formato

Condition Formato utilizado
solutions/*/solution.yml encontrado — exatamente uma solução YAML, onde o nome da solução é inferido a partir da pasta
solutions/*/solution.yml — múltiplas soluções encontradas YAML, onde o /SolutionName argumento é necessário
Não há solutions/ subdiretório presente Formato XML (legado)

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 incorporados num sistema de compilação automatizada, como os ficheiros .xap do Silverlight e as assemblagens de plug-ins, normalmente não são verificados no controlo de código fonte. Pode já ter recursos web no controlo de versões em locais que não são diretamente compatíveis com a ferramenta SolutionPackager. Ao incluir o parâmetro /map, pode direcionar a ferramenta SolutionPackager para ler e empacotar esses ficheiros a partir de locais alternativos, em vez de os ler e empacotar a partir da pasta Extract. 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.

  • Pode listar várias diretivas, incluindo as 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 arquivo corresponder a qualquer diretiva, ele deve ser encontrado em pelo menos um local alternativo. Se não forem encontradas alternativas correspondentes, o SolutionPackager emite um erro.

  • Os caminhos das pastas e ficheiros podem ser absolutos ou relativos. Os caminhos relativos são sempre avaliados a partir da pasta especificada pelo parâmetro /folder.

  • Especifique variáveis de ambiente usando a sintaxe %variable%.

  • Utilize um caráter universal de pasta ** para significar "em qualquer subpasta". Só pode usá-lo como parte final de um caminho, por exemplo: c:\folderA\**.

  • Utilize os curingas do nome do ficheiro apenas nas formas *.ext ou *.*. Nenhum outro padrão é suportado.

    A secção seguinte descreve os três tipos de mapeamentos diretivos, juntamente com um exemplo que mostra como os utilizar.

Mapeamento de pastas

A secção seguinte fornece informações detalhadas sobre o mapeamento de pastas.

Formato XML

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

Descrição

Os caminhos de ficheiro que correspondam a "folderA" são alterados para "folderB".

  • A hierarquia das subpastas sob cada pasta deve corresponder exatamente.

  • Não são suportados carateres universais de pastas.

  • Não podes especificar nomes de ficheiros.

    Examples

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

Mapeamento de 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 valor do parâmetro map é lido a partir do nome e do caminho especificados no parâmetro to.

Para o parâmetro map:

  • Especifique um nome de ficheiro. O caminho é opcional. Se não especificares um caminho, o mapeamento pode corresponder a ficheiros de qualquer pasta.

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

  • Suporta o caráter universal da pasta.

    Para o parâmetro to:

  • Especifique um nome de ficheiro e caminho.

  • O nome do ficheiro pode diferir do nome no map parâmetro.

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

  • Suporta o caráter universal da pasta.

Examples

  <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 anterior do pacote NuGet, cr886_PluginPackageTest.nupkg não é sobrescrito se o ficheiro já existir na localização especificada.

Mapeamento de ficheiro para caminho

A secção seguinte fornece informações detalhadas sobre o mapeamento de ficheiro para caminho.

Formato XML

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

Descrição

O parâmetro map especifica o ficheiro a corresponder e o parâmetro to especifica o caminho a partir do qual deve ser lido.

Para o parâmetro map:

  • Especifique um nome de ficheiro. O caminho é opcional. Se não especificares um caminho, o mapeamento pode corresponder a ficheiros de qualquer pasta.

  • Suporta carateres universais de nomes de ficheiro.

  • Suporta o caráter universal da pasta.

Para o parâmetro to:

  • Especifique um caminho.

  • Suporta o caráter universal da pasta.

  • Não especifiquem um nome de ficheiro.

    Examples

  <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

Pode exportar um ficheiro de solução comprimida Dataverse (.zip) como solução gerida ou não gerida.

Solução gerenciada
Uma solução concluída pronta para ser importada para uma organização. Uma vez importado, não pode adicionar ou remover componentes, embora possa, opcionalmente, permitir personalizações adicionais. Use este tipo quando o desenvolvimento da solução estiver concluído.

Solução não gerenciada
Uma solução aberta, sem restrições sobre o que pode adicionar, remover ou modificar. Use este tipo durante o desenvolvimento de uma solução.

O formato de um ficheiro de solução comprimida difere consoante o seu tipo, seja 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, como de não gerido para gerido, é importando o ficheiro .zip da solução não gerida para um servidor Dataverse e depois exportando a solução como solução gerida.

O SolutionPackager pode processar ficheiros de solução não gerida e gerida .zip como um conjunto combinado, utilizando o /PackageType:Both parâmetro. Para realizar esta operação, precisa de exportar a sua solução duas vezes, uma de cada tipo. Nomeie os ficheiros .zip da seguinte forma:

Arquivo .zip não gerenciado: AnyName.zip

Ficheiro .zip controlado: AnyName_managed.zip

A ferramenta assume que o ficheiro zip gerido está na mesma pasta que o ficheiro não gerido. Extrai ambos os ficheiros para uma única pasta e preserva as diferenças onde existem componentes geridos e não geridos.

Depois de extraires uma solução como não gerida e gerida, podes empacotar ambos os tipos ou cada tipo individualmente a partir dessa pasta. Utilize o parâmetro /PackageType para especificar que tipo criar. Quando especifica ambos os ficheiros, a ferramenta produz dois ficheiros .zip usando a convenção de nomenclatura anterior. Se não incluir o parâmetro /PackageType ao criar um pacote a partir de uma pasta dupla gerida e não gerida, a predefinição é produzir um único ficheiro .zip não gerido.

Troubleshooting

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

Se usar o Visual Studio para editar ficheiros de recursos criados pelo empacotador da solução, pode ver 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." Esta mensagem aparece porque o 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 depois 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 cadeia de caracteres:

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

    Muda para:

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

    Esta alteração permite que o empacotador da solução leia e importe o ficheiro de recurso. Este problema ocorre apenas quando se utiliza 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 coloca esses ficheiros na raiz da pasta em vez de dentro da subpasta necessária solutions/<SolutionUniqueName>/ .

Causa:A ferramenta deteta o formato YAML para controlo de código fonte procurando uma subpasta solutions/ que contenha ficheiros *solution.yml. Quando esse diretório está ausente, a ferramenta recorre silenciosamente ao formato XML (legacy) e espera Other\Customizations.xml. A mensagem de erro refere-se a um ficheiro XML e não menciona YAML, o que pode ser confuso.

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á está 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.

Ver também