Strumento SolutionPackager

  • Articolo

SolutionPackager è uno strumento in grado di scomporre un file di soluzione Microsoft Dataverse compresso in più file XML e altri file. È quindi possibile gestire facilmente questi file utilizzando un sistema di controllo del codice sorgente. Nelle sezioni seguenti è illustrato come eseguire lo strumento e come utilizzarlo con le soluzioni gestite e non gestite.

Importante

Lo strumento SolutionPackager non è più il modo consigliato per decomprimere e comprimere le soluzioni. Le funzionalità dello strumento SolutionPackager sono state incorporate nella Power Platform CLI. Il comando pac solution ha un numero di verbi tra cui unpack, pack, clone e sync che integrano le stesse funzionalità sottostanti dello strumento SolutionPackager.

Dove trovare lo strumento SolutionPackager

Lo strumento SolutionPackager è distribuito come parte del pacchetto NuGet Microsoft.CrmSdk.CoreTools. Esegui la procedura seguente per l'installare il programma.

  1. Scarica il pacchetto NuGet.
  2. Rinomina l'estensione del nome file del pacchetto da .nupkg a .zip.
  3. Estrai i contenuti del file compresso (zip).

Trovare l'eseguibile SolutionPackager.exe nella cartella <nome-cartella-estratta>/contents/bin/coretools. Esegui il programma dalla cartella coretools o aggiungi quella cartella al tuo PERCORSO.

Argomenti della riga di comando di SolutionPackager

SolutionPackager è uno strumento da riga di comando che può essere richiamato con i parametri identificati nella tabella seguente.

Argomento Description
/action: {Extract|Pack} Obbligatorio. L'azione da eseguire. L'azione può essere l'estrazione di un file .zip della soluzione in una cartella o la compressione di una cartella in un file .zip.
/zipfile: <file path> Obbligatorio. Il percorso e il nome di un file .zip della soluzione. Per l'estrazione, il file deve già esistere e sarà leggibile. Per la compressione, il file viene sostituito.
/folder: <folder path> Obbligatorio. Il percorso di una cartella. Per l'estrazione, questa cartella viene creata e popolata con i file del componente. Per la compressione, la cartella deve già esistere e contenere i file del componente estratti in precedenza.
/packagetype: {Unmanaged|Managed|Both} (Facoltativo). Il tipo di pacchetto da elaborare. Il valore predefinito è Non gestito. L'argomento può essere omesso nella maggior parte delle occasioni perché il tipo di pacchetto può essere letto dai file del componente o dal file .zip. Quando si estrae e Both viene specificato, i file .zip della soluzione gestiti e non gestiti devono essere presenti ed elaborati in una singola cartella. Quando si crea un pacchetto e Both viene specificato, i file .zip della soluzione non gestiti vengono prodotti da una cartella. Per ulteriori informazioni, vedere la sezione sull'utilizzo delle soluzioni gestite e non gestite più avanti in questo articolo.
/allowWrite:{Yes|No} (Facoltativo). Il valore predefinito è Sì. Questo argomento viene utilizzato solo durante l'estrazione. Se /allowWrite:No viene specificato, lo strumento esegue tutte le operazioni, ma non può scrivere né eliminare alcun file. L'operazione di estrazione può essere applicata in sicurezza senza sovrascrivere o eliminare i file esistenti.
/allowDelete:{Yes|No|Prompt} (Facoltativo). Il valore predefinito è Prompt. Questo argomento viene utilizzato solo durante l'estrazione. Se /allowDelete:Yes viene specificato, i file presenti nella cartella specificata dal parametro /folder non previsti vengono automaticamente eliminati. Se /allowDelete:No viene specificato, non viene eseguita alcuna eliminazione. Se /allowDelete:Prompt viene specificato, all'utente viene richiesto tramite la console di consentire o negare tutte le operazioni di eliminazione. Se /allowWrite:No viene specificato, non viene eseguita alcuna eliminazione anche se è specificato anche /allowDelete:Yes.
/clobber (Facoltativo). Questo argomento viene utilizzato solo durante l'estrazione. Se /clobber viene specificato, i file con l'attributo di sola lettura impostato vengono sovrascritti o eliminati. Se non viene specificato, i file con l'attributo di sola lettura non vengono sovrascritti o eliminati.
/errorlevel: {Off|Error|Warning|Info|Verbose} (Facoltativo). Il valore predefinito è Info. Questo argomento indica il livello delle informazioni del registro di output.
/map: <file path> (Facoltativo). Il percorso e il nome di un file .xml che contiene le direttive di mapping dei file. Se utilizzato durante estrazione, i file in genere letti dalla cartella specificata dal parametro /folder vengono letti da posizioni alternative come specificato nel file di mapping. Durante l'operazione di creazione del pacchetto, i file che corrispondono alle direttive non vengono scritti.
/nologo (Facoltativo). Eliminare lo striscione al runtime.
/log: <file path> (Facoltativo). Il percorso e il nome di un file di registro. Se il file è già presente, le nuove informazioni del registro vengono aggiunte in coda al file.
@ <file path> (Facoltativo). Il percorso e il nome di un file contenente gli argomenti della riga di comando per lo strumento.
/sourceLoc: <string> (Facoltativo). Questo argomento genera di un file di risorse di modello ed è valido solo per l'estrazione.

