SolutionPackager-Tool

SolutionPackager ist ein Tool, das eine Microsoft Dataverse komprimierte Lösungsdatei in mehrere XML-Dateien und andere Dateien umkehrbar dekompilieren kann. Sie können diese Dateienproblemlos mithilfe von einem Versionsverwaltungssystem verwalten. In den folgenden Abschnitten wird gezeigt, wie Sie das Tool ausführen und wie Sie das Tool mit verwalteten und nicht verwalteten Lösungen verwenden.

Wo finde ich das SolutionPackager-Tool?

Das SolutionPackager-Tool wird als Teil des NuGet-Pakets Microsoft.CrmSdk.CoreTools verteilt. Um das Programm zu installieren, führen Sie diese Schritte aus.

1. Laden Sie das NuGet-Paket herunter.
2. Benennen Sie die Dateinamenerweiterung des Pakets von .nupkg in .zip um.
3. Extrahieren Sie den Inhalt der komprimierten (Zip)-Datei.

Suchen Sie die ausführbare SolutionPackager.exe-Datei im Ordner <extracted-folder-name>/contents/bin/coretools. Führen Sie das Programm aus dem Coretools-Ordner aus oder fügen Sie diesen Ordner zu Ihrem PATH hinzu.

SolutionPackager-Befehlszeilenargumente

SolutionPackager ist ein Befehlszeilentool, das mit den in der folgenden Tabelle aufgeführten Parametern aufgerufen werden kann.

Dateiformate für die Quellcodeverwaltung

SolutionPackager unterstützt zwei Ordnerlayouts beim Extrahieren und Verpacken von Lösungen.

XML-Format (veraltet)

Das ursprüngliche Format. Lösungsmetadaten werden in Other\Solution.xml und Other\Customizations.xml gespeichert, und alle Komponentendateien werden zusammen mit diesen Dateien in eine einfache Ordnerstruktur extrahiert. Dieses Format ist das Standardformat beim Extrahieren einer .zip Datei ohne weitere Konfiguration.

YAML-Quellcodeverwaltungsformat

Neben der Integration von Dataverse Git speichert dieses Format Lösungsmetadaten als YAML-Dateien, die über eine strukturierte Ordnerhierarchie verteilt werden. Es ist das Format, das verwendet wird, wenn Sie Lösungen mithilfe der nativen Git-Integration in Power Apps commiten.

Vorteile gegenüber dem XML-Format

• Produziert übersichtlichere, besser lesbare Diffs pro Komponente in der Quellcodeverwaltung
• Unterstützt mehrere Lösungen in einem einzigen Repositoryordner
• Canvas-App-Dateien .msapp und moderne Abläufe werden nur in diesem Format unterstützt.
• Die Neuzuordnung des Plug-In-Typnamens ist standardmäßig aktiviert.

Erforderliche Ordnerstruktur

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

Weitere Informationen: Referenz zum YaML-Quellcodeverwaltungsformat der Lösung

Formatieren von Regeln für die automatische Erkennung

Packen eines YAML-Format-Verzeichnisses

Der folgende Befehl packt einen Ordner im YAML-Format.

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

Entpacken aus einem Ordner mit mehreren Lösungen

Der folgende Befehl enthält eine angegebene Lösung in einem Ordner mit mehreren Lösungen.

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

Verwenden Sie das Befehlsargument /map

In der folgenden Erläuterung wird die Verwendung des /map-Arguments für das SolutionPackager-Tool ausführlich beschrieben.

Dateien, die in einem automatischen System erstellt werden, wie etwa .xap Silverlight-Dateien und Plug-in-Assemblys, werden normalerweise nicht in das Quellcodeverwaltungssystem eingecheckt. Webressourcen können sich bereits in der Quellcodeverwaltung an Orten befinden, die nicht direkt kompatibel mit dem SolutionPackager-Tool sind. Durch das Einschließen des /map-Parameters kann das SolutionPackager-Tool angewiesen werden, solche Dateien von alternativen Speicherorten und nicht aus dem Extract-Ordner zu lesen und zu packen, wie dies normalerweise der Fall wäre. Der Parameter /map muss den Namen und den Pfad zu einer XML-Datei angeben, die Zuordnungsanweisungen enthält. Diese Anweisungen weisen den SolutionPackager an, Dateien anhand ihres Namens und Pfads abzugleichen, und geben den alternativen Speicherort an, um die abgeglichene Datei zu finden. Die folgenden Informationen gelten für alle Direktiven gleichermaßen.

• Es können mehrere Direktiven aufgeführt werden, einschließlich Direktiven, die identische Dateien zuordnen. Früh in der Datei aufgeführte Direktiven haben Vorrang gegenüber den später aufgeführten Direktiven.

• Wenn eine Datei mit einer Direktive übereinstimmt, muss sie an mindestens einem alternativen Speicherort gefunden werden. Wenn keine entsprechenden Alternativen gefunden werden, gibt der SolutionPackager einen Fehler aus.

• Ordner- und Dateipfade können absolut oder relativ sein. Relative Pfade werden immer aus dem Ordner ausgewertet, der durch den Parameter /folder angegeben wird.

