Erstellen von Paketen für das Package Deployer-Tool

Artikel
07/01/2024

Mit Package Deployer können Administratoren Pakete auf einer Microsoft Dataverse-Instanz bereitstellen. Ein Package Deployer Paket kann aus einem oder allen der folgenden Elemente bestehen:

Eine oder mehrere Dataverse-Lösungsdateien.
Flache Dateien oder exportierte Konfigurationsdatendateien aus dem Konfigurationsmigrationstool. Weitere Informationen zum Tool finden Sie unter Verschieben von Konfigurationsdaten über Instanzen und Organisationen hinweg mit dem Konfigurationsmigrationstool.
Benutzerdefinierter Code, der ausgeführt werden kann, bevor, während oder nachdem das Paket auf der Dataverse-Instanz bereitgestellt wird.
inhaltsspezifische HTML für das Paket, das bei Start und Ende des Bereitstellungsprozesses angezeigt werden kann. Dieser Inhalt kann nützlich sein, um eine Beschreibung der Lösungen und Dateien zu liefern, die in dem Paket bereitgestellt werden.

Notiz

Es gibt einen weiteren Pakettyp, der Plug-In-Paket genannt wird. Diese Art von Paket ist für Plug-in abhängige Assemblies gedacht und hat keine Beziehung zu den Package Deployer-Paketen.

Anforderungen

Stellen Sie sicher, dass Sie alle Lösungs- und anderen Dateien bereithalten, die Sie in das Paket aufnehmen möchten.
Visual Studio 2019 oder später, oder Visual Studio Code.

Überblick über den Prozess

Um ein Package Deployer-Paket zu erstellen, führen Sie die folgenden Schritte aus.

Erstellen Sie ein Visual Studio- oder MSBuild-Projekt
Fügen Sie Lösungen und andere Dateien zu dem Projekt hinzu
Aktualisieren Sie die bereitgestellten HTML-Dateien (optional)
Festlegen von Konfigurationswerten für das Paket
Definieren Sie angepassten Code für das Paket
Erstellen und Bereitstellen des Pakets

Diese Schritte werden in diesem Artikel im Detail beschrieben.

Erstellen Sie ein Paketprojekt

Der erste Schritt besteht darin, ein Visual Studio- oder MSBuild-Projekt für das Paket zu erstellen. Dazu müssen Sie eine der beiden verfügbaren Tool-Erweiterungen auf Ihrem Entwicklungscomputer installiert haben. Wenn Sie Visual Studio Code verwenden, installieren Sie Microsoft Power Platform CLI. Wenn Sie dagegen Visual Studio 2019 oder höher verwenden, installieren Sie Power Platform Tools für Visual Studio

Wählen Sie die entsprechende Registerkarte unten, um zu erfahren, wie Sie ein Projekt mit der gewünschten Tool-Erweiterung erstellen. Beide Tools geben das Projekt in einem ähnlichen Format aus.

Power Platform Befehlszeilenschnittstelle (CLI)
Power Platform Werkzeuge

Führen Sie den pac-Paket init Befehl zum Erstellen des Anfangspakets aus. Mehr Informationen: pac-Paket

pac package init help
pac package init --outputDirectory DeploymentPackage

Die resultierende CLI-Ausgabe enthält die unten abgebildeten Ordner und Dateien. Der Ordnername „DeploymentPackage“ wurde hier als Beispiel verwendet.

C:.
└───DeploymentPackage
    │   DeploymentPackage.csproj
    │   PackageImportExtension.cs
    │
    └───PkgAssets
            ImportConfig.xml
            manifest.ppkg.json

Suchen Sie im erstellten Projekt die Konfigurationsdatei ImportConfig.xml im Ordner PkgAssets und die Datei PackageImportExtension.cs. Sie ändern diese Dateien wie später in diesem Artikel beschrieben.

Sie können ein Visual Studio-Projekt mit der Power Platform-Lösungsvorlage erstellen und später ein Paketprojekt mit der Power Platform-Projektvorlage für die Paketbereitstellung hinzufügen oder direkt ein Projekt mit der Power Platform-Projektvorlage für die Paketbereitstellung erstellen.

Hinzufügen eines Paketprojekts.

Notiz

Wählen Sie nicht die Vorlage Power Platform Paket. Diese Vorlage ist für Plug-in-Pakete gedacht.