I valori possibili sono auto o un codice LCID/ISO per la lingua che si desidera esportare. Quando questo argomento viene utilizzato, le risorse di tipo stringa dalle impostazioni locali specificate vengono estratte come file con estensione resx indipendente dalla lingua. Se viene specificato auto o semplicemente il formato breve o lungo dell'opzione, vengono usate le impostazioni locali di base o la soluzione. È possibile utilizzare il formato breve del comando: /src.
/localize (Facoltativo). Estrarre o unire tutte le risorse di tipo stringa nei file con estensione resx. È possibile utilizzare il formato breve del comando: /loc. L'opzione localize supporta i componenti condivisi per i file .resx. Ulteriori informazioni: Utilizzo delle risorse Web RESX

Utilizzare l'argomento di comando /map

Nella seguente discussione si definisce l'utilizzo dell'argomento /map per lo strumento SolutionPackager.

I file incorporati in un sistema di compilazione automatizzato, ad esempio assembly di plug-in e file .xap di Silverlight, di solito non vengono archiviati nel controllo del codice sorgente. Le risorse Web possono essere già presenti nel controllo del codice sorgente in posizioni non direttamente compatibili con lo strumento SolutionPackager. Includendo il parametro /map, lo strumento SolutionPackager può essere diretto alla lettura e alla compressione dei file da posizioni alternative e non dalla cartella Extract come in genere accade. Il parametro /map deve specificare il nome e il percorso di un file XML contenente le direttive di mappatura. Tali direttive indicano a SolutionPackager di abbinare i file in base al nome e al percorso e indicano la posizione alternativa per trovare il file corrispondente. Le informazioni seguenti si applicano a tutte le direttive.

  • Possono essere elencate più direttive, incluse quelle che abbinano i file identici. Le direttive elencate prima nel file hanno la precedenza su quelle specificate dopo.

  • Se un file è corrispondente a una direttiva, si deve trovare in almeno un percorso alternativo. Se nessuna alternativa corrispondente viene trovata, verranno restituiti errori da SolutionPackager.

  • I percorsi dei file e delle cartelle devono essere assoluti o relativi. I percorsi relativi vengono sempre valutati dalla cartella specificata dal parametro /folder.

  • Le variabili di ambiente possono essere specificate utilizzando la sintassi %variable%.

  • Il carattere jolly di cartella "**" può essere utilizzato per indicare "in qualsiasi sottocartella". Può essere utilizzato solo come parte finale del percorso, ad esempio: “c:\folderA\**”.

  • Il carattere jolly di nome di file può essere utilizzato nei formati “*.ext” o “*.*”. Nessun altro modello è supportato.

    Di seguito sono descritti i tre tipi di mapping di direttive, insieme a un esempio che illustra come utilizzarli.

Mapping di cartella

Le seguenti informazioni sono dettagliate sul mapping di cartella.

Formato XML

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

Descrizione

I percorsi di file che corrispondono a "folderA" vengono passati a "folderB".

  • La gerarchia delle sottocartelle di ogni percorso deve corrispondere esattamente.

  • I caratteri jolly di cartella non sono supportati.

  • Non è possibile specificare i nomi file.

    Esempi

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

Mapping di file a file

Le seguenti informazioni forniscono più dettagli nel mapping file a file.

Formato XML

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

Descrizione

Qualsiasi file corrispondente al parametro map verrà letto dal nome e dal percorso specificato nel parametro to.

Per il parametro map :

  • Deve essere specificato un nome file. Il percorso è facoltativo. Se non viene specificato alcun percorso, è possibile corrispondere i file di qualsiasi cartella.

  • I caratteri jolly di nome file non sono supportati.

  • Il carattere jolly di cartella non è supportato.

    Per il parametro to :

  • Devono essere specificati un nome file e un percorso.

  • Il nome file può essere diverso dal nome nel parametro map.

  • I caratteri jolly di nome file non sono supportati.

  • Il carattere jolly di cartella non è supportato.