• Umgebungsvariablen können mithilfe einer %variable% Syntax angegeben werden.

• Ein Ordner-Wildcard "**" kann verwendet werden, um "in jedem Unterordner" zu bedeuten. Sie kann nur als letzter Teil eines Pfads verwendet werden, z. B. "c:\folderA\**".

• Dateinamen-Wildcards können nur in den Formularen "*.ext" oder "*.*" verwendet werden. Es wird kein anderes Muster unterstützt.

  Die drei Arten von Direktivenzuordnungen werden hier zusammen mit einem Beispiel beschrieben, das Ihnen zeigt, wie Sie sie verwenden.

Ordnerzuordnung

Nachfolgend sind Informationen zur Ordnerzuordnung bereitgestellt.

Xml-Format

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

Beschreibung

Dateipfade, die "folderA" entsprechen, werden zu "folderB" gewechselt.

• Die Hierarchie der Unterordner muss exakt übereinstimmen.

• Ordnerplatzhalter werden nicht unterstützt.

• Es dürfen keine Dateinamen angegeben werden.

  Beispiele

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

Datei-zu-Datei-Zuordnung

Nachfolgende Informationen sind detaillierte Informationen zur Datei-zu-Datei-Zuordnung.

Xml-Format

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

Beschreibung

Jede beliebige Datei, die dem Parameter map entspricht, wird von dem im Parameter to angegebenen Namen und Pfad gelesen.

Für den map Parameter:

• Es muss ein Dateiname angegeben werden. Der Pfad ist optional. Wenn kein Pfad angegeben ist, können Dateien aus einem beliebigen Ordner abgeglichen werden.

• Dateinamenplatzhalter werden nicht unterstützt.

• Der Ordnerplatzhalter wird unterstützt.

  Für den to Parameter:

• Es müssen ein Dateiname und ein Pfad angegeben werden.

• Der Dateiname kann sich vom Namen im map Parameter unterscheiden.

• Dateinamenplatzhalter werden nicht unterstützt.

• Der Ordnerplatzhalter wird unterstützt.

Beispiele

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

Im obigen NuGet-Paketbeispiel wird cr886_PluginPackageTest.nupkg nicht überschrieben, wenn die Datei bereits am angegebenen Speicherort vorhanden ist.

Datei-zu-Pfad-Zuordnung

Im Folgenden finden Sie ausführliche Informationen zur Datei-zu-Pfad-Zuordnung.

Xml-Format

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

Beschreibung

Jede Datei, die dem Parameter entspricht, map wird aus dem im Parameter angegebenen to Pfad gelesen.

Für den map Parameter:

• Es muss ein Dateiname angegeben werden. Der Pfad ist optional. Wenn kein Pfad angegeben ist, können Dateien aus einem beliebigen Ordner abgeglichen werden.

• Dateinamenplatzhalter werden unterstützt.

• Der Ordnerplatzhalter wird unterstützt.

Für den to Parameter:

• Es muss ein Pfad angegeben werden.

• Der Ordnerplatzhalter wird unterstützt.

• Es darf kein Dateiname angegeben werden.

  Beispiele

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

Zuordnungsbeispiel

Das folgende XML-Codebeispiel zeigt eine vollständige Zuordnungsdatei, die es dem SolutionPackager-Tool ermöglicht, jede Webressource und die beiden standardmäßig generierten Assemblys aus einem Developer Toolkit-Projekt mit dem Namen CRMDevTookitSample zu lesen.

<?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>  

Verwaltete und nicht verwaltete Lösungen

Eine komprimierte Lösungsdatei (ZIP) von Dataverse kann auf eine von zwei Weisen exportiert werden.

Verwaltete Lösung
Eine fertige Lösung, die in eine Organisation importiert werden kann. Nach dem Importieren können Komponenten nicht hinzugefügt oder entfernt werden, obwohl sie optional weitere Anpassungen zulassen können. Dies wird empfohlen, wenn die Entwicklung der Lösung abgeschlossen ist.

Nicht verwaltete Lösung
Eine offene Lösung ohne Einschränkungen hinsichtlich dessen, was hinzugefügt, entfernt oder geändert werden kann. Dies wird bei der Entwicklung einer Lösung empfohlen.

Das Format einer komprimierten Lösungsdatei hängt vom Typ ab, ob sie verwaltet oder unverwaltet ist. Der SolutionPackager kann komprimierte Lösungsdateien beider Typen verarbeiten. Das Tool kann jedoch keinen Typ in einen anderen konvertieren. Die einzige Möglichkeit, Lösungsdateien zu einem anderen Typs zu konvertieren, etwa von verwaltete zu nicht verwaltete, besteht im Import der nicht verwalteten Lösungs-ZIP-Datei in einen Dataverse-Server und dem anschließenden Export der Lösung als verwaltete Lösung.

Der SolutionPackager kann sowohl nicht verwaltete als auch verwaltete Lösungsdateien .zip über den Parameter /PackageType:Both als kombinierten Satz verarbeiten. Zum Ausführen dieses Vorgangs ist es erforderlich, Ihre Lösung jeweils als jeden Typ zu exportieren und die .zip-Dateien wie folgt zu benennen.