Die resultierende Visual Studio-Lösung und das Projekt enthalten die unten abgebildeten Ordner und Dateien. Der Name „Deployment-package“ wurde hier als Beispiel verwendet. Der Inhalt des Inhaltsordners wird hier der Kürze halber nicht angezeigt.

C:.
│   Deployment-package.csproj
│   Deployment-package.sln
│   GettingStarted.html
│   PackageTemplate.cs
│
├───PkgFolder
│   │   ImportConfig.xml
│   │
│   └───Content

In dem erstellten Projekt finden Sie die Konfigurationsdatei ImportConfig.xml im Ordner PkgFolder und die Datei PackageTemplate.cs. Sie ändern diese Dateien wie später in diesem Artikel beschrieben.

Weitere Informationen zur Verwendung der Erweiterung Power Platform für Tools: Schnellstart: Erstellen Sie ein Power Platform Tools Projekt

Paketdateien hinzufügen

Nachdem Sie ein Paketprojekt erstellt haben, können Sie damit beginnen, Lösungen und andere Dateien zu diesem Projekt hinzuzufügen.

Power Platform Befehlszeilenschnittstelle (CLI)
Power Platform Werkzeuge

Wenn Sie die Befehlszeilenschnittstelle (CLI) verwenden, können Sie externe Pakete, Lösungen und Referenzen zu Ihrem Paketprojekt hinzufügen, indem Sie einen der Unterbefehle Hinzufügen verwenden. Geben Sie pac package help ein, um die Liste der Unterbefehle zu sehen. Lassen Sie uns eine Lösung zu unserem Paket hinzufügen.

> pac package add-solution help

Commands:
Usage: pac package add-solution --path [--import-order] [--skip-validation] [--publish-workflows-activate-plugins] [--overwrite-unmanaged-customizations] [--import-mode] [--missing-dependency-behavior] [--dependency-overrides]

> cd .\DeploymentPackage\
> pac package add-solution --path ..\TestSolution_1_0_0_1_managed.zip

The item was added successfully.

Fügen Sie im Bereich Solutions Explorer Ihre Dataverse Lösungen und andere Dateien unter dem Ordner PkgFolder hinzu. Die HTML-Dateien gehören in den Ordner Content. Mehr über diesen HTML-Inhalt erfahren Sie später.
Für jede Datei, die Sie hinzufügen, legen Sie im Bereich Eigenschaften den Wert Kopieren in das Ausgabeverzeichnis auf Immer kopieren fest. Indem Sie diesen Wert festlegen, stellen Sie sicher, dass Ihre Dateien in dem generierten Paket verfügbar sind.

Als nächstes aktualisieren Sie die sprachspezifischen HTML-Dateien.

Erweitern Sie im Bereich Solution Explorer PkgFolder>Content>de-us. Sie finden hier zwei Ordner genannt EndHTML und WelcomeHTML. Diese Ordner enthalten die HTML- und zugehörigen Dateien, mit denen Sie (dem Benutzer) Informationen am Ende und am Anfang des Prozesses der Bereitstellung von Paketen anzeigen können. Bearbeiten Sie die Dateien im HTML-Ordner dieser Ordner, um Informationen hinzuzufügen, die für Ihr Paket angezeigt werden sollen.
Sie können in Ihrem Paket auch HTML-Dateien in anderen Sprachen hinzufügen, damit der Inhalt des HTML in der Sprache der Gebietsschemaeinstellungen der Firma des Benutzers angezeigt wird. Dazu müssen Sie Folgendes tun:
1. Erstellen Sie eine Kopie des Ordners de-DE unter PkgFolder>Inhalt.
2. Benennen Sie den kopierten Ordner entsprechend der Sprache. Benennen Sie ihn für die spanische Sprache beispielsweise mit es-ES.
3. Ändern Sie den Inhalt der HTML-Dateien, um spanischen Inhalt hinzuzufügen.

Konfigurieren Sie das Paket

Definieren Sie die Paketkonfiguration, indem Sie Informationen über Ihr Paket in der Datei ImportConfig.xml im Projekt hinzufügen. Ein Beispiel und Beschreibungen der zu verwendenden gültigen Elemente und Attribute finden Sie in der ImportConfig-Referenz.

Angepassten Code hinzufügen

Sie können angepassten Code hinzufügen, der vor, während und nach dem Import des Pakets in eine Umgebung ausgeführt wird. Folgen Sie dazu den folgenden Anweisungen.

Bearbeiten Sie die Datei PackageTemplate.cs (oder PackageImportExtension.cs) im Stammordner des Projekts.