Esempi

  <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" />

Nell'esempio di pacchetto NuGet riportato sopra, cr886_PluginPackageTest.nupkg non viene sovrascritto se il file esiste già nella posizione specificata.

Mapping di file a percorso

Nella tabella seguente sono disponibili le informazione dettagliate sul mapping di file a percorso.

Formato XML

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

Descrizione

Qualsiasi file corrispondente al parametro map viene letto dal percorso specificato nel parametro to.

Per il parametro map :

  • Deve essere specificato un nome file. Il percorso è facoltativo. Se non viene specificato alcun percorso, è possibile corrispondere i file di qualsiasi cartella.

  • I caratteri jolly di nome file sono supportati.

  • Il carattere jolly di cartella non è supportato.

Per il parametro to :

  • Deve essere specificato un percorso.

  • Il carattere jolly di cartella non è supportato.

  • Non deve essere specificato un nome file.

    Esempi

  <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" />

Mapping di esempio

Il seguente esempio di codice XML illustra un file di mapping completo che consente allo strumento SolutionPackager di leggere una risorsa Web e i due assembly generati predefiniti da un progetto Toolkit sviluppatori denominato 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>

Soluzioni gestite e non gestite

Un file (.zip) della soluzione compressa Dataverse può essere esportato in uno dei due tipi, come illustrato di seguito.

Soluzione gestita
Una soluzione completata pronta per essere importata in un'organizzazione. Una volta importata, non è possibile aggiungere o rimuovere i componenti, sebbene possano facoltativamente consentire ulteriore personalizzazione. Questa soluzione è consigliata quando lo sviluppo di soluzioni è stato completato.

Soluzione non gestita
Una soluzione aperta senza limitazioni su ciò che è possibile aggiungere, rimuovere o modificare. Questa soluzione è consigliata quando si sviluppa una soluzione.

Il formato di un file della soluzione compresso sarà diverso a seconda del tipo (gestito o non gestito). SolutionPackager può elaborare file di soluzione compressi di entrambi i tipi. Tuttavia, lo strumento non può convertire un tipo in un altro. L'unico modo per convertire i file di soluzione in un tipo diverso, ad esempio da non gestito in gestito, consiste nell'importare il file .zip della soluzione non gestita in un server Dataverse e quindi nell'esportare la soluzione come soluzione gestita.

SolutionPackager può elaborare file .zip di soluzione gestita e non gestita come set combinato utilizzando il parametro /PackageType:Both. Per eseguire questa operazione, è necessario esportare la soluzione due volte, come ciascun tipo, denominando i file .zip come segue.
File .zip non gestito: AnyName.zip File .zip gestito: AnyName_managed.zip

Lo strumento presuppone la presenza del file .zip gestito nella stessa cartella che contiene il file non gestito ed estrae entrambi i file in una singola cartella mantenendo le differenze tra componenti gestiti e non gestiti esistenti.

Una volta estratta una soluzione come gestita e non gestita, è possibile dalla singola cartella comprimere entrambi i tipi insieme o ogni tipo singolarmente, utilizzando il parametro /PackageType per specificare il tipo da creare. Se si specificano entrambi i file, vengono prodotti due file .zip utilizzando la convenzione di denominazione indicata in precedenza. Se il parametro /PackageType non è presente quando si comprime da una cartella gestita e non gestita, per impostazione predefinita viene prodotto un singolo file .zip non gestito.

Risoluzione dei problemi

Se usi Visual Studio per modificare i file di risorse creati dal programma di creazione del pacchetto della soluzione, quando il pacchetto viene creato nuovamente è possibile ricevere un messaggio simile al seguente: “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.” Ciò si verifica perché Visual Studio sostituisce i tag dei metadati del file di risorse con i tag dei dati.

Soluzione alternativa

  1. Aprire il file di risorse nell'editor di testo desiderato e individuare e aggiornare i tag seguenti:

    <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. Modificare il nome del nodo da <data> a <metadata>.

    Ad esempio, la stringa:

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

    diventa:

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

    Questo consente al programma di creazione del pacchetto della soluzione di leggere e importare il file di risorse. Questo problema è stato osservato solo quando si utilizza l'editor di risorse di Visual Studio.

Vedi anche

Utilizzare il controllo del codice sorgente con i file della soluzione
Concetti della soluzione