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. Die folgenden Abschnitte zeigen, wie Sie das Tool ausführen und es mit verwalteten und nicht verwalteten Lösungen verwenden.

Wo Sie das SolutionPackager-Tool finden

Das SolutionPackager-Tool wird als Teil des Microsoft.CrmSdk.CoreTools NuGet-Pakets 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 Parametern aufgerufen werden kann, die in der folgenden Tabelle identifiziert sind.

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 des Befehlsarguments /map

Nachfolgend wird die Verwendung des /map-Arguments für das SolutionPackager-Tool erläutert.

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 anderen Orten zu lesen und zu packen, und nicht aus dem Extrahierungs-Ordner wie sonst. 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 gleichermaßen für alle Direktiven.

• 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 einer Direktive zugeordnet wird, muss sie sich an mindestens einem alternativen Ort befinden. 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 von dem im /folder-Parameter angegebenen Ordner evaluiert.

• Umgebungsvariablen können mit einem %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. Kein anderes Muster wird unterstützt.

  Die drei Typen von Direktivenzuordnungen werden hier beschrieben, zusammen mit einem Beispiel für ihre Verwendung.

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 können 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 Parameter map:

• Ein Dateiname muss angegeben werden. Der Pfad ist optional. Falls kein Pfad angegeben wird, können Dateien aus allen Ordnern zugeordnet werden.

• Dateinamenplatzhalter werden nicht unterstützt.

• Der Ordnerplatzhalter wird unterstützt.

  Für den Parameter to:

• Ein Dateiname und ein Pfad muss angegeben werden.

• Der Dateiname weicht möglicherweise von dem Namen im Parameter map ab.

• 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

Nachfolgend sind detaillierte Informationen zur Datei-zu-Pfad-Zuordnung.

Xml-Format

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

Beschreibung

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

Für den Parameter map:

• Ein Dateiname muss angegeben werden. Der Pfad ist optional. Falls kein Pfad angegeben wird, können Dateien aus allen Ordnern zugeordnet werden.

• Dateinamenplatzhalter werden unterstützt.

• Der Ordnerplatzhalter wird unterstützt.

Für den Parameter to:

• Ein Pfad muss angegeben werden.

• Der Ordnerplatzhalter wird unterstützt.

• Ein Dateiname darf nicht 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 das SolutionPackager-Tool in die Lage versetzt, jede Webressource und die beiden generierten Standardassemblys 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 abgeschlossene Lösung, die bereit ist, in eine Organisation importiert zu werden. Nach dem Importieren können Komponenten nicht hinzugefügt oder entfernt werden, obwohl sie optional weitere Anpassungen zulassen können. Dies wird empfohlen, nachdem die Entwicklung der Lösung abgeschlossen ist.

Nicht verwaltete Lösung
Eine offene Lösung ohne Einschränkungen dahingehend, was hinzugefügt, entfernt oder geändert werden kann. Dieses wird während der Entwicklung einer Lösung empfohlen.

Das Format einer komprimierten Lösungsdatei basiert auf dem Typ,verwaltet oder nicht verwaltet. 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 verwaltete und nicht verwaltete Lösungs-ZIP-Dateien als kombinierten Satz über den /PackageType:Both-Parameter verarbeiten. Dazu ist es erforderlich, Ihre Lösung zweimal in jedem Typ zu exportieren, wobei die ZIP-Dateien wie folgt benannt werden.

Das Tool nimmt das Vorhandensein der verwalteten ZIP-Datei im gleichen Ordner wie die nicht verwaltete Datei an und extrahiert beide Dateien in einen einzelnen Ordner, wobei die Unterschiede beibehalten werden, wo verwaltete und nicht verwaltete Komponenten vorhanden sind.

Nachdem eine Lösung als nicht verwaltet und verwaltet extrahiert wurde, ist es möglich, beide aus diesem Ordner zu verpacken (oder beide einzeln), indem der /PackageType-Parameter für die Angabe verwendet wird, welcher Typ erstellt werden soll. Wenn beide Dateien angegeben werden, werden zwei ZIP-Dateien mit der gleichen Namenskonvention wie oben erstellt. Wenn der /PackageType-Parameter bei Packen von einem dualen Ordner (verwaltet und nicht verwaltet) fehlt, ist das Standardvorgehen die Erstellung einer einzelnen nicht verwalteten ZIP-Datei.

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 einem Texteditor Ihrer Wahl, und 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> zu <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>  
   
   

   Dies ermöglicht dem Lösungspacker, die Ressourcendatei zu lesen und zu importieren. Dieses Problem wurde nur beim Verwenden 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

• Verwendung der Quellverwaltung mit Lösungsdateien
• Lösungskonzepte