Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
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.
Importante
A ferramenta SolutionPackager não é mais a maneira recomendada de descompactar e compactar soluções. Os recursos da ferramenta SolutionPackager são incorporados à CLI do Power Platform. O pac solution comando tem muitos verbos, incluindo unpack, packclonee sync que incorporam os mesmos recursos subjacentes da ferramenta SolutionPackager.
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.
- Baixe o pacote NuGet.
- Renomeie a extensão de nome de arquivo do pacote de .nupkg para .zip.
- 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 do SolutionPackager
SolutionPackager é uma ferramenta de linha de comando. Você pode invocá-lo usando os parâmetros descritos na tabela a seguir.
| Argument | Description |
|---|---|
| /ação: {Extrair|Empacotar} | Obrigatório. A ação a ser executada. A ação pode ser extrair um arquivo de solução .zip para uma pasta, ou empacotar uma pasta em um arquivo .zip. |
| /zipfile: <caminho do arquivo> | Obrigatório. O caminho e o nome de um arquivo .zip da solução. Ao extrair, o arquivo deve existir e estar legível. Ao embalar, o arquivo é substituído. |
| /folder: <caminho da pasta> | Obrigatório. O caminho para uma pasta. Ao extrair, essa pasta é criada e preenchida com arquivos de componente. Ao empacotar, essa pasta já deve existir e conter arquivos de componentes extraídos anteriormente. |
| /tipo de pacote: {Não gerenciado|Gerenciado|Ambos} | Opcional. O tipo de pacote a ser processado. O valor padrão é Não gerenciado. Omita esse argumento na maioria dos casos porque a ferramenta pode ler o tipo de pacote de dentro do arquivo .zip ou arquivos de componente. Ao extrair e Ambos for especificado, os arquivos .zip gerenciados e não gerenciados da solução deverão estar presentes e serão processados em uma única pasta. Ao empacotar e Ambos for especificado, os arquivos .zip gerenciados e não gerenciados da solução serão gerados a partir de uma pasta. Para obter mais informações, consulte a seção sobre como trabalhar com soluções gerenciadas e não gerenciadas mais adiante neste artigo. |
| /allowWrite:{Sim|Não} | Opcional. O valor padrão é Sim. Use este argumento somente durante a extração. Quando você especifica /allowWrite:No, a ferramenta executa todas as operações, mas não grava nem exclui nenhum arquivo. Você pode testar com segurança a operação de extração sem substituir ou excluir arquivos existentes. |
| /allowDelete:{Yes|No|Prompt} | Opcional. O valor padrão é Prompt. Use esse argumento somente durante uma extração. Quando você especifica /allowDelete:Yes, a ferramenta exclui automaticamente todos os arquivos presentes na pasta especificada pelo parâmetro /folder que não são esperados. Quando você especifica /allowDelete:No, a ferramenta não exclui nenhum arquivo. Quando você especifica /allowDelete:Prompt, o usuário recebe uma solicitação no console para permitir ou rejeitar todas as operações de exclusão. Se você especificar /allowWrite:No, a ferramenta não excluirá nenhum arquivo mesmo que /allowDelete:Yes também seja especificado. |
| /clobber | Opcional. Utilize este argumento somente durante uma extração. Quando você especifica /clobber, a ferramenta substitui ou exclui arquivos que têm o atributo somente leitura definido. Quando não especificado, a ferramenta não substitui nem exclui arquivos com o atributo somente leitura. |
| /errorlevel: {Off|Erro|Aviso|Informações|Detalhado} | Opcional. O valor padrão é Info. Esse argumento indica o nível de informações de log a serem exibidas. |
| /map: <caminho do arquivo> | Opcional. O caminho e o nome de um arquivo .xml que contém diretivas de mapeamento de arquivo. Quando usada durante uma extração, a ferramenta lê, de locais alternativos, arquivos normalmente lidos da pasta especificada pelo parâmetro /folder, conforme especificado no arquivo de mapeamento. Durante uma operação de empacotamento, a ferramenta não grava arquivos que correspondam às diretivas. |
| /nologo | Opcional. Omitir a faixa no tempo de execução. |
| /log: <caminho do arquivo> | Opcional. Um caminho e um nome para um arquivo de log. Se o arquivo já existir, novas informações de log serão anexadas ao arquivo. |
| <@ caminho do arquivo> | Opcional. Um caminho e um nome para um arquivo que contém argumentos de linha de comando para a ferramenta. |
| /sourceLoc: <string> | 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 você usa esse argumento, a ferramenta extrai os recursos de cadeia de caracteres da localidade fornecida como um arquivo .resx neutro. Se você especificar auto ou apenas a forma longa ou curta da opção, a localidade padrão ou a solução será usada. Você pode usar a forma abreviada do comando: /src. |
| /localizar | Opcional. Extraia ou mescle todos os recursos de cadeia de caracteres em arquivos .resx. Você pode usar a forma abreviada do comando: /loc. A opção para localizar oferece suporte a componentes compartilhados para arquivos .resx. Para obter mais informações, consulte Como usar recursos da Web RESX. |
| /SolutionName: <nome> | Opcional. O nome exclusivo da solução a ser empacotada ou extraída quando a pasta de origem contiver várias soluções em solutions/*/solution.yml. Necessário quando mais de uma solução é detectada. Aplica-se apenas ao formato de controle do código-fonte YAML. Você pode usar a forma curta do comando: /sn. |
| /remapPluginTypeNames | Opcional. Quando especificado, a ferramenta remapea nomes de tipo totalmente qualificados do plug-in com base nos assemblies incluídos na solução. Habilitado por padrão no formato de controle do código-fonte YAML. Você pode usar a forma curta do comando: /fp. |
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. A ferramenta armazena metadados da solução em Other\Solution.xml e Other\Customizations.xml. A ferramenta extrai todos os arquivos de componente em uma hierarquia plana de pastas ao lado desses arquivos. Esse formato é o formato padrão quando você extrai um arquivo .zip 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
.msappe fluxos modernos só têm suporte nesse formato. - O remapeamento de nomes de tipo de plug-in 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]/
Importante
A presença de uma subpasta solutions/ que contém arquivos *solution.yml indica o formato YAML.
Se você colocar seus arquivos de manifesto YAML (solution.yml, solutioncomponents.yml, e assim por diante) na raiz da pasta em vez de sob solutions/<SolutionUniqueName>/, a ferramenta não detectará o formato YAML. A ferramenta volta para o caminho XML e relata um erro enganoso sobre um erro ausente Customizations.xml. Consulte solução de problemas para obter informações sobre como corrigir esse problema.
Mais informações: Referência do formato de controle do código-fonte YAML da solução
Formatar regras de detecção automática
| Condição | Formato usado |
|---|---|
solutions/*/solution.yml encontrada – exatamente uma solução |
Formato YAML, em que o nome da solução é inferido da pasta |
solutions/*/solution.yml encontrado – várias soluções |
Formato YAML, em que o /SolutionName argumento é necessário |
Nenhum solutions/ subdiretório presente |
Formato XML (herdado) |
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 várias 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 /map
A discussão a seguir detalha o uso do argumento /map para a ferramenta SolutionPackager.
Os arquivos criados em um sistema de build automatizado, como .xap arquivos Silverlight e assemblies de plug-in, normalmente não são adicionados ao controle de versão. Talvez você já tenha recursos da Web no controle do código-fonte em locais que não são diretamente compatíveis com a ferramenta SolutionPackager. Ao incluir o parâmetro /map, você pode direcionar a ferramenta SolutionPackager para ler e empacotar esses arquivos de locais alternativos em vez de dentro da pasta Extract. 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 informações que se seguem aplicam-se igualmente a todas as directivas.
Você pode listar várias diretivas, incluindo as diretivas que correspondem a arquivos idênticos. Diretivas listadas no início do arquivo têm prioridade sobre as listadas posteriormente.
Se um arquivo corresponder a qualquer diretiva, ele deverá ser encontrado em pelo menos um local alternativo. Se não forem encontradas alternativas correspondentes, o SolutionPackager emitirá um erro.
Os caminhos de pasta e arquivo 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%.Use um curinga
**de pasta para indicar "em qualquer subpasta". Você só pode usá-lo como a parte final de um caminho, por exemplo:c:\folderA\**.Use curingas de nome de arquivo somente nas formas
*.extou*.*. Não há suporte para nenhum outro padrão.A seção a seguir descreve os três tipos de mapeamentos de diretiva, juntamente com um exemplo que mostra como usá-los.
Mapeamento de pasta
A seção a seguir fornece informações detalhadas sobre o mapeamento de pastas.
Formato XML
<Folder map="folderA" to="folderB" />
Descrição
Caminhos de arquivo que correspondem a "folderA" mudam para "folderB".
A hierarquia de subpastas em cada pasta deve corresponder exatamente.
Os caracteres curingas da pasta não têm suporte.
Você não pode especificar nomes de arquivo.
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 lê a partir do nome e do caminho especificados no parâmetro to.
Para o map parâmetro:
Especifique um nome de arquivo. O caminho é opcional. Se você não especificar um caminho, o mapeamento poderá corresponder a arquivos de qualquer pasta.
Os caracteres curingas do nome do arquivo não possuem suporte.
Dá suporte ao curinga da pasta.
Para o
toparâmetro:Especifique um nome de arquivo e o caminho do arquivo.
O nome do arquivo pode ser diferente do nome no parâmetro
map.Os caracteres curingas do nome do arquivo não possuem suporte.
Dá suporte ao 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 de pacote NuGet anterior, cr886_PluginPackageTest.nupkg não é substituído se o arquivo já existir no local especificado.
Mapeamento de arquivo para caminho
A seção a seguir fornece informações detalhadas sobre o mapeamento de arquivo para caminho.
Formato XML
<FileToPath map="path\filename.ext" to="path" />
Descrição
O parâmetro map especifica o arquivo para correspondência, e o parâmetro to especifica o caminho do qual ler.
Para o map parâmetro:
Especifique um nome de arquivo. O caminho é opcional. Se você não especificar um caminho, o mapeamento poderá corresponder a arquivos de qualquer pasta.
Dá suporte a curingas de nome de arquivo.
Dá suporte ao curinga da pasta.
Para o to parâmetro:
Especifique um caminho.
Dá suporte ao curinga da pasta.
Não especifique um nome de arquivo.
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 exemplo de código XML a seguir mostra um arquivo de mapeamento completo que permite que a ferramenta SolutionPackager leia qualquer recurso da Web e os dois assemblies gerados padrão de um projeto do Developer Toolkit 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
Você pode exportar um arquivo de solução compactada do Dataverse (.zip) como uma solução gerenciada ou não gerenciada.
Solução gerenciada
Uma solução concluída pronta para importar para uma organização. Depois de importado, você não pode adicionar ou remover componentes, embora possa, opcionalmente, permitir mais personalização. Use esse tipo quando o desenvolvimento da solução for concluído.
Solução não gerenciada
Uma solução aberta sem restrições sobre o que você pode adicionar, remover ou modificar. Use este tipo durante o desenvolvimento de uma solução.
O formato de um arquivo de solução compactada varia de acordo com seu tipo, seja gerenciado ou não gerenciado. O SolutionPackager pode processar arquivos de 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, como de não gerenciada para gerenciada, é importar o arquivo .zip da solução não gerenciada para um servidor Dataverse e, em seguida, exportar a solução como uma solução gerenciada.
O SolutionPackager pode processar arquivos .zip de solução não gerenciada e gerenciada como um conjunto combinado usando o parâmetro /PackageType:Both. Para executar essa operação, você precisa exportar sua solução duas vezes, uma para cada tipo. Nomeie os arquivos .zip da seguinte maneira:
Arquivo .zip não gerenciado: AnyName.zip
Arquivo .zip gerenciado: QualquerNome_gerenciado.zip
A ferramenta pressupõe que o arquivo .zip gerenciado esteja na mesma pasta do arquivo não gerenciado. Ele extrai os dois arquivos em uma única pasta e preserva as diferenças onde houver componentes gerenciados e não gerenciados.
Depois de extrair uma solução como não gerenciada e gerenciada, você pode empacotar os dois tipos ou cada tipo individualmente dessa mesma pasta. Use o parâmetro /PackageType para especificar qual tipo criar. Quando você especifica os dois arquivos, a ferramenta produz dois arquivos .zip usando a convenção de nomenclatura anterior. Se você não incluir o parâmetro /PackageType ao empacotar de uma pasta dupla, gerenciada e não gerenciada, o padrão é produzir um único arquivo .zip não gerenciado.
Solucionando problemas
Mensagem exibida ao usar Visual Studio para editar arquivos de recurso
Se você usar Visual Studio para editar arquivos de recurso criados pelo empacotador de soluções, poderá 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." essa mensagem é exibida porque Visual Studio substitui as marcas de metadados do arquivo de recurso por marcas de dados.
Solução alternativa
Abra o arquivo de recurso no editor de texto favorito e localize e atualize as seguintes marcas:
<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">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ções em:
<metadata name="Source LCID" xml:space="preserve"> <value>1033</value> </metadata>Essa alteração permite que o empacotador de soluções leia e importe o arquivo de recursos. Esse problema ocorre somente quando você usa 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 você coloca esses arquivos 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 refere-se a um arquivo XML e não menciona YAML, o que pode ser confuso.
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á está 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 confirmados, 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 arquivo .msapp deve estar 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.