Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
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 viene illustrato come eseguire lo strumento e come utilizzarlo con soluzioni gestite e non gestite.
Important
Lo strumento SolutionPackager non è più il modo consigliato per decomprimere e comprimere le soluzioni. Le funzionalità dello strumento SolutionPackager vengono incorporate nell'interfaccia della riga di comando di Power Platform. Il pac solution comando include molti verbi, tra cui unpack, packclone, e sync che incorporano le stesse funzionalità sottostanti dello strumento SolutionPackager.
Dove trovare lo strumento SolutionPackager
Lo strumento SolutionPackager viene distribuito come parte del pacchetto NuGet Microsoft.CrmSdk.CoreTools . Esegui la procedura seguente per l'installare il programma.
- Scarica il pacchetto NuGet.
- Rinomina l'estensione del nome file del pacchetto da .nupkg a .zip.
- 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. È possibile richiamarlo usando i parametri descritti nella tabella seguente.
| Argomentazione | Description |
|---|---|
| /action: {Estrai|Confeziona} | Obbligatorio. L'azione da eseguire. L'azione può consistere nell'estrarre un file di .zip soluzione in una cartella o nel comprimere una cartella in un file .zip. |
| /zipfile: <percorso del file> | Obbligatorio. Il percorso e il nome di un file della soluzione .zip. Per l'estrazione, il file deve già esistere e sarà leggibile. Per la compressione, il file viene sostituito. |
| /folder: <percorso della cartella> | Obbligatorio. Percorso di una cartella. Durante l'estrazione, questa cartella viene creata e popolata con i file dei componenti. Durante la compressione, questa cartella deve esistere già e contenere i file dei componenti estratti in precedenza. |
| /packagetype: {Non gestito|Gestito|Entrambi} | Facoltativo. Il tipo di pacchetto da elaborare. Il valore predefinito è Non gestito. Omettere questo argomento nella maggior parte dei casi perché lo strumento può leggere il tipo di pacchetto dall'interno del file .zip o dei file del componente. 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ì. Utilizzare questo argomento solo durante un'estrazione. Quando si specifica /allowWrite:No, lo strumento esegue tutte le operazioni, ma non scrive o elimina alcun file. È possibile verificare in modo sicuro l'operazione di estrazione senza sovrascrivere o eliminare file esistenti. |
| /allowDelete:{Sì|No|Avviso} | Facoltativo. Il valore predefinito è Prompt. Utilizzare questo argomento solo durante un'estrazione. Quando si specifica /allowDelete:Yes, lo strumento elimina automaticamente tutti i file presenti nella cartella specificata dal parametro /folder che non sono previsti. Quando si specifica /allowDelete:No, lo strumento non elimina alcun file. Quando si specifica /allowDelete:Prompt, all'utente viene richiesto tramite la console di consentire o negare tutte le operazioni di eliminazione. Se si specifica /allowWrite:No, lo strumento non elimina alcun file anche se viene specificato anche /allowDelete:Yes. |
| /clobber | Facoltativo. Utilizzare questo argomento solo durante un'estrazione. Quando si specifica /clobber, lo strumento sovrascrive o elimina i file con l'attributo di sola lettura impostato. Se non specificato, lo strumento non sovrascrive o elimina i file con l'attributo di sola lettura. |
| /errorlevel: {Off|Errore |Avviso |Informazioni |Dettagliato} | Facoltativo. Il valore predefinito è Info. Questo argomento indica il livello delle informazioni del registro di output. |
| /map: <percorso del file> | Facoltativo. Il percorso e il nome di un file .xml che contiene direttive per il mapping dei file. Se usato durante un'estrazione, lo strumento legge i file in genere letti dall'interno della cartella specificata dal parametro /folder da percorsi alternativi, come specificato nel file di mapping. Durante un'operazione di tipo pack, lo strumento non scrive file che corrispondono alle istruzioni. |
| /nologo | Facoltativo. Eliminare lo striscione al runtime. |
| /log: <percorso del file> | Facoltativo. Percorso e nome di un file di registro. Se il file esiste già, le nuove informazioni di registrazione vengono aggiunte al file. |
| <@ percorso del file> | Facoltativo. Percorso e nome di un file che contiene gli argomenti della riga di comando dello strumento. |
| /sourceLoc: <string> | Facoltativo. Questo argomento genera un file di risorse 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 si usa questo argomento, lo strumento estrae le risorse stringa dal locale indicato come file .resx neutro. Se si specifica auto o solo la forma lunga o breve dello switch, viene usato il locale di base o la soluzione. È possibile utilizzare la forma abbreviata del comando: /src. |
| /localize | Facoltativo. Estrarre o unire tutte le risorse stringa in file con estensione resx. È possibile utilizzare la forma abbreviata del comando: /loc. L'opzione localize supporta i componenti condivisi per i file .resx. Per altre informazioni, vedere Uso delle risorse Web RESX. |
| /SolutionName: <nome> | Facoltativo. Nome univoco della soluzione da comprimere o estrarre quando la cartella di origine contiene più soluzioni in solutions/*/solution.yml. Obbligatorio quando vengono rilevate più soluzioni. Si applica solo al formato di controllo del codice sorgente YAML. È possibile usare la forma breve del comando : /sn. |
| /remapPluginTypeNames | Facoltativo. Se specificato, lo strumento esegue nuovamente il mapping dei nomi dei tipi completi del plug-in in in base agli assembly inclusi nella soluzione. Abilitato per impostazione predefinita nel formato del controllo del codice sorgente YAML. È possibile usare la forma breve del comando: /fp. |
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. Lo strumento archivia i metadati della soluzione in Other\Solution.xml e Other\Customizations.xml. Lo strumento estrae tutti i file di componente in una gerarchia di cartelle flat insieme a tali file. Questo formato è il formato predefinito quando si estrae un file .zip senza ulteriori configurazioni.
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 delle soluzioni usando l'integrazione Git nativa in Power Apps.
Vantaggi rispetto al formato XML
- Genera diff per componente più puliti e leggibili nel controllo del codice sorgente.
- Supporta più soluzioni in una singola cartella del repository.
- I file dell'app
.msappCanvas e i flussi moderni sono supportati solo in questo formato. - Il mapping del nome del tipo 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]/
Important
La presenza di una solutions/ sottocartella contenente *solution.yml file indica il formato YAML.
Se si inseriscono i file manifesto YAML (solution.yml, solutioncomponents.yml e così via) nella radice della cartella anziché in solutions/<SolutionUniqueName>/, lo strumento non rileva il formato YAML. Lo strumento esegue il fallback al percorso XML e segnala un errore fuorviante relativo a un elemento mancante Customizations.xml. Per informazioni su come risolvere questo problema, vedere Risoluzione dei problemi .
Altre informazioni: Informazioni di riferimento sul formato del controllo del codice sorgente YAML della soluzione
Formattare le regole di rilevamento automatico
| Condizione | Formato usato |
|---|---|
solutions/*/solution.yml trovato — esattamente una soluzione |
Formato YAML, in cui il nome della soluzione viene dedotto dalla cartella |
solutions/*/solution.yml trovato — più soluzioni |
Formato YAML, dove l'argomento /SolutionName è obbligatorio |
Nessuna sottodirectory solutions/ presente |
Formato XML (obsoleto) |
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 discussione seguente viene illustrato in dettaglio l'utilizzo dell'argomento /map per lo strumento SolutionPackager.
I file compilati in un sistema di compilazione automatizzato, ad esempio .xap i file Silverlight e gli assembly plug-in, in genere non vengono archiviati nel controllo del codice sorgente. È possibile che nel controllo del codice sorgente siano già presenti risorse Web che non sono direttamente compatibili con lo strumento SolutionPackager. Includendo il parametro /map, è possibile indirizzare lo strumento SolutionPackager a leggere e creare un pacchetto di tali file da percorsi alternativi anziché dall'interno della cartella Extract. 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 seguenti informazioni si applicano allo stesso modo a tutte le direttive.
È possibile elencare più direttive, incluse quelle che corrispondono a file identici. Le direttive elencate prima nel file hanno la precedenza su quelle specificate dopo.
Se un file corrisponde a una direttiva, deve essere trovato in almeno una posizione alternativa. Se nessuna alternativa corrispondente viene trovata, verranno restituiti errori da SolutionPackager.
I percorsi di cartelle e file possono essere assoluti o relativi. I percorsi relativi vengono sempre valutati dalla cartella specificata dal parametro /folder.
Specificare le variabili di ambiente usando la sintassi
%variable%.Usare un carattere jolly
**della cartella per indicare "in qualsiasi sottocartella". È possibile usarlo solo come parte finale di un percorso, ad esempio :c:\folderA\**.Usare i caratteri jolly nei nomi file solo nelle forme
*.exto*.*. Nessun altro modello è supportato.Nella sezione seguente vengono descritti i tre tipi di mapping delle direttive, insieme a un esempio che illustra come usarli.
Mappatura delle cartelle
Nella sezione seguente vengono fornite informazioni dettagliate sul mapping delle cartelle.
Formato XML
<Folder map="folderA" to="folderB" />
Descrizione
I percorsi di file che corrispondono a "folderA" passano a "folderB".
La gerarchia delle sottocartelle in ogni cartella deve corrispondere esattamente.
I caratteri jolly di cartella non sono supportati.
Non è possibile specificare i nomi di file.
Esempi
<Folder map="folderA" to="folderB" /> <Folder map="folderA\folderB" to="..\..\folderC\" /> <Folder map="WebResources\subFolder" to="%base%\WebResources" />
Mappatura da 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 che corrisponde al parametro map legge il nome e il percorso specificati nel parametro to.
Per il map parametro :
Specificare un nome di file. Il percorso è facoltativo. Se non si specifica un percorso, il mapping può corrispondere ai file di qualsiasi cartella.
I caratteri jolly di nome file non sono supportati.
Supporta il wildcard per le cartelle.
Per il
toparametro :Specificare un nome file e un percorso.
Il nome del file può essere diverso dal nome nel
mapparametro .I caratteri jolly di nome file non sono supportati.
Supporta i caratteri jolly per le cartelle.
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 precedente del pacchetto NuGet, cr886_PluginPackageTest.nupkg non viene sovrascritto se il file esiste già nel percorso specificato.
Mappatura da file a percorso
Nella sezione seguente vengono fornite informazioni dettagliate sul mapping da file a percorso.
Formato XML
<FileToPath map="path\filename.ext" to="path" />
Descrizione
Il parametro map specifica il file da confrontare e il parametro to specifica il percorso da cui leggere.
Per il map parametro :
Specificare un nome di file. Il percorso è facoltativo. Se non si specifica un percorso, il mapping può corrispondere ai file di qualsiasi cartella.
Supporta i caratteri wildcard nel nome file.
Supporta il carattere wildcard della cartella.
Per il to parametro :
Specificare un percorso.
Supporta i metacaratteri per le cartelle.
Non specificare un nome di 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" />
Esempio di mappatura
Nell'esempio di codice XML seguente viene illustrato un file di mapping completo che consente allo strumento SolutionPackager di leggere qualsiasi risorsa Web e i due assembly predefiniti generati da un progetto Developer Toolkit 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
È possibile esportare un file di soluzione compressa dataverse (.zip) come soluzione gestita o non gestita.
Soluzione gestita
Soluzione completata pronta per l'importazione in un'organizzazione. Dopo l'importazione, non è possibile aggiungere o rimuovere componenti, anche se facoltativamente è possibile consentire un'ulteriore personalizzazione. Usare questo tipo al termine dello sviluppo della soluzione.
Soluzione non gestita
Una soluzione aperta senza restrizioni su ciò che è possibile aggiungere, rimuovere o modificare. Usare questo tipo durante lo sviluppo di una soluzione.
Il formato di un file di soluzione compresso è diverso in base al tipo, gestito o non gestito. SolutionPackager è in grado di elaborare file di soluzioni 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 a gestito, consiste nell'importare il file .zip della soluzione non gestita in un server Dataverse e quindi esportare la soluzione come soluzione gestita.
SolutionPackager può elaborare file .zip di soluzione non gestiti e gestiti come set combinato usando il parametro /PackageType:Both. Per eseguire questa operazione, è necessario esportare la soluzione due volte in ciascun tipo. Denominare i file .zip come indicato di seguito:
File di .zip non gestito: AnyName.zip
File .zip gestito: AnyName_managed.zip
Lo strumento presuppone che il file ZIP gestito si trova nella stessa cartella del file non gestito. Estrae entrambi i file in una singola cartella e preserva le differenze nei casi in cui esistono componenti gestiti e non gestiti.
Dopo aver estratto una soluzione come non gestita e gestita, è possibile pacchettizzare entrambi i tipi o ogni tipo singolarmente da tale singola cartella. Usare il /PackageType parametro per specificare il tipo da creare. Quando si specificano entrambi i file, lo strumento produce due file .zip usando la convenzione di denominazione precedente. Se non si include il parametro /PackageType durante la creazione del pacchetto da una doppia cartella gestita e non gestita, l'impostazione predefinita consiste nel produrre 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 di risorse creati dal packager della soluzione, è possibile che venga visualizzato 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." questo messaggio viene visualizzato perché Visual Studio sostituisce i tag di metadati del file di risorse con i tag di dati.
Soluzione alternativa
Aprire il file di risorse nell'editor di testo preferito, quindi 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">Modificare il nome del nodo da
<data>a<metadata>.Ad esempio, questa stringa:
<data name="Source LCID" xml:space="preserve"> <value>1033</value> </data>diventa:
<metadata name="Source LCID" xml:space="preserve"> <value>1033</value> </metadata>Questa modifica consente al packager della soluzione di leggere e importare il file di risorse. Questo problema si verifica 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, ad solution.ymlesempio , ma tali file vengono posizionati 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 fa riferimento a un file XML e non menziona YAML, che può generare confusione.
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 hai ottenuto la cartella da un commit di integrazione Git o pac solution clone, la struttura di cartelle è 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.