Strumento SolutionPackager

SolutionPackager è uno strumento in grado di scomporre in modo reversibile un file di soluzione compresso Microsoft Dataverse in più file XML e in 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.

Dove trovare lo strumento SolutionPackager

Lo strumento SolutionPackager viene distribuito come parte del Microsoft. CrmSdk.CoreTools pacchetto NuGet. 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.

Formati di file di controllo del codice sorgente

SolutionPackager supporta due layout di cartelle durante l'estrazione e la compressione di soluzioni.

Formato XML (obsoleto)

Formato originale. I metadati della soluzione vengono archiviati in Other\Solution.xml e Other\Customizations.xmle tutti i file dei componenti vengono estratti in una gerarchia di cartelle flat insieme a tali file. Questo formato è il formato predefinito durante l'estrazione di un .zip file senza più configurazione.

Formato del controllo del codice sorgente YAML

Introdotto insieme all'integrazione di Dataverse Git, questo formato archivia i metadati della soluzione come file YAML distribuiti in una gerarchia di cartelle strutturata. È il formato scritto quando si esegue il commit di soluzioni usando l'integrazione Git nativa in Power Apps.

Vantaggi rispetto al formato XML

• Produce differenze più pulite e leggibili per componente nel controllo del codice sorgente
• Supporta più soluzioni in una singola cartella del repository
• I file dell'app .msapp Canvas e i flussi moderni sono supportati solo in questo formato
• Il mapping del nome tipo di plug-in è abilitato per impostazione predefinita

Struttura di cartelle richiesta

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

Altre informazioni: Informazioni di riferimento sul formato del controllo del codice sorgente YAML della soluzione

Formattare le regole di rilevamento automatico

Compressione di una cartella di formato YAML

Il comando seguente include una cartella di formato YAML.

SolutionPackager.exe /action:Pack /zipfile:MySolution.zip /folder:C:\repos\myrepo

Compressione da una cartella multi-soluzione

Il comando seguente include una soluzione specificata in una cartella multi-soluzione.

SolutionPackager.exe /action:Pack /zipfile:SolutionA.zip /folder:C:\repos\myrepo /SolutionName:SolutionA

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%.

• Un wildcard di cartella "**" può essere usato per indicare "in qualsiasi sottocartella". Può essere usato solo come parte finale di un percorso, ad esempio "c:\folderA\**".

• I caratteri jolly del nome file possono essere utilizzati solo 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 del 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 Dataverse della soluzione compressa (.zip) può essere esportato in uno dei due tipi, come illustrato di seguito.

Soluzione gestita
Una soluzione completata pronta per essere importata in un'organizzazione. Dopo l'importazione, i componenti non possono essere aggiunti o rimossi, anche se facoltativamente possono consentire un'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.

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

Messaggio visualizzato quando si usa Visual Studio per modificare i file di risorse

Se si usa Visual Studio per modificare i file fsile di risorse creati dal packager della soluzione, è possibile che venga visualizzato un messaggio quando si esegue il repack 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." Questo accade perché Visual Studio sostituisce i tag di metadati del file di risorse con i tag di 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 rilevato solo quando si usa l'editor di risorse Visual Studio.

Errore: "Impossibile trovare il file obbligatorio ...\Other\Customizations.xml" con una cartella YAML

Questo errore viene visualizzato quando si esegue SolutionPackager (o pac solution pack) in una cartella contenente file YAML, solution.ymlad esempio , ma tali file vengono inseriti nella radice della cartella anziché all'interno della sottocartella richiesta solutions/<SolutionUniqueName>/ .

Causa: Lo strumento rileva il formato di controllo del codice sorgente YAML cercando una solutions/ sottocartella contenente *solution.yml file. Quando la directory è assente, lo strumento esegue automaticamente il fallback al formato XML (legacy) e prevede Other\Customizations.xml. Il messaggio di errore risultante fa riferimento a un file XML e non menziona YAML, che è fuorviante.

Correzione: Riorganizzare la cartella in modo che i file manifesto YAML si trovino nei percorsi corretti:

<rootFolder>/
  solutions/<YourSolutionUniqueName>/   ← move solution.yml here
    solution.yml
    solutioncomponents.yml
    rootcomponents.yml
    missingdependencies.yml
  publishers/<YourPublisherUniqueName>/
    publisher.yml

Se la cartella è stata ottenuta da un commit di integrazione Git o pac solution clone, la struttura di cartelle dovrebbe essere già corretta. Una cartella che contiene solo i file YAML di primo livello senza la solutions/ sottodirectory rappresenta un estratto incompleto e non può essere compresso direttamente.

Avviso: il componente dichiarato in rootcomponents.yml non contiene file di origine

Questo avviso viene visualizzato quando un componente, ad esempio un'app canvas, è elencato in rootcomponents.yml ma non esistono file di origine corrispondenti nella cartella del componente previsto (ad esempio, canvasapps/<schema-name>/).

Effetto: Lo strumento ha comunque esito positivo (codice di uscita 0) e produce un file valido .zip , ma il componente dichiarato viene omesso dalla soluzione in pacchetto.

Causa: La cartella è stata prodotta da un estratto parziale o i file di origine del componente non sono stati inclusi nel repository. Ad esempio, solo i file manifesto della soluzione sono stati sottoposti a commit e non all'app canvas stessa.

Correzione: Verificare che tutti i componenti dichiarati in rootcomponents.yml abbiano i file di origine corrispondenti presenti nella cartella . Per le app canvas, il .msapp file deve esistere in canvasapps/<schema-name>/. Se mancano file, esportare nuovamente la soluzione completa da Dataverse e decomprimerla oppure usare pac solution clone per ottenere un estratto completo.

Vedi anche

• Utilizzare il controllo del codice sorgente con i file della soluzione
• s Concetti relativi alla soluzione