Ferramenta SolutionPackager

  • Artigo

O SolutionPackager é uma ferramenta que pode decompor inversamente um ficheiro de solução comprimido do Microsoft Dataverse em vários 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 pacote Microsoft.CrmSdk.CoreTools NuGet. Para instalar o programa, siga estes passos.

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

Irá encontrar o executável do SolutionPackager.exe na pasta <nome-pasta-extraída>/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.

Argumento Description
/action: {Extract|Pacote} Obrigatório. A ação a executar. A ação pode ser extrair um ficheiro .zip da solução para uma pasta ou colocar uma pasta num pacote num ficheiro .zip.
/zipfile: <caminho do ficheiro> Obrigatório. O caminho e o nome de um ficheiro .zip da solução. Ao extrair, o ficheiro tem de existir e de ser legível. Ao criar o pacote, o ficheiro é substituído.
/folder: <caminho da pasta> Obrigatório. O caminho para uma pasta. Ao extrair, esta pasta é criada e povoada com ficheiros de componentes. Ao criar o pacote, esta pasta já tem de existir e conter os ficheiros de componentes extraídos anteriormente.
/packagetype: {Unmanaged|Managed|Ambos} Opcional. O tipo de pacote a processar. O valor predefinido é Unmanaged. Este argumento pode ser omitido na maioria das ocasiões porque o tipo de pacote pode ser lido a partir de dentro do ficheiro .zip ou dos ficheiros de componentes. Ao extrair e especificar Both, os ficheiros .zip da solução gerida e não gerida têm de estar presentes e ser processados numa ú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 tópico.
/allowWrite:{Yes|Não} Opcional. O valor predefinido é Sim. Este argumento é utilizado apenas durante uma extração. Quando /allowWrite:No é especificado, a ferramenta executa todas as operações, mas está impedida de escrever ou eliminar quaisquer ficheiros. A operação de extração pode ser avaliada em segurança sem substituir ou eliminar quaisquer ficheiros existentes.
/allowDelete:{Yes|No|Pedir} Opcional. O valor predefinido é Prompt. Este argumento é utilizado apenas durante uma extração. Quando /allowDelete:Yes é especificado, quaisquer ficheiros presentes na pasta especificada pelo parâmetro /folder que não sejam esperados serão automaticamente eliminados. Quando /allowDelete:No é especificado, não ocorrem eliminações. Quando /allowDelete:Prompt é especificado, o utilizador é solicitado através da consola para permitir ou negar todas as operações de eliminação. Se /allowWrite:No é especificado, não ocorre qualquer eliminação, mesmo que /allowDelete:Yes também seja especificado.
/clobber Opcional. Este argumento é utilizado apenas durante uma extração. Quando /clobber é especificado, os ficheiros que têm o conjunto de atributos apenas de leitura são substituídos ou eliminados. Quando não especificado, os ficheiros com o atributo só de leitura não são substituídos ou eliminados.
/errorlevel: {Off|Error|Warning|Info|Verboso} Opcional. O valor predefinido é Info. Este argumento indica o nível de informações de registo para a saída.
/map: <caminho do ficheiro> Opcional. O caminho e o nome de um ficheiro .xml que contém diretivas de mapeamento de ficheiros. Quando utilizados durante uma extração, os ficheiros normalmente lidos a partir do interior da pasta especificada pelo parâmetro /folder são lidos a partir de localizações alternativas, conforme especificado no ficheiro de mapeamento. Durante uma operação de criação de pacote, os ficheiros que correspondem às diretivas não são escritos.
/nologo Opcional. Suprimir a faixa em runtime.
/log: <caminho do ficheiro> Opcional. Um caminho e nome para um ficheiro de registo. Se o ficheiro já existir, são anexadas novas informações de registo ao ficheiro.
@ <caminho do ficheiro> Opcional. Um caminho e nome para um ficheiro que contém argumentos de linha de comando para a ferramenta.
/sourceLoc: <cadeia> Opcional. Este argumento gera um ficheiro de recursos de modelo, e é válido apenas ao extrair.

Os valores possíveis são auto ou um código LCID/ISO para o idioma que pretende exportar. Quando este argumento é utilizado, os recursos da cadeia da região determinada são extraídos como um ficheiro .resx neutro. Se for especificado auto ou apenas o formato longo ou curto do parâmetro, é utilizada a região base ou a solução. Pode utilizar o formato curto do comando: /src.
/localize Opcional. Extraia ou una todos os recursos de cadeia em ficheiros .resx. Pode utilizar o formato curto do comando: /loc. A opção de localização suporta componentes partilhados para ficheiros .resx. Mais informações: Utilizar recursos Web RESX

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 as diretivas que correspondem 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 caráter universal de pasta “**” pode ser utilizado para indicar "em qualquer subpasta". Só pode ser utilizado como parte final de um caminho, por exemplo: “c:\folderA\**”.

  • Os carateres universais de nome de ficheiro só podem ser utilizados nos formatos “*.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 ficheiro que correspondam a “folderA” são alterados para "folderB”.

  • A hierarquia de subpastas sob cada um 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 parâmetro map será 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.

  • É suportado o caráter universal da pasta.

    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.

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

  • É suportado o caráter universal 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" />

Note que, no exemplo do pacote NuGet acima, o cr886_PluginPackageTest.nupkg não é substituído se o ficheiro já existir na localização especificada.

Correspondência ficheiro para caminho

O seguinte 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, poderão ser correspondidos os ficheiros de qualquer pasta.

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

  • É suportado o caráter universal da pasta.

Para o parâmetro to:

  • Tem de especificar um caminho.

  • É suportado o caráter universal 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 sub-folders -->  
       <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 gerida
Uma solução concluída pronta para ser importada para uma organização. Depois de importados, os componentes não podem ser adicionados ou removidos, apesar de opcionalmente poderem permitir uma maior personalização. Isto é recomendado quando o desenvolvimento da solução estiver completo.

Solução não gerida
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 pode converter um tipo noutro. 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 ficheiros .zip da solução 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.
Ficheiro .zip não gerido: AnyName.zip Ficheiro .zip gerido: AnyName_managed.zip

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 ser extraída como não gerida e gerida, é possível, a partir dessa única pasta, colocar ambas num pacote, ou cada tipo individualmente, com o parâmetro /PackageType para especificar o tipo a criar. Ao especificar ambos, os ficheiros serão produzidos dois ficheiros .zip com 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

Se utilizar o Visual Studio para editar ficheiros de recursos criados pelo Empacotador de Soluções, poderá receber uma mensagem quando voltar a reempacotar de forma 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 o Visual Studio substitui as etiquetas de metadados do ficheiro de recursos com 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 cadeia:

    <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 quando ao utilizar o Editor de recursos do Visual Studio.

Consulte também

Utilizar o Controlo de Origem com Ficheiros da Solução

Conceitos da solução