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 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.
• HTML-Inhalte, die speziell für das Paket sind und zu Beginn und am Ende des Bereitstellungsvorgangs angezeigt werden können. Dieser Inhalt kann nützlich sein, um eine Beschreibung der Lösungen und Dateien zu liefern, die in dem Paket bereitgestellt werden.

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 höher oder Visual Studio Code.

Überblick über den Prozess

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

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 andernfalls 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.

pac package init help
pac package init --outputDirectory DeploymentPackage

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

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

Paketdateien hinzufügen

Nachdem Sie ein Paketprojekt erstellt haben, können Sie damit beginnen, Lösungen und andere Dateien zu diesem Projekt hinzuzufü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.

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.

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

2. In der C#-Datei können Sie:

   1. Geben Sie benutzerdefinierten Code in der Definition der Überschreibungsmethode von InitializeCustomExtension ein, der ausgeführt wird, wenn das Paket 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 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. 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()  
      {
        // 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: Pakete bereitstellen mit dem Paket-Tool und Windows PowerShell

   2. 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.

   3. 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	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.

   4. Überschreiben Sie die Methode OverrideSolutionImportDecision, um eine UserRequestedImportAction-Enumeration zurückzugeben, die steuert, ob der Import einer Lösung übersprungen, aktualisiert oder upgegradet 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);
      }
      

   5. 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 Flat Files für die in der Datei ImportConfig.xml angegebenen Lösungen werden vor Abschluss des Lösungsimports importiert.

   6. Überschreiben Sie die aktuell ausgewählte Sprache für den Import von Konfigurationsdaten mittels der Definition der Überschreibungsmethode 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.

      Das Überspringen der Datenprüfungen (OverrideDataImportSafetyChecks = wahr) kann hier effektiv sein, wenn Sie sicher sind, dass die Dataverse-Zielinstanz keine Daten enthält.

   7. Geben Sie benutzerdefinierten Code ein, der ausgeführt wird, nachdem der Import abgeschlossen wird, in der Überschreibungsdefinition der Methode AfterPrimaryImport>. Die restlichen Flatfiles, die vor Beginn des Lösungsimports nicht importiert wurden, werden jetzt importiert.

   8. Ä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 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";  
          }  
      }  
      

   9. Ä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.

   10. Ä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.

   11. Ä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.

3. 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 eine neue Fortschrittsanzeige in der Benutzeroberfläche (UI) zu erstellen.
   RaiseUpdateEvent(String, ProgressPanelItemStatus)	Funktion	Wird verwendet, um den Fortschritt zu aktualisieren, der beim Aufruf von CreateProgressItem(String) erstellt wurde. ProgressPanelItemStatus ist eine Enumeration mit folgenden Werte: Arbeit = 0 Abgeschlossen = 1 Fehlgeschlagen = 2 Warnung = 3 Unbekannt = 4
   RaiseFailEvent(String, Exception)	Funktion	Wird verwendet, um den aktuellen Statusimport mit einer Ausnahmefehlermeldung abzubrechen.
   IsRoleAssociatedWithTeam(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 Verwendung auf null-Werte zu prüfen, da sie möglicherweise nicht auf einen Wert gesetzt ist.
   CrmSvc	Eigenschaften	Ein Zeiger auf die Klasse CrmServiceClient, die es einem Paket ermöglicht, Dynamics 365 von innerhalb des Pakets aus zu adressieren. 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 Datenimportvorgänge überspringt, z. B. das Importieren von Dataverse-Beispieldaten, flachen Dateidaten und Daten, die aus dem Konfigurationsmigrationstool exportiert wurden. Geben Sie wahr oder falsch an. Der Standardwert ist false.
   OverrideDataImportSafetyChecks	Eigenschaften	Geben Sie an, ob Dynamics 365 Package Deployer einige seiner Sicherheitsprüfungen umgeht, was bei der Verbesserung der Importleistung hilft. 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.

4. 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.

Bauen

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

> dotnet publish

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

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

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

• <PackageName> Ordner: Der Ordnername ist derselbe, den Sie für Ihren Paketordnernamen im Schritt 2.g des Abschnitts Benutzerdefinierten Code hinzufügen geändert haben. Dieser Ordner enthält alle Lösungen, Konfigurationsdaten, Flatfiles und die Inhalte Ihres Pakets.

• <PackageName>.dll: Die Assembly enthält den benutzerdefinierten Code für Ihr Paket. Standardmäßig ist der Name des Assembly identisch mit dem Projektnamen.

Bereitstellen

Nachdem Sie ein Paket erstellt haben, können Sie es auf der Dataverse-Instanz bereitstellen, indem Sie das Tool "Package Deployer", Windows PowerShell oder einen CLI-Befehl verwenden.

• Um mit dem Package Deployer-Tool bereitzustellen, laden Sie zunächst das Tool herunter, wie in Dataverse-Entwicklungswerkzeuge beschrieben. Folgen Sie als Nächstes den detaillierten Informationen zur Paketbereitstellung im Artikel Deploy packages using Package Deployer or Windows PowerShell.

• Um ü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.

Erstellen von Paketen

Wenn Sie Pakete erstellen, müssen Entwickler:

• Sicherstellen, dass die Paketassemblies signiert sind.

Pakete bereitstellen

Wenn Pakete bereitgestellt werden, müssen Dataverse-Administratoren:

• Auf signierte Paket-Montagen bestehen, damit Sie einen Assembly zu seiner Quelle zurückverfolgen können.
• Testen Sie das Paket auf einer Vorproduktionsinstanz, vorzugsweise einem Spiegelbild der Produktionsinstanz, bevor Sie es auf einer Produktionsinstanz ausführen.
• Sichern Sie die Produktionsinstanz, bevor Sie das Paket bereitstellen.

Siehe auch

Solution Packager-Tool