Das Tool geht davon aus, dass die verwaltete ZIP-Datei im selben Ordner wie die nicht verwaltete Datei vorhanden ist, und extrahiert beide Dateien in einen einzigen Ordner, wobei die Unterschiede zwischen verwalteten und nicht verwalteten Komponenten beibehalten werden.

Nachdem eine Lösung sowohl als nicht verwaltet als auch als verwaltet extrahiert wurde, ist es möglich, aus diesem Ordner beide oder jeden Typ einzeln zu verpacken, indem der Parameter /PackageType verwendet wird, um anzugeben, welcher Typ erstellt werden soll. Wenn beide Dateien angegeben werden, werden zwei ZIP-Dateien mit der gleichen Namenskonvention wie oben erstellt. Wenn der Parameter /PackageType beim Packen aus einem doppelt verwalteten und einem nicht verwalteten Ordner fehlt, wird standardmäßig eine einzelne nicht verwaltete .zip Datei erstellt.

Problembehandlung

Meldung, die beim Bearbeiten von Ressourcendateien mit Visual Studio angezeigt wird

Wenn Sie Visual Studio zum Bearbeiten von Ressourcendateien verwenden, die vom Solution Packager erstellt wurden, erhalten Sie möglicherweise eine Meldung, wenn Sie ein ähnliches Paket wie folgt erneut packen: "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." Dies geschieht, da Visual Studio die Metadaten-Tags der Ressourcendatei durch Daten-Tags ersetzt.

Problemumgehung

1. Öffnen Sie die Ressourcendatei in Ihrem bevorzugten Texteditor, suchen und aktualisieren Sie die folgenden Tags:

   <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. Ändern Sie den Knotennamen von <data> in <metadata>.

   Zum Beispiel: Die Zeichenfolge:

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

   wird geändert zu:

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

   Auf diese Weise kann der Lösungspaketierer die Ressourcendatei lesen und importieren. Dieses Problem wurde nur bei Verwendung des Visual Studio-Ressourcen-Editors beobachtet.

Fehler: "Erforderliche Datei kann nicht gefunden werden ...\Other\Customizations.xml" mit einem YAML-Ordner

Dieser Fehler wird angezeigt, wenn Sie SolutionPackager (oder pac solution pack) für einen Ordner ausführen, der YAML-Dateien wie z. B. solution.yml enthält, diese Dateien jedoch im Stammverzeichnis des Ordners und nicht im erforderlichen Unterordner solutions/<SolutionUniqueName>/ abgelegt sind.

Ursache: Das Tool erkennt das YAML-Quellcodeverwaltungsformat, indem nach einem solutions/ Unterordner gesucht wird, der Dateien enthält *solution.yml . Wenn dieses Verzeichnis nicht vorhanden ist, greift das Tool im Hintergrund auf das XML-Format (Legacyformat) zurück und erwartet Other\Customizations.xml. Die resultierende Fehlermeldung bezieht sich auf eine XML-Datei und erwähnt YAML nicht, was irreführend ist.

Lösung: Ordnen Sie den Ordner neu an, sodass sich die YAML-Manifestdateien unter den richtigen Pfaden befinden:

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

Wenn Sie den Ordner aus einem Git-Integrations-Commit abgerufen haben oder pac solution clone, sollte die Ordnerstruktur bereits korrekt sein. Ein Ordner, der nur die YAML-Dateien der obersten Ebene ohne das solutions/ Unterverzeichnis enthält, stellt einen unvollständigen Extrakt dar und kann nicht direkt gepackt werden.

Warnung: In rootcomponents.yml deklarierte Komponente enthält keine Quelldateien.

Diese Warnung wird angezeigt, wenn eine Komponente, z. B. eine Canvas-App, in rootcomponents.yml aufgeführt ist, aber keine entsprechenden Quelldateien im erwarteten Komponentenordner vorhanden sind (zum Beispiel canvasapps/<schema-name>/).

Wirkung: Das Tool ist weiterhin erfolgreich (Exitcode 0) und erzeugt eine gültige .zip Datei, die deklarierte Komponente wird jedoch aus der verpackten Lösung weggelassen.

Ursache: Der Ordner wurde durch einen Teilextrakt erstellt, oder die Quelldateien der Komponente waren nicht im Repository enthalten. Beispielsweise wurden nur die Lösungsmanifestdateien und nicht die Canvas-App selbst zugesichert.

Lösung: Stellen Sie sicher, dass alle in deklarierten rootcomponents.yml Komponenten über entsprechende Quelldateien im Ordner verfügen. Für Canvas-Apps muss die .msapp Datei unter canvasapps/<schema-name>/vorhanden sein. Wenn Dateien fehlen, exportieren Sie die vollständige Lösung aus Dataverse erneut und entpacken Sie sie, oder verwenden Sie pac solution clone, um einen vollständigen Extrakt zu erhalten.

Siehe auch

• Verwenden der Quellcodeverwaltung mit Lösungsdateien
• Lösungskonzepte