Ferramenta SolutionPackager
O SolutionPackager é uma ferramenta que pode decompor reversivelmente um arquivo de solução compactado do 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 pacote NuGet Microsoft.CrmSdk.CoreTools. Para instalar o programa, siga estas etapas.
- Baixe o pacote do NuGet.
- Renomeie a extensão de nome de arquivo do pacote de .nupkg para .zip.
- Extraia o conteúdo do arquivo compactado (zip).
Você encontrará o executável SolutionPackager.exe 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.
| Argumento | Description |
|---|---|
| /action: {Extract|Pack} | Obrigatória. Ação a executar. A ação pode ser para extrair um arquivo .zip da solução para uma pasta, ou para empacotar uma pasta em um arquivo .zip. |
| /zipfile: <file path> | Obrigatória. 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: <folder path> | Obrigatória. O caminho para uma pasta. Ao extrair, esta pasta é criada e preenchida com arquivos de componentes. Ao embalar, essa pasta já deve existir e conter arquivos de componentes extraídos anteriormente. |
| /packagetype: {Unmanaged|Managed|Both} | Opcional. O tipo de pacote para processar. O valor padrão não é gerenciado. Este 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 componentes. 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 tópico. |
| /allowWrite:{Yes|No} | Opcional. O valor padrão é Sim. Este argumento é usado somente durante a extração. Quando /allowWrite:No for especificado, a ferramenta executa todas as operações, mas é impedida de escrever ou excluir qualquer arquivo. A operação de extração pode ser avaliada com segurança sem substituir ou excluir os arquivos existentes. |
| /allowDelete:{Yes|No|Prompt} | Opcional. O valor padrão é Prompt. Este argumento é usado somente durante a 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 for especificado, o usuário será solicitado pelo console a permitir ou recusar 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. Este argumento é usado somente durante a extração. Quando /clobber for especificado, os arquivos que tiverem o atributo somente leitura serã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|Error|Warning|Info|Verbose} | Opcional. O valor padrão é Info. Este argumento indica o nível de informações do log de saída. |
| /map: <file path> | Opcional. O caminho e o nome de um arquivo .xml que contém diretivas de mapeamento de arquivos. Quando usado durante uma extração, os arquivos normalmente lidos de dentro da pasta especificada pelo parâmetro /folder são lidos a partir de locais alternados, conforme especificado no arquivo de mapeamento. Durante a operação de pacote, os arquivos que atendem às diretrizes não são escritos. |
| /nologo | Opcional. Omitir a faixa no tempo de execução. |
| /log: <file path> | Opcional. Um caminho e o nome ao arquivo de log. Se o arquivo já existe, novas informações de log são acrescentadas ao arquivo. |
| @ <file path> | Opcional. Um caminho e o nome ao arquivo que contém argumentos de linha de comando para a ferramenta. |
| /sourceLoc: <string> | Opcional. Este argumento gera um arquivo de recurso modelo, e é válido somente no extração. Os valores possíveis são auto ou um código LCID/ISO para o idioma que você deseja exportar. Quando o argumento for 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 o formato abreviado do comando: /src. |
| /localizar | Opcional. Extrair ou mesclar todos os recursos de cadeia de caracteres em arquivos .resx. Você pode usar o formato abreviado do comando: /loc. A opção para localizar oferece suporte a componentes compartilhados para arquivos .resx. Mais informações: Usar recursos da Web RESX |
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%.
Um caractere curinga da pasta “**” pode ser usado para representar "em qualquer subpasta". Ele só pode ser usado como a parte final do caminho, por exemplo: "c:\folderA\**”.
Os caracteres curingas do nome do 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 do arquivo que correspondem a "folderA" são alterados 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 com o parâmetro map será 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" />
Observe que 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 sub-folders -->
<FileToPath map="WebResources\*.*" to="..\..\CrmPackage\WebResources\**" />
<FileToPath map="WebResources\**\*.*" to="..\..\CrmPackage\WebResources\**" />
</Mapping>
Soluções gerenciadas e não gerenciadas
Um arquivo compactado (.zip) do Dataverse da solução 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 possam opcionalmente permitir a personalização futura. 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. Entretanto, a ferramenta não pode converter um tipo para outro. A única maneira de converter arquivos da 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 exportar 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.
| Arquivo .zip não gerenciado: QualquerNome.zip | Arquivo .zip gerenciado: QualquerNome_gerenciado.zip |
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
Se usar o Visual Studio para editar arquivos de recursos criados pelo pacote de soluções, você receberá uma mensagem quando empacotar novamente 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 o Visual Studio substitui as tags de metadados do arquivo de recursos por tags de dados.
Solução alternativa
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">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 Visual Studio.
Consulte também
Usar o Controle do Código-Fonte com arquivos de solução
Conceitos da solução