Erstellen von Paketen für das Package Deployer-Tool

Package Deployer ermöglicht Administratoren die Bereitstellung von Paketen auf Microsoft Dataverse Instanzen. 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 Configuration Migration Tool. 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.
Paketspezifischer HTML-Inhalt, der zu Beginn und am 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.

Hinweis

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

Voraussetzungen

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

Prozessüberblick

Führen Sie zum Erstellen eines Paketbereitstellungspakets die folgenden Schritte aus:

Erstellen eines Visual Studio- oder MSBuild-Projekts
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

In diesem Artikel werden diese Schritte ausführlich beschrieben.

Erstellen Sie ein Paketprojekt

Erstellen Sie zunächst ein Visual Studio- oder MSBuild-Projekt für das Paket. Um das Projekt zu erstellen, installieren Sie eine von zwei verfügbaren Toolerweiterungen auf Ihrem Entwicklungscomputer. Wenn Sie Visual Studio Code verwenden, installieren Sie Microsoft Power Platform CLI. Wenn Sie Visual Studio 2019 oder höher verwenden, installieren Sie Power Platform-Tools für Visual Studio.

Wenn Sie erfahren möchten, wie Sie ein Projekt mithilfe der gewünschten Toolerweiterung erstellen, wählen Sie im folgenden Abschnitt die entsprechende Registerkarte aus. Beide Tools geben das Projekt in einem ähnlichen Format aus.

Power Platform CLI
Power Platform Tools

Führen Sie den pac-Paket init Befehl zum Erstellen des Anfangspakets aus. Weitere Informationen finden Sie unter pac-Paket.

pac package init help
pac package init --outputDirectory DeploymentPackage

Die CLI-Ausgabe enthält die folgenden Ordner und Dateien. Der Name DeploymentPackage wird hier als Beispiel verwendet.

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

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

Sie können ein Visual Studio-Projekt erstellen, indem Sie die Power Platform-Lösungsvorlage verwenden und später ein Paketprojekt mithilfe der Vorlage „Power Platform Package Deployment Project“ hinzufügen. Alternativ können Sie direkt mithilfe der Vorlage "Power Platform Package Deployment Project" ein Projekt erstellen.

Hinzufügen eines Paketprojekts.

Hinweis

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

Die resultierende Visual Studio Lösung und projekt enthält die Ordner und Dateien, die im folgenden Abschnitt angezeigt werden. Der Name "Deployment-package" wurde hier als Beispiel verwendet. Aus Platzgründen wird der Inhalt des Inhaltsordners 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 weiter unten in diesem Artikel beschrieben.

Weitere Informationen zur Verwendung der Power Platform-Tools-Erweiterung finden Sie in der Schnellstartanleitung: Erstellen eines Power Platform Tools-Projekts.

Paketdateien hinzufügen

Nachdem Sie ein Paketprojekt erstellt haben, können Sie mit dem Hinzufügen von Lösungen und anderen Dateien zu diesem Projekt beginnen.

Power Platform CLI
Power Platform Tools

Wenn Sie die CLI verwenden, können Sie externe Pakete, Lösungen und Verweise auf Ihr Paketprojekt hinzufügen, indem Sie einen der Unterbefehle add 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. Platzieren Sie HTML-Dateien unter dem Content-Ordner.
Legen Sie für jede datei, die Sie hinzufügen, den Wert "Auf Ausgabeverzeichnis kopieren " auf "Immer kopieren " im Eigenschaftenbereich fest. Diese Einstellung stellt sicher, dass Ihre Dateien im generierten Paket verfügbar sind.

Aktualisieren Sie als Nächstes die sprachspezifischen HTML-Dateien.

Erweitern Sie im Bereich Projektmappen-Explorer den Pfad PkgFolder>Content>en-us. Find two folders called EndHTMLandWelcomeHTML`. 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 auch HTML-Dateien in anderen Sprachen zu Ihrem Paket hinzufügen, sodass der Inhalt der HTML-Dateien in der Sprache der Gebietsschemaeinstellungen des Computers des Benutzers angezeigt wird. Führen Sie folgende Schritte durch:
1. Erstellen Sie eine Kopie des Ordners de-DE unter PkgFolder>Inhalt.
2. Benennen Sie den kopierten Ordner in die entsprechende Sprache um. Für Spanisch benennen Sie den Ordner beispielsweise in es-ES um.
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 eine Beschreibung der zu verwendenden gültigen Elemente und Attribute finden Sie unter ImportConfig Reference.

Angepassten Code hinzufügen

Sie können benutzerdefinierten Code hinzufügen, der vor, während und nach dem Importieren des Pakets in eine Umgebung ausgeführt wird. Gehen Sie wie folgt vor, um benutzerdefinierten Code hinzuzufügen:

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

In der C#-Datei können Sie:

Geben Sie benutzerdefinierten Code ein, der ausgeführt werden soll, wenn das Paket in der Definition der Override-Methode von InitializeCustomExtension initialisiert wird.

Verwenden Sie diese Methode, um Benutzern die Verwendung der Laufzeitparameter beim Ausführen eines Pakets zu ermöglichen. Als Entwickler können Sie Unterstützung für jeden Laufzeitparameter Ihrem Paket hinzufügen, indem Sie die Eigenschaft RuntimeSettings verwenden, solange Sie Code haben, um sie basierend auf den Benutzereingaben zu verarbeiten.

Zum Beispiel aktiviert der folgende Beispielcode einen Laufzeitparameter namens SkipChecks für das Paket, der entweder den Wert "true" oder "false" hat. Der Beispielcode überprüft, ob der Benutzer laufzeitparameter beim Ausführen von Package Deployer (entweder mithilfe der Befehlszeile oder PowerShell) angibt und dann die Informationen entsprechend verarbeitet. Wenn der Benutzer beim Ausführen des Pakets keinen Laufzeitparameter angibt, ist der Wert der RuntimeSettings Eigenschaft NULL.
```
public override void InitializeCustomExtension()  
{
  // 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 die Befehlszeile oder das Cmdlet Import-CrmPackage verwenden, um anzugeben, ob die Sicherheitsprüfungen beim Ausführen des Paketbereitstellungstools zum Importieren des Pakets übersprungen werden sollen. Weitere Informationen finden Sie unter Bereitstellen von Paketen mit Package Deployer und Windows PowerShell.
Geben Sie benutzerdefinierten Code ein, der vor dem Import der Lösungen in der Definition der Override-Methode PreSolutionImport ausgeführt werden soll. Verwenden Sie diese Methode, um anzugeben, ob Anpassungen beibehalten oder überschrieben werden sollen, während die angegebene Lösung in einer Dataverse-Zielinstanz aktualisiert wird und ob Plug-Ins und Workflows automatisch aktiviert werden sollen.

Verwenden Sie die Override-Methodendefinition von RunSolutionUpgradeMigrationStep, um Datentransformationen oder Upgrades zwischen zwei Versionen einer Lösung durchzuführen. Diese Methode wird nur ausgeführt, wenn die importierte Lösung bereits in der Dataverse-Zielinstanz vorhanden ist.

Diese Funktion erwartet die folgenden Parameter:

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

Überschreiben Sie die Methode OverrideSolutionImportDecision , um eine UserRequestedImportAction-Enumeration zurückzugeben, die steuert, ob der Import einer Lösung übersprungen, aktualisiert oder hochgestuft wird (Standard).

public override UserRequestedImportAction OverrideSolutionImportDecision(
  string solutionUniqueName, Version organizationVersion,
  Version packageSolutionVersion, Version inboundSolutionVersion,
  Version deployedSolutionVersion, ImportAction systemSelectedImportAction )
{
  return systemSelectedImportAction == 
      ImportAction.Import ? UserRequestedImportAction.ForceUpdate
      : base.OverrideSolutionImportDecision(solutionUniqueName, organizationVersion,
      packageSolutionVersion, inboundSolutionVersion, deployedSolutionVersion,
      systemSelectedImportAction);
}

Geben Sie benutzerdefinierten Code ein, der ausgeführt werden soll, bevor der Lösungsimport in der Überschreibungsdefinition der BeforeImportStage Methode abgeschlossen ist. Das Tool importiert die Beispieldaten und einige Flatfiles für Lösungen, die in der ImportConfig.xml Datei angegeben sind, bevor der Lösungsimport abgeschlossen ist.
Überschreiben Sie die aktuell ausgewählte Sprache für den Import von Konfigurationsdaten mithilfe der Definition der Override-Methode von OverrideConfigurationDataFileLanguage. Wenn die angegebene Gebietsschema-ID (LCID) der angegebenen Sprache nicht in der Liste der 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. Sie geben die Standardkonfigurationsdatenimportdatei im crmmigdataimportfile Attribut in der ImportConfig.xml Datei an.

Das Überspringen der Datenprüfungen (OverrideDataImportSafetyChecks = wahr) kann hier effektiv sein, wenn Sie sicher sind, dass die Dataverse-Zielinstanz keine Daten enthält.
Geben Sie benutzerdefinierten Code ein, der nach Abschluss des Imports in der Überschreibungsdefinition der AfterPrimaryImport Methode ausgeführt werden soll. Das Tool importiert die verbleibenden Flachdateien, die noch nicht zuvor importiert wurden, bevor der Lösungsimport gestartet wurde.

Ändern Sie den Standardnamen Ihres Paketordners in den von Ihnen gewünschten Paketnamen. Benennen Sie dazu den PkgFolder Ordner "PkgAssets" im Bereich „Projektmappen-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 Solution 
        // Explorer where the ImportConfig.xml and sub content is located.  
        // Changing this name requires that you also change the correlating name
        // in 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 des Pakets, das auf der Seite "Paketauswahl" im Assistenten Dynamics 365 Package Deployer angezeigt wird.
Ä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.

Das Paket hat auch Zugriff auf die folgenden Funktionen und Variablen:

Name	Typ	Beschreibung
CreateProgressItem(String)	Funktion	Erstellt ein neues Fortschrittselement in der Benutzeroberfläche (UI).
RaiseUpdateEvent(String, ProgressPanelItemStatus)	Funktion	Aktualisiert das durch den Aufruf CreateProgressItem(String) erstellte Fortschrittsobjekt. ProgressPanelItemStatus ist eine Enumeration mit folgenden Werte: Arbeit = 0 Abgeschlossen = 1 Fehlgeschlagen = 2 Warnung = 3 Unbekannt = 4
RaiseFailEvent(String, Exception)	Funktion	Der aktuelle Statusimport schlägt mit einer Ausnahmemeldung fehl.
IsRoleAssociatedWithTeam(Guid, Guid)	Funktion	Bestimmt, ob eine Rolle einem angegebenen Team zugeordnet ist.
IsWorkflowActive(Guid)	Funktion	Bestimmt, ob ein angegebener Workflow aktiv ist.
PackageLog	Klassenzeiger	Ein Zeiger auf die initialisierte Protokollierungsschnittstelle für das Paket. Das Paket verwendet diese Schnittstelle, um Nachrichten und Ausnahmen in der Paketprotokolldatei zu protokollieren.
RootControlDispatcher	Eigenschaft	Eine Dispatcherschnittstelle, die von Ihrem Steuerelement zum Rendern der eigenen Benutzeroberfläche während der Paketbereitstellung verwendet wird. Sie verwenden diese Schnittstelle, um beliebige UI-Elemente oder -Befehle zu verpacken. Überprüfen Sie diese Variable auf NULL-Werte, bevor Sie sie verwenden, da sie möglicherweise nicht auf einen Wert festgelegt ist.
CrmSvc	Eigenschaft	Ein Zeiger auf die Klasse CrmServiceClient, mit der ein Paket Dynamics 365 innerhalb des Pakets ansprechen kann. Verwenden Sie diesen Zeiger, um SDK-Methoden und andere Aktionen in den überschriebenen Methoden auszuführen.
DataImportBypass	Eigenschaft	Geben Sie an, ob Dynamics 365 Package Deployer alle Datenimportvorgänge überspringt, z. B. das Importieren von Dataverse-Beispieldaten, flachen Dateidaten und Daten, die aus dem Konfigurationsmigrationstool exportiert wurden. Geben Sie `true` oder `false` an. Der Standardwert ist `false`.
OverrideDataImportSafetyChecks	Eigenschaft	Geben Sie an, ob Dynamics 365 Package Deployer einige seiner Sicherheitsprüfungen umgeht, wodurch die Importleistung verbessert wird. Geben Sie `true` oder `false` an. Der Standardwert ist `false`. Legen Sie diese Eigenschaft nur dann auf `true` fest, wenn die Dataverse-Zielinstanz keine Daten enthält.

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

Erstellen und Implementieren

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

Erstellen

In den folgenden Abschnitten wird beschrieben, wie Sie Ihr Paket erstellen, je nachdem, welches Tool Sie verwenden.

Power Platform CLI
Power Platform Tools

Um ein paket zu erstellen, das mit der CLI erstellt wurde, können Sie die .csproj Datei in Visual Studio laden, aber Sie können auch den dotnet Befehl und MSBuild verwenden. Im folgenden Beispiel wird davon ausgegangen, 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 die Details des erstellten Pakets anzeigen.

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

Ihr Paket besteht aus den folgenden Dateien unter dem *<Project>*\Bin\Debug Ordner:

<PackageName> ordner: Der Ordnername entspricht dem Namen, den Sie für Den Paketordner in Schritt 2.g des Abschnitts "Benutzerdefinierten Code hinzufügen " ausgewählt haben. Dieser Ordner enthält alle Lösungen, Konfigurationsdaten, Flatfiles und die Inhalte Ihres Pakets.

Hinweis

Möglicherweise wird ein .NET-Ordner (z. B. net472) angezeigt, der einen pdpublish-Ordner enthält. Ihre DLL und andere Projektdateien befinden sich in diesem pdpublish Ordner.

<PackageName>.dll: Die Assembly enthält den benutzerdefinierten Code für Ihr Paket. Standardmäßig entspricht der Name der Assembly ihrem Projektnamen.

Bereitstellen

Nachdem Sie ein Paket erstellt haben, stellen Sie es mithilfe des Tools „Package Deployer“, Windows PowerShell oder eines CLI-Befehls auf der Dataverse-Instanz bereit.

Um mit dem Tool „Package Deployer“ bereitzustellen, laden Sie zuerst das Tool herunter, wie in den Dataverse-Entwicklungstools beschrieben. Folgen Sie als Nächstes den detaillierten Informationen zur Paketbereitstellung im Artikel Deploy packages using Package Deployer or Windows PowerShell.
Verwenden Sie den pac package deploy Befehl, um mithilfe der CLI bereitzustellen.
```
> pac package deploy --package .\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip
```
Hinweis

Um ein Paket mithilfe der CLI in einer Zielumgebung bereitzustellen, müssen Sie zuerst ein Authentifizierungsprofil einrichten und eine Organisation auswählen. Weitere Informationen finden Sie unter pac auth create und pac org select.

Bewährte Vorgehensweisen

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