Pakketten maken voor het hulpprogramma Package Deployer

Met Package Deployer kunnen beheerders pakketten implementeren op Microsoft Dataverse exemplaren. Een Package Deployer-pakket kan bestaan uit enkele of alle van de volgende onderdelen:

• Een of meer Dataverse-oplossingsbestanden.
• Platte bestanden of geëxporteerde configuratiegegevensbestanden uit het hulpprogramma voor configuratiemigratie. Zie Configuratiegegevens verplaatsen tussen exemplaren en organisaties met het hulpprogramma voor configuratiemigratie voor meer informatie over dit hulpprogramma.
• Aangepaste code die kan worden uitgevoerd voor, tijdens of na de implementatie voor het Dataverse-exemplaar.
• HTML-inhoud specifiek voor het pakket die aan het begin en het einde van het installatieproces kan worden weergeven. Deze inhoud kan handig zijn als u een beschrijving wilt geven van de oplossingen en bestanden die in het pakket worden geïnstalleerd.

Vereisten

• Zorg ervoor dat u alle oplossings- en andere bestanden bij de hand hebt die u in het pakket wilt opnemen.
• Visual Studio 2019 of hoger of Visual Studio Code.

Procesoverzicht

Voer de volgende stappen uit om een Package Deployer-pakket te maken.

Deze stappen worden in dit artikel in detail beschreven.

Een pakketproject maken

De eerste stap is het maken van een Visual Studio- of MSBuild-project voor het pakket. Hiertoe moet u een van de twee beschikbare toolextensies op uw ontwikkelcomputer hebben geïnstalleerd. Als u Visual Studio Code gebruikt, installeert u Microsoft Power Platform CLI. Als u Visual Studio 2019 of hoger gebruikt, installeert u Power Platform-hulpprogramma's voor Visual Studio.

Selecteer het juiste tabblad hieronder om erachter te komen hoe u een project kunt maken met de gewenste toolextensie. Beide tools voeren het project in een vergelijkbare indeling uit.

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

Pakketbestanden toevoegen

Nadat u een pakketproject hebt gemaakt, kunt u beginnen met het toevoegen van oplossingen en andere bestanden aan dat project.

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

Het pakket configureren

Definieer de pakketconfiguratie door informatie over uw pakket toe te voegen in het bestand ImportConfig.xml in het project. Raadpleeg ImportConfig-referentie voor een voorbeeld en beschrijvingen van de geldige elementen en kenmerken die u kunt gebruiken.

Aangepaste code toevoegen

U kunt aangepaste code toevoegen die wordt uitgevoerd voor, tijdens en nadat het pakket in een omgeving is geïmporteerd. Hiertoe volgt u deze instructies.

1. Bewerk het bestand PackageTemplate.cs (of PackageImportExtension.cs) in de hoofdmap van het project.

2. In het C#-bestand kunt u:

   1. Aangepaste code invoeren om uit te voeren wanneer het pakket geïnitialiseerd is in de override-methode definitie van InitializeCustomExtension.

      Met deze methode kunnen gebruikers de runtime-parameters gebruiken terwijl zij een pakket uitvoeren. Als ontwikkelaar kunt u ondersteuning voor alle runtime-parameters aan uw pakket toevoegen door de eigenschap RuntimeSettings te gebruiken, als u code hebt om het te verwerken op basis van de gebruikerinvoer.

      In de volgende voorbeeldcode wordt bijvoorbeeld een runtime-parameter met de naam SkipChecks ingeschakeld voor het pakket, die twee mogelijke waarden heeft: true of false. De voorbeeldcode controleert of de gebruiker runtime-parameters heeft opgegeven bij het uitvoeren van Package Deployer (vanaf de opdrachtregel of vanuit de PowerShell) en verwerkt vervolgens de gegevens. Als geen runtime-parameter door de gebruiker is opgegeven tijdens het uitvoeren van het pakket, wordt de waarde van de eigenschap RuntimeSettings ingesteld op 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");
        }  
      } 
      

      Deze code stelt de beheerder in staat de opdrachtregel of de cmdlet Import-CrmPackage te gebruiken om op te geven of de veiligheidscontroles moeten worden overgeslagen tijdens het uitvoeren van het hulpprogramma Package Deployer om het pakket te importeren. Meer informatie: Pakketten implementeren met behulp van Package Deployer en Windows PowerShell

   2. Voer aangepaste code in die moet worden uitgevoerd voordat de oplossingen worden geïmporteerd in de methodeoverschrijvingsdefinitie van PreSolutionImport, om op te geven of u aanpassingen wilt behouden of wilt overschrijven, terwijl de opgegeven oplossing wordt bijgewerkt in een doelexemplaar van Dataverse, en of u invoegtoepassingen en workflows automatisch wilt laten activeren.

   3. Gebruik de overschrijvingsmethodedefinitie van RunSolutionUpgradeMigrationStep om een gegevenstransformatie of upgrade tussen twee versies van een oplossing uit te voeren. Deze methode wordt alleen aangeroepen als de oplossing die u importeert al aanwezig is in het doelexemplaar van Dataverse.

      Deze functie verwacht de volgende parameters:

      Parameter	Beschrijving
      solutionName	Naam van de oplossing
      oldVersion	Versienummer van de oude oplossing
      newVersion	Versienummer van de nieuwe oplossing
      oldSolutionId	GUID van de oude oplossing.
      newSolutionId	GUID van de nieuwe oplossing.

   4. Overschrijf de methode OverrideSolutionImportDecision om een UserRequestedImportAction-opsomming te retourneren die bepaalt of het importeren van een oplossing wordt overgeslagen, bijgewerkt of geüpgraded (de standaardinstelling).

      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. Voer aangepaste code in die moet worden uitgevoerd voordat de import van de oplossing wordt afgerond in de overschrijvingsdefinitie van de methode BeforeImportStage. De voorbeeldgegevens en sommige platte bestanden voor oplossingen die zijn opgegeven in het bestand ImportConfig.xml worden geïmporteerd voordat de import van de oplossing is voltooid.

   6. Overschrijf de momenteel geselecteerde taal voor de import van configuratiegegevens door middel van de methodeoverschrijvingsdefinitie van OverrideConfigurationDataFileLanguage. Als de opgegeven landinstellingen-ID (LCID) van de opgegeven taal niet in de lijst met beschikbare talen in het pakket wordt gevonden, wordt het standaardgegevensbestand geïmporteerd.

      U kunt de beschikbare talen voor de configuratiegegevens opgeven in het knooppunt <cmtdatafiles> in het bestand ImportConfig.xml. Het standaardconfiguratie importbestand wordt opgegeven in het attribuut crmmigdataimportfile in het bestand ImportConfig.xml.

      Het overslaan van gegevenscontroles (OverrideDataImportSafetyChecks = true) kan hier nuttig zijn als u zeker weet dat het doelexemplaar van Dataverse geen gegevens bevat.

   7. Voer aangepaste code uit na voltooiing van de import in de overschrijvingsdefinitie van de methode AfterPrimaryImport>. De resterende platte bestanden die niet eerder werden geïmporteerd, voordat de import van de oplossing begon, worden nu geïmporteerd.

   8. Wijzig de standaardnaam van uw pakketmap in de gewenste pakketnaam. Hiervoor wijzigt u de naam van de map PkgFolder (of PkgAssets) in het deelvenster Solution Explorer en bewerkt u de retourwaarde onder de eigenschap 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. Wijzig de pakketnaam door de retourwaarde onder de GetNameOfImport eigenschap te bewerken.

      public override string GetNameOfImport(bool plural)  
      {  
          return "Package Short Name";  
      }  
      

      Deze geretourneerde waarde is de naam van uw pakket dat wordt weergegeven op de pagina 'Pakketselectie' in de Wizard van Dynamics 365 Package Deployer.

   10. Wijzig de pakketbeschrijving door de retourwaarde onder de GetImportPackageDescriptionText eigenschap te bewerken.

       public override string GetImportPackageDescriptionText  
       {  
           get { return "Package Description"; }  
       }  
       

       Deze geretourneerde waarde is de pakketbeschrijving die naast de pakketnaam wordt weergegeven op de pakketselectiepagina in de wizard Package Deployer.

   11. Wijzig de lange pakketnaam door de retourwaarde onder de GetLongNameOfImport eigenschap te bewerken.

       public override string GetLongNameOfImport  
       {  
           get { return "Package Long Name"; }  
       }  
       

       De lange pakketnaam wordt weergegeven op de volgende pagina nadat u het pakket om te installeren hebt geselecteerd.

3. Bovendien zijn de volgende functies en de variabelen voor het pakket beschikbaar:

   Naam	Type	Beschrijving
   CreateProgressItem(String)	Functie	Gebruikt om een nieuw voortgangitem in de gebruikersinterface (UI) te maken.
   RaiseUpdateEvent(String, ProgressPanelItemStatus)	Functie	Gebruikt om de voortgang bij te werken die is gegenereerd door de aanroep naar CreateProgressItem(String). ProgressPanelItemStatus is een enum met de volgende waarden: Werkt = 0 Voltooid = 1 Mislukt = 2 Waarschuwing = 3 Onbekend = 4
   RaiseFailEvent(String, Exception)	Functie	Gebruikt om de huidige statusimport met een uitzonderingsbericht te laten mislukken.
   IsRoleAssociatedWithTeam(Guid, Guid)	Functie	Gebruikt om te bepalen of een rol met een bepaald team is gekoppeld.
   IsWorkflowActive(Guid)	Functie	Gebruikt om te bepalen of een bepaalde werkstroom actief is.
   PackageLog	Klassenaanwijzer	Een pointer naar de geïnitialiseerde loginterface van het pakket. Deze interface wordt gebruikt door een pakket om berichten en uitzonderingen op het pakketlogboekbestand te registreren.
   RootControlDispatcher	Eigenschap	Een dispatcherinterface die wordt gebruikt om het besturingselement toe te staan om zijn eigen UI weer te geven tijdens de pakketinstallatie. Gebruik deze interface om eventuele UI-elementen of opdrachten te verpakken. Het is belangrijk om deze variabele te controleren op nullwaarden voordat u deze gebruikt, omdat deze mogelijk nog niet op een waarde is ingesteld.
   CrmSvc	Eigenschap	Een aanwijzer naar CrmServiceClient-klasse waarmee een pakket Dynamics 365 vanuit het pakket kan adresseren. Gebruik deze aanwijzer om SDK-methoden en andere acties in de overschreven methoden uit te voeren.
   DataImportBypass	Eigenschap	Geef op of Dynamics 365 Package Deployer alle bewerkingen voor het importeren van gegevens overslaat, zoals het importeren van Gegevensverse-voorbeeldgegevens, platte bestandsgegevens en gegevens die zijn geëxporteerd vanuit het hulpprogramma Configuratiemigratie. Stel als waarde true of false in. De standaardinstelling is false.
   OverrideDataImportSafetyChecks	Eigenschap	Geef op of Dynamics 365 Package Deployer enkele van de veiligheidscontroles omzeilt, wat helpt bij het verbeteren van de importprestaties. Opgeven true of false. De standaardinstelling is false. U moet deze eigenschap alleen instellen op true, als het doelexemplaar van Dataverse geen gegevens bevat.

4. Sla uw project op. De volgende stap is het bouwen van het pakket.

Bouwen en implementeren

In de volgende secties wordt beschreven hoe u een pakket bouwt en implementeert.

Build

Het samenstellen van uw pakket wordt hieronder beschreven, afhankelijk van de tool die u gebruikt.

> 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

Uw pakket bestaat uit de volgende bestanden onder de map <Project>\Bin\Debug.

• <Pakketnaam> map : De mapnaam is dezelfde als die u in stap 2.g van deze sectie voor de mapnaam van uw pakket hebt gewijzigd Aangepaste code toevoegen. Deze map bevat alle oplossingen, configuratiegegevens, platte bestanden en de inhoud voor uw pakket.

• <Pakketnaam> .dll :De assembly bevat de aangepaste code voor uw pakket. Standaard is de naam van de assembly hetzelfde als de projectnaam.

Implementeren

Nadat u een pakket hebt gemaakt, kunt u het implementeren op het Dataverse-exemplaar met behulp van het hulpprogramma Package Deployer, Windows PowerShell of een CLI-opdracht.

• Als u wilt implementeren met behulp van de Package Deployer-tool, downloadt eerst de tool zoals beschreven in Dataverse-ontwikkelingshulpmiddelen. Volg vervolgens de gedetailleerde informatie over pakketimplementatie in het artikel Deploy-pakketten met behulp van Package Deployer of Windows PowerShell.

• Gebruik de opdracht pac package deploy als u wilt implementeren met behulp van de CLI.

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

  Notitie

  Als u een pakket wilt implementeren in een doelomgeving met behulp van de CLI, moet u eerst een verificatieprofiel instellen en een organisatie selecteren. Meer informatie: pac auth create, pac org select

Beste praktijken

Hieronder vindt u enkele praktische tips die u kunt volgen bij het werken met Package Deployer-pakketten.

Pakketten maken

Bij het maken van pakketten moeten ontwikkelaars:

• Zorg ervoor dat pakketassemblages zijn ondertekend.

Pakketten implementeren

Bij het implementeren van pakketten moeten Dataverse-beheerders het volgende doen:

• Sta erop dat de pakketten gesigneerd worden samengesteld zodat u een assemblage terug naar de bron kunt volgen.
• Test het pakket op een preproductie-exemplaar, bij voorkeur een spiegelbeeld van het productie-exemplaar, voordat u het op een productie-exemplaar uitvoert.
• Maak een back-up van het productie-exemplaar voordat u het pakket implementeert.

Zie ook

Hulpprogramma Oplossingsverpakker