In der C#-Datei können Sie:

Geben Sie benutzerdefinierten Code ein, der ausgeführt wird, wenn das Paket in der Definition der Überschreibenmethode von InitializeCustomExtension initialisiert wird.

Diese Methode kann angewendet werden, um Benutzer die Ablaufparameter beim Ausführen eines Pakets verwenden zu lassen. Als Entwickler können Sie Unterstützung für jeden Ablaufparameter Ihrem Paket hinzufügen, indem Sie die Eigenschaft RuntimeSettings verwenden, solange Sie Code haben, zum sie basierend auf den Benutzereingaben zu verarbeiten.

Zum Beispiel ermöglicht der folgende Beispielcode einem Ablaufparameter namens SkipChecks für das Paket, der zwei mögliche Werte hat: true oder false. Die Beispielcode prüft, ob der Benutzer irgendwelche Ablaufparameter beim Ausführen von Package Deployer angegeben hat (entweder per Befehlszeile oder per PowerShell) und verarbeitet die Informationen dann entsprechend. Wenn kein Ablaufparameter vom Benutzer beim Ausführen des Pakets spezifiziert wird, ist der Wert der Eigenschaft RuntimeSettings gleich null.
```
public override void InitializeCustomExtension()  
{  
// Do nothing.  

// Validate the state of the runtime settings object.  
if (RuntimeSettings != null)  
{  
PackageLog.Log(string.Format("Runtime Settings populated.  Count = {0}", RuntimeSettings.Count));  
foreach (var setting in RuntimeSettings)  
{  
PackageLog.Log(string.Format("Key={0} | Value={1}", setting.Key, setting.Value.ToString()));  
}  

// Check to see if skip checks is present.  
if ( RuntimeSettings.ContainsKey("SkipChecks") )  
{  
bool bSkipChecks = false;  
if (bool.TryParse((string)RuntimeSettings["SkipChecks"], out bSkipChecks))  
OverrideDataImportSafetyChecks = bSkipChecks;  
}  
}  
else  
PackageLog.Log("Runtime Settings not populated");  
}  
```
Mit diesem Code kann der Administrator über die Befehlszeile oder das Cmdlet Import-CrmPackage angeben, ob die Sicherheitsüberprüfungen übersprungen werden sollen, während das Tool Package Deployer zum Importieren des Pakets ausgeführt wird. Weitere Informationen: Bereitstellen von Paketen mit Package Deployer und Windows PowerShell
Geben Sie kundenspezifischen Code ein, der ausgeführt wird, bevor die Lösungen in die Definition der Überschreibungsmethode von PreSolutionImport importiert werden, um zu spezifizieren, ob Anpassungen bei der Aktualisierung der spezifizierten Lösung in einer Zielinstanz von Dataverse beibehalten oder überschrieben werden sollen, und ob Plug-Ins und Arbeitsflüsse automatisch aktiviert werden.

Verwenden Sie die Außerkraftsetzungsmethodendefinition von RunSolutionUpgradeMigrationStep, um Datenumwandlung oder Aktualisierung zwischen zwei Versionen einer Lösung auszuführen. Diese Methode wird nur aufgerufen, sofern die Lösung, die Sie importieren, in der Dataverse-Zielinstanz bereits vorhanden ist.

Diese Funktion erwartet die folgenden Parameter:

Parameter	Beschreibung
`solutionName`	Der Name des Lösungsherausgebers.
`oldVersion`	Versionsnummer der alten Lösung
`newVersion`	Versionsnummer der neuen Lösung
`oldSolutionId`	GUID der alten Lösung.
`newSolutionId`	GUID der neuen Lösung.

Geben Sie benutzerdefinierten Code ein, der ausgeführt wird, bevor der Lösungsimport abgeschlossen wird, in der Überschreibungsdefinition der Methode BeforeImportStage. Die Beispieldaten und einige Textdateien für die Lösungen, die in der Datei ImportConfig.xml spezifiziert werden, werden importiert, bevor der Lösungsimport abschließt.
Überschreiben Sie die gegenwärtig-vorgewählte Sprache für Konfigurationsdatenimport unter Verwendung der Überschreibungsmethodendefinition von OverrideConfigurationDataFileLanguage. Wenn die spezifizierte Gebietsschema-ID (LCID) der angegebenen Sprache nicht in der Liste von verfügbaren Sprachen im Paket gefunden wird, wird die Standarddatendatei importiert.

Sie spezifizieren die verfügbaren Sprachen für die Konfigurationsdaten im <cmtdatafiles> Knoten in der ImportConfig.xml Datei. Die Standard-Konfigurationsdaten-Importdatei wird im Attribut crmmigdataimportfile in der Datei ImportConfig.xml spezifiziert.

Überspringen der Datenfehler (OverrideDataImportSafetyChecks = wahr) kann hier effektiv sein, wenn Sie sicher sind, dass die Dataverse-Zielinstanz keine Daten enthält.
Geben Sie benutzerdefinierten Code ein, der ausgeführt wird, nachdem der Import abgeschlossen wird, in der Überschreibungsdefinition der Methode AfterPrimaryImport>. Die restlichen Textdateien, die nicht früher importiert wurden, bevor der angestellte Lösungsimport, werden jetzt importiert.

Ändern Sie den Standardnamen Ihres Paketordners in den von Ihnen gewünschten Paketnamen. Benennen Sie dazu den Ordner PkgFolder (oder PkgAssets) im Bereich Solution Explorer um und bearbeiten Sie dann den Rückgabewert unter der Eigenschaft GetImportPackageDataFolderName.

public override string GetImportPackageDataFolderName  
{  
get  
{  
// WARNING this value directly correlates to the folder name in the Solution Explorer where the ImportConfig.xml and sub content is located.  
// Changing this name requires that you also change the correlating name in the Solution Explorer  
return "PkgFolder";  
}  
}

Ändern Sie den Paketnamen, indem Sie den Rückgabewert unter der GetNameOfImport Eigenschaft bearbeiten.
```
public override string GetNameOfImport(bool plural)  
{  
return "Package Short Name";  
}  
```
Dieser zurückgegebene Wert ist der Name Ihres Pakets, der auf der Seite für die Paketauswahl im Dynamics 365 Package Deployer-Assistenten erscheint.
Ändern Sie die Paketbeschreibung, indem Sie den Rückgabewert unter der GetImportPackageDescriptionText Eigenschaft bearbeiten.
```
public override string GetImportPackageDescriptionText  
{  
get { return "Package Description"; }  
}  
```
Dieser zurückgegebene Wert ist die Paketbeschreibung, die neben dem Paketnamen auf der Paketauswahlseite im Package Deployer-Assistenten erscheint.
Ändern Sie den langen Paketnamen, indem Sie den Rückgabewert unter der GetLongNameOfImport Eigenschaft bearbeiten.
```
public override string GetLongNameOfImport  
{  
get { return "Package Long Name"; }  
}  
```
Der lange Paketname wird auf der nächsten Seite angezeigt, nachdem Sie das zu installierende Paket ausgewählt haben.

Darüber hinaus sind die folgenden Funktionen und die Variablen für das Paket verfügbar:

Name	Typ	Beschreibung
CreateProgressItem(String)	Funktion	Wird verwendet, um ein neues Statuselement in der Benutzeroberfläche (UI) zu erstellen.
RaiseUpdateEvent(String, ProgressPanelItemStatus)	Funktion	Wird verwendet, um den Status zu aktualisieren, der beim Aufruf von CreateProgressItem(String) erstellt wird. ProgressPanelItemStatus ist ein Enumeration mit den folgenden Werten: Arbeit = 0 Abgeschlossen = 1 Fehler = 2 Warnung = 3 Unbekannt = 4
RaiseFailEvent(String, Exception)	Funktion	Wird verwendet, um den Import des aktuellen Status mit einer Ausnahmebedingungsnachricht fehlschlagen zu lassen.
IsRoleAssoicatedWithTeam(Guid, Guid)	Funktion	Wird verwendet, um zu ermitteln, ob eine Rolle einem bestimmten Team zugeordnet ist.
IsWorkflowActive(Guid)	Funktion	Wird verwendet, um zu bestimmen, ob ein angegebener Workflow aktiv ist.
PackageLog	Klassenzeiger	Ein Zeiger auf die initialisierte Protokollierungsschnittstelle für das Paket. Diese Schnittstelle wird von einem Paket verwendet, um Nachrichten und Ausnahmen in der Paketprotokolldatei zu protokollieren.
RootControlDispatcher	Eigenschaften	Eine Dispatcher-Schnittstelle, die es Ihrem Steuerelement erlaubt, während der Bereitstellung des Pakets seine eigene Benutzeroberfläche zu rendern. Sie verwenden diese Schnittstelle, um beliebige UI-Elemente oder -Befehle zu verpacken. Es ist wichtig, diese Variable vor der Nutzung auf NULL-Werte zu prüfen, da sie auf einen Wert festgelegt sein können, oder nicht.
CrmSvc	Eigenschaften	Ein Zeiger auf die Klasse CrmServiceClient, die es zulässt, dass ein Paket Dynamics 365 aus dem Paket heraus anspricht. Verwenden Sie diesen Zeiger, um SDK-Methoden und andere Aktionen in den überschriebenen Methoden auszuführen.
DataImportBypass	Eigenschaften	Geben Sie an, ob Dynamics 365 Package Deployer alle Vorgänge des Datenimports überspringt, wie z.B. den Import von Dataverse Beispieldaten, Flat File-Daten und Daten, die vom Konfigurationsmigrationstool exportiert wurden. Geben Sie true oder false an. Der Standardwert ist `false`.
OverrideDataImportSafetyChecks	Eigenschaften	Legen Sie fest, ob Dynamics 365 Package Deployer einige seiner Sicherheitsprüfungen umgeht, was zur Verbesserung der Importleistung beiträgt. Geben Sie `true` oder `false` an. Der Standardwert ist `false`. Sie sollten diese Eigenschaft nur dann auf `true` setzen, wenn die Zielinstanz Dataverse keine Daten enthält.

Speichern Sie Ihr Projekt. Der nächste Schritt besteht darin, das Paket zu erstellen.

Erstellen und Bereitstellen

In den folgenden Abschnitten wird beschrieben, wie ein Paket erstellt und bereitgestellt wird.

Erstellen

Nachfolgend wird die Erstellung Ihres Pakets beschrieben, je nachdem, welches Tool Sie verwenden.

Power Platform Befehlszeilenschnittstelle (CLI)
Power Platform Werkzeuge

Um ein mit der CLI erstelltes Paket zu erstellen, könnten Sie die .csproj-Datei in Visual Studio laden, aber stattdessen verwenden wir den Befehl dotnet und MSBuild. Das folgende Beispiel geht davon aus, dass das Arbeitsverzeichnis die *.csproj-Datei enthält.

> dotnet publish

DeploymentPackage -> C:\Users\peter\Downloads\DeploymentPackage\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip

Optional können Sie sich die Details des erstellten Pakets ansehen.

> pac package show --package .\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip

Ihr Paket besteht aus den folgenden Dateien im Ordner <Project>\Bin\Debug.

<Paketname> Ordner : Der Ordnername ist derselbe, den Sie für Ihren Paketordnernamen in Schritt 2.g dieses Abschnitts geändert haben. Hinzufügen von benutzerdefiniertem Code. Dieser Ordner enthält alle Lösungen, Konfigurationsdaten, Flatfiles und die Inhalte Ihres Pakets.

Notiz

Sie sehen möglicherweise einen .NET-Ordner (z.B. net472), der einen pdpublish-Ordner enthält. Ihre DLL und andere Projektdateien befinden sich in diesem pdpublish-Ordner.

<Paketname> .DLL : Die Assembly enthält den benutzerdefinierten Code für Ihr Paket. Standardmäßig ist der Name der Montage derselbe wie der Name Ihres Projekts.

Bereitstellen

Nachdem Sie ein Paket erstellt haben, können Sie es mit dem Package Deployer Tool, der Windows PowerShell oder einem CLI-Befehl auf der Dataverse Instanz bereitstellen.

Um es mit dem Package Deployer Tool bereitzustellen, laden Sie das Tool zunächst herunter, wie in Dataverse Entwicklungs-Tools beschrieben. Befolgen Sie als Nächstes die detaillierten Informationen zur Paketbereitstellung im Artikel Pakete bereitstellen mit Package Deployer oder Windows PowerShell.
Um Pakete über die CLI bereitzustellen, verwenden Sie den Befehl pac package deploy.
```
> pac package deploy --package .\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip
```
Notiz

Um ein Paket über die CLI in einer Umgebung bereitzustellen, müssen Sie zunächst ein Authentifizierungsprofil festlegen und eine Organisation auswählen. Weitere Informationen: pac auth create, pac org select

Best Practices

Im Folgenden finden Sie einige bewährte Verfahren, die Sie bei der Arbeit mit Package Deployer-Paketen beachten sollten.