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 que pode ser invocada com os parâmetros identificados 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. Esse argumento pode ser omitido na maioria das ocasiões porque o tipo de pacote pode ser lido de dentro do arquivo .zip ou dos 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. Esse argumento é usado somente durante uma extração. Quando /allowWrite:No é especificado, a ferramenta executa todas as operações, mas é impedida de gravar ou excluir arquivos. A operação de extração pode ser avaliada com segurança sem substituir ou excluir nenhum arquivo existente. |
| /allowDelete:{Yes|No|Prompt} | Opcional. O valor padrão é Prompt. Esse argumento é usado somente durante uma extração. Quando /allowDelete:Yes for especificado, todos os arquivos presentes na pasta especificada pelo parâmetro /folder que não forem esperados serão automaticamente excluídos. Quando /allowDelete:No for especificado, nenhuma exclusão ocorrerá. Quando /allowDelete:Prompt é especificado, o usuário é solicitado pelo console a permitir ou negar todas as operações de exclusão. Se /allowWrite:No for especificado, não ocorrerá nenhuma exclusão mesmo se /allowDelete:Yes também for especificado. |
| /clobber | Opcional. Esse argumento é usado somente durante uma extração. Quando /clobber é especificado, os arquivos que têm o atributo somente leitura definido são substituídos ou excluídos. Quando não especificado, os arquivos com o atributo somente leitura não são substituídos ou excluídos. |
| /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 usados durante uma extração, os arquivos normalmente lidos de dentro da pasta especificada pelo parâmetro /folder são lidos de locais alternativos, conforme especificado no arquivo de mapeamento. Durante uma operação de pacote, os arquivos que correspondem às diretivas não são gravados. |
| /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 esse argumento é usado, os recursos de cadeia de caracteres da localidade fornecida são extraídos como um arquivo .resx neutro. Se o auto ou apenas o formato longo ou abreviado do switch for especificado, a localidade base ou a solução serão usadas. 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. Mais informações: 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, os nomes de tipo completamente qualificados do plug-in são remapeados 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. 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
.msappe 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]/
Importante
O formato YAML é detectado automaticamente pela presença de uma solutions/ subpasta que contém *solution.yml arquivos.
Se os arquivos de manifesto YAML (solution.ymlsolutioncomponents.ymle assim por diante) forem colocados na raiz da pasta em vez de em 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 encontrado – 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 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 /map
A discussão a seguir 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. Ao incluir o parâmetro /map, a ferramenta SolutionPackager pode ser direcionada para ler e empacotar esses arquivos de locais alternativos e não de dentro da pasta Extract, 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 informações que se seguem aplicam-se igualmente a todas as directivas.
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 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.
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 "*.*". Não há suporte para nenhum outro padrão.
Os três tipos de mapeamentos de diretivas sã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 para 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 map parâmetro:
Um nome de arquivo deve ser especificado. O caminho é opcional. Se nenhum caminho for especificado, os arquivos de qualquer pasta podem ser exibidos.
Os caracteres curingas do nome do arquivo não possuem suporte.
O caractere curinga da pasta possui suporte.
Para o
toparâmetro:Um nome de arquivo e um caminho devem ser especificados.
O nome do arquivo pode ser diferente do nome no
mapparâmetro.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 ao map parâmetro é lido a partir do caminho especificado no to parâmetro.
Para o map parâmetro:
Um nome de arquivo deve ser especificado. O caminho é opcional. Se nenhum caminho for especificado, os arquivos de qualquer pasta podem ser exibidos.
Os caracteres curingas do nome do arquivo possuem suporte.
O caractere curinga da pasta possui suporte.
Para o to parâmetro:
Um caminho deve ser especificado.
O caractere curinga da pasta possui suporte.
Um nome de 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" />
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
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 completa pronta para ser importada para uma organização. Depois de importados, os componentes não podem ser adicionados ou removidos, embora, opcionalmente, possam permitir uma personalização adicional. Isso é recomendado 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 ser adicionado, removido ou modificado. Isso é recomendado durante o desenvolvimento de uma solução.
O formato de um arquivo de solução compactado será diferente com base em seu tipo, 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, 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 de solução .zip não gerenciados e gerenciados como um conjunto combinado usando o parâmetro /PackageType:Both. Para realizar essa operação, é necessário exportar sua solução duas vezes como cada tipo, nomeando os arquivos .zip da seguinte maneira.
Arquivo .zip não gerenciado: AnyName.zip
Arquivo .zip gerenciado: QualquerNome_gerenciado.zip
A ferramenta assumirá a presença do arquivo zip gerenciado na mesma pasta que o arquivo não gerenciado e extrairá ambos os arquivos em uma única pasta, preservando as diferenças em que existem 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 ao empacotar de uma pasta que contém tanto elementos gerenciados quanto não gerenciados, o padrão será 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 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
Abra o arquivo de recurso em seu editor de texto favorito e localize e atualize as seguintes tags:
<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>Isso permite que o empacotador de soluções 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.