Delen via

Pakketten maken voor het hulpprogramma Package Deployer

  • Artikel

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.

Notitie

Er is een ander pakkettype dat invoegtoepassingspakket wordt genoemd. Dat type pakket is voor Invoegtoepassingsafhankelijke assembly's en heeft geen relatie met Package Deployer-pakketten.

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 later, of Visual Studio Code.

Procesoverzicht

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

  • Een Visual Studio- of MSBuild-project maken
  • Oplossingen en andere bestanden toevoegen aan het project
  • Aangeleverde HTML-bestanden bijwerken (optioneel)
  • Configuratiewaarden opgeven voor het pakket
  • Aangepaste code definiëren voor het pakket
  • Het pakket bouwen en implementeren

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. Bij gebruik van Visual Studio Code installeert u Microsoft Power Platform CLI. Installeer anders, als u Visual Studio 2019 of hoger gebruikt, Power Platform Tools 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.

Voer de opdracht pac package init uit om het initiële pakket te maken. Meer informatie: pac-pakket

pac package init help
pac package init --outputDirectory DeploymentPackage

De resulterende CLI-uitvoer bevat de onderstaande mappen en bestanden. De mapnaam "DeploymentPackage" is hier als voorbeeld gebruikt.

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

Zoek in het gemaakte project het configuratiebestand 'ImportConfig.xml' in de map 'PkgAssets', en het bestand 'PackageImportExtension.cs'. U wijzigt deze bestanden zoals verderop in dit artikel wordt beschreven.

Pakketbestanden toevoegen

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

Wanneer u de CLI gebruikt, kunt u externe pakketten, oplossingen en verwijzingen toevoegen aan uw pakketproject met behulp van een van de subopdrachten add. Voer pac package help in om de lijst met subopdrachten te bekijken. Laten we een oplossing aan ons pakket gaan toevoegen.

> 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 is in geïnitialiseerd in de negeermethodedefinitie 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()  
{  
// 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");  
}

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

    5. 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 standaardbestand voor import van standaardgegevens wordt opgegeven in het knooppunt 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.

    6. Voer aangepaste code in die moet worden uitgevoerd nadat de import van de oplossing wordt afgerond 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.

    7. Wijzig de standaardnaam van uw pakketmap in de gewenste pakketnaam. Hiertoe hernoemt u de map PkgFolder (of PkgAssets) in het deelvenster Oplossingsverkenner en bewerkt u vervolgens de retourwaarde onder de eigenschap 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";  
}  
}

    8. 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 die verschijnt op de pakketselectiepagina in de wizard Dynamics 365 Package Deployer.

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

    10. 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 gemaakt door de oproep tot CreateProgressItem(String).

    ProgressPanelItemStatus is een enum met de volgende waarden:

    Werkt = 0
    Voltooid = 1
    Mislukt = 2
    Waarschuwing = 3
    Onbekend = 4
    RaiseFailEvent(String, Exception) Function Gebruikt om de huidige statusimport met een uitzonderingsbericht te laten mislukken.
    IsRoleAssoicatedWithTeam(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 aanwijzer voor de geïnitialiseerde interface voor logboekregistratie voor het pakket. Deze interface wordt gebruikt door een pakket om berichten en uitzonderingen op het pakketlogboekbestand te registreren.
    RootControlDispatcher Eigenschappen 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 dat u deze variabele voor nullwaarden controleert voordat deze kan worden gebruikt omdat deze mogelijk al op een waarde is ingesteld.
    CrmSvc Eigenschappen Een aanwijzer naar de klasse CrmServiceClient waarmee een pakket Dynamics 365 vanuit het pakket kan aanspreken. Gebruik deze aanwijzer om SDK-methoden en andere acties in de overschreven methoden uit te voeren.
    DataImportBypass Eigenschappen Geef op of Dynamics 365 Package Deployer alle bewerkingen voor gegevensimport moet overslaan, zoals de import van voorbeeldgegevens voor Dataverse, gegevens in platte bestanden en gegevens die zijn geëxporteerd vanuit het hulpprogramma voor configuratiemigratie. Stel als waarde true of false in. Standaard is false.
    OverrideDataImportSafetyChecks Eigenschappen Geef op of Dynamics 365 Package Deployer enkele veiligheidscontroles moet omzeilen. Dit kan bijdragen aan betere systeemprestaties bij de import. Geef true of false op. Standaard 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.

Om een ​​pakket te bouwen dat met de CLI is gemaakt, kunt u het .csproj-bestand in Visual Studio laden, maar in plaats daarvan gaan we de dotnet-opdracht en MSBuild gebruiken. In het onderstaande voorbeeld wordt ervan uitgegaan dat de werkdirectory het *.csproj-bestand bevat.

> dotnet publish

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

U kunt optioneel de details van het gebouwde pakket bekijken.

> 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 hebt gewijzigd voor de mapnaam van uw pakket in stap 2.g van deze sectie Aangepaste code toevoegen. Deze map bevat alle oplossingen, configuratiegegevens, platte bestanden en de inhoud voor uw pakket.

Notitie

Mogelijk ziet u een .NET-map (bijv. net472) met een map pdpublish. Uw DLL en andere projectbestanden bevinden zich in die map pdpublish.

  • <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 updatepakket hebt gemaakt, kunt u het installeren op het Dataverse-exemplaar met de Package Deployer-tool, 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 Pakketten implementeren met 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

Aanbevolen procedures

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

Pakketten implementeren

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

  • Dring aan op ondertekende pakketassemblages zodat u een assemblage terug naar de bron kunt volgen.
  • Test het pakket op een preproductie-exemplaar, bij voorkeur een spiegelbeeld van productie-exemplaar, voordat u het op een productie-exemplaar uitvoert.
  • Maak een back-up van productie-exemplaar voordat u het pakket implementeert.

Zie ook

Oplossingspakket-tool