Del via

Oprette pakker til Package Deployer-værktøjet

  • Artikel

Package Deployer gør det muligt for administratorer at installere pakker på Microsoft Dataverse-forekomster. En Package Deployer pakke kan bestå af en eller flere af følgende:

  • En eller flere Dataverse-løsningsfiler.
  • Flade filer eller eksporterede konfigurationsdatafiler fra Configuration Migration tool. Du kan finde flere oplysninger om værktøjet under Flytte konfigurationsdata på tværs af forekomster og organisationer med Configuration Migration tool.
  • Brugerdefineret kode, der kan køre, før, under eller efter at pakken er installeret på Dataverse-forekomsten.
  • HTML-indhold er specifik for pakken, der kan vises i begyndelsen og slutningen af installationsprocessen. Indholdet kan være nyttigt for at give en beskrivelse af de løsninger og filer, der installeres i pakken.

Bemærk

Der findes en anden pakketype, der kaldes en plug-in-pakke. Den type pakke gælder for plug-in-afhængige samlinger og har ingen relation til Package Deployer-pakker.

Forudsætninger

  • Sørg for, at du har alle de løsnings- og andre filer klar, som du vil medtage i pakken.
  • Visual Studio 2019 eller nyere eller Visual Studio Code.

Procesoversigt

Opret en Package Deployer-pakke ved at udføre følgende trin.

  • Oprette et Visual Studio- eller MSBuild-projekt
  • Tilføje løsninger og andre filer til projektet
  • Opdatere de medfølgende HTML-filer (valgfrit)
  • Angiv konfigurationsværdier for pakken
  • Definere brugerdefineret kode til pakken
  • Opbygning og installation af pakken

Disse trin beskrives mere detaljeret i denne artikel.

Oprette et pakkeprojekt

Det første trin er at oprette et Visual Studio- eller MSBuild-projekt for pakken. Hvis du vil gøre det, skal en af to tilgængelige værktøjsudvidelser være installeret på udviklingscomputeren. Hvis du bruger Visual Studio Code, skal du installere Microsoft Power Platform CLI. Ellers hvis du bruger Visual Studio 2019 eller senere, skal du installere Power Platform Tools til Visual Studio.

Vælg den relevante fane nedenfor for at finde ud af, hvordan du opretter et projekt ved hjælp af den ønskede værktøjsudvidelse. Begge værktøjer output projektet i et lignende format.

Kør kommandoen pac package init for at oprette den første pakke. Flere oplysninger: pac-pakke

pac package init help
pac package init --outputDirectory DeploymentPackage

Det resulterende CLI-output indeholder de mapper og filer, der vises nedenfor. Mappenavnet "DeploymentPackage" blev brugt her som et eksempel.

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

I det oprettede projekt skal du finde konfigurationsfilen ImportConfig.xml i mappen PkgAssets og filen PackageImportExtension.cs. Du vil ændre disse filer som beskrevet senere i denne artikel.

Tilføj pakkefiler

Når du har oprettet et pakkeprojekt, kan du begynde at føje løsninger og andre filer til det pågældende projekt.

Når du bruger CLI, kan du tilføje eksterne pakker, løsninger og referencer til pakkeprojektet ved hjælp af en af underkommandoer Tilføj. Angiv pac package help for at få vist listen over underkommandoer. Lad os føje en løsning til pakken.

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

Konfigurere pakken

Definer pakkekonfigurationen ved at tilføje oplysninger om din pakke i filen ImportConfig.xml, der er tilgængelig i projektet. Se ImportConfig-reference for at få et eksempel og beskrivelser af de gyldige elementer og attributter, der skal bruges.

Tilføje brugerdefineret kode

Du kan tilføje brugerdefineret kode, der køres før, under og efter at pakken er importeret i et miljø. Det gøres ved at følge denne vejledning.

  1. Rediger filen PackageTemplate.cs (eller PackageImportExtension.cs) i projektets rodmappe.

  2. I C# filen kan du:

    1. Angive brugerdefineret kode, der skal udføres, når pakken er initialiseret i tilsidesættesmetodedefinitionen af InitializeCustomExtension.

      Denne metode kan bruges til at lade brugerne bruge kørselsparametre under kørsel af en pakke. Som udvikler kan du tilføje understøttelse af alle kørselsparametre til din pakke ved at bruge egenskaben RuntimeSettings, så længe du har koden til at behandle den egenskab, der er baseret på brugerinputtet.

      Følgende eksempelkode giver f.eks mulighed for en kørselsparameter, der kaldes SkipChecks for pakken, der har to mulige værdier: true eller false. Eksempelkoden kontrollerer, om brugeren har angivet kørselsparametre under kørsel af Package Deployer (enten ved hjælp af kommandolinjen eller PowerShell), og behandler oplysninger ud fra dette. Hvis brugeren ikke har angivet nogen kørselsparametre under kørsel af pakken, bliver værdien af egenskaben RuntimeSettings 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");  
}

      Denne kode giver administratoren mulighed for at bruge kommandolinjen eller Import-CrmPackage-cmdlet til at angive, om sikkerhedskontrollerne skal springes over under kørsel af Package Deployer-værktøjet for at importere pakken. Flere oplysninger: Installere pakker ved hjælp af Package Deployer og Windows PowerShell

    2. Angiv brugerdefineret kode, der skal afvikes, før løsningerne importeres definitionen af tilsidesættelsesmetoden PreSolutionImport for at angive, om tilpasningerne skal bevares eller tilsidesættes under opdatering af den angivne løsning i en Dataverse-destinationsforekomst, og om plugins og arbejdsprocesser skal aktiveres automatisk.

    3. Brug definitionen af tilsidesættelsesmetoden for RunSolutionUpgradeMigrationStep til at udføre datatransformation eller -opgradering mellem to versioner af en løsning. Denne metode kaldes kun, hvis den løsning, du importerer, allerede findes i Dataverse-destinationsforekomsten.

      Denne funktion forventer følgende parametre:

      Parameter Beskrivelse
      solutionName Navnet på løsningen
      oldVersion Versionsnummer for den gamle løsning
      newVersion Versionsnummer for den nye løsning
      oldSolutionId GUID til den gamle løsning
      newSolutionId GUID til den nye løsning.

    4. Angiv brugerdefineret kode, der skal udføres, før importen af løsningen fuldføres i tilsidesættelsesdefinitionen for BeforeImportStage-metoden. Eksempeldataene og nogle flade filer til løsninger, der er angivet i ImportConfig.xml-filen, importeres, før importen af løsningen er fuldført.

    5. Tilsidesæt det sprog, der er valgt i øjeblikket til konfiguration af dataimport, ved hjælp af definitionen af tilsidesættelsesmetoden OverrideConfigurationDataFileLanguage. Hvis den angivne landestandard-ID (LCID) for det angivne sprog ikke findes på listen over tilgængelige sprog i pakken, importeres standarddatafilen.

      Du angiver de tilgængelige sprog for konfigurationsdataene i <cmtdatafiles>-noden i ImportConfig.xml-filen. Standardimportfilen for konfigurationsdata er angivet i crmmigdataimportfile-attributten i ImportConfig.xml-filen.

      Det kan være effektivt at springe datakontroller over her (OverrideDataImportSafetyChecks = sand), hvis du er sikker på, at Dataverse-destinationsforekomsten ikke indeholder data.

    6. Angiv brugerdefineret kode, der skal udføres, efter importen af løsningen er fuldført i tilsidesættelsesdefinitionen for metoden AfterPrimaryImport>. De resterende flade filer, der ikke er blevet importeret tidligere, før løsning af importen gik i gang, importeres nu.

    7. Skift standardnavnet på din pakkemappe til det ønskede pakkenavn. Det gør du ved at omdøbe PkgFolder (eller PkgAssets)-mappen i ruden Løsningsoversigt og derefter redigere returværdien under egenskaben 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. Ændre navnet på pakken ved at redigere returneringsværdien under egenskaben GetNameOfImport.

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

      Denne returnerede værdi er navnet på den pakke, der vises på siden til valg af pakken i guiden Dynamics 365 Package Deployer.

    9. Ændre pakkebeskrivelsen ved at redigere returneringsværdien under egenskaben GetImportPackageDescriptionText.

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

      Denne returnerede værdi er den pakkebeskrivelse, der vises ved siden af navnet på pakken på siden til valg af pakken i guiden Package Deployer.

    10. Ændre pakkens lange navn ved at redigere returneringsværdien under egenskaben GetLongNameOfImport.

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

      Pakkens lange navn vises på næste side, når du har valgt at installere pakken.

  3. Desuden er følgende funktion og variabler tilgængelige til pakken:

    Navn Skriv Beskrivelse
    CreateProgressItem(String) Funktion Bruges til at oprette et nyt statuselement i brugergrænsefladen.
    RaiseUpdateEvent(String, ProgressPanelItemStatus) Funktion Bruges til at opdatere de fremskridt, der er oprettet ved et opkald til CreateProgressItem(String).

    ProgressPanelItemStatus er en fasttekstværdi med følgende værdier:

    Arbejder = 0
    Fuldført = 1
    Mislykkedes = 2
    Advarsel = 3
    Ukendt = 4
    RaiseFailEvent(String, Exception) Function Bruges til at mislykkes den aktuelle status for import med en undtagelsesmeddelelse.
    IsRoleAssoicatedWithTeam(Guid, Guid) Funktion Bruges til at afgøre, om en rolle er knyttet til et bestemt team.
    IsWorkflowActive(Guid) Funktion Bruges til at bestemme, om en bestemt arbejdsproces er aktiv.
    PackageLog Klassemarkør En markør til den initialiserede grænseflade til logføring for pakken. Denne grænseflade udnyttes af en pakke til at logge meddelelser og undtagelser til pakkelogfilen.
    RootControlDispatcher Egenskab En ekspeditørgrænseflade, der anvendes til at give dit kontrolelement mulighed for at gengive sin egen brugergrænseflade under installation af pakken. Brug denne grænseflade til at ombryde alle elementer i brugergrænsefladen eller kommandoer. Det er vigtigt at kontrollere denne variabel til null-værdier, før du bruger den, da den muligvis kan eller ikke kan angives til en værdi.
    CrmSvc Egenskab En henvisning til CrmServiceClient-klasen, der giver en pakke mulighed for at henvende sig til Dynamics 365 fra pakken. Brug denne markør til at udføre SDK-metoder og andre handlinger i de metoder, der tilsidesættes.
    DataImportBypass Egenskab Angiv, om Dynamics 365 Package Deployer springer alle dataimporthandlinger over som f.eks. import af Dataverse-eksempeldata og flad fil-data, der er eksporteret fra Configuration Migration tool. Angiv sand eller falsk. Standard er false.
    OverrideDataImportSafetyChecks Egenskab Angiv, om Dynamics 365 Package Deployer tilsidesætter nogle af dets sikkerhedskontroller, der gør det muligt at forbedre importens ydeevne. Angiv true eller false. Standard er false.

    Du skal kun angive denne egenskab til true, hvis Dataverse-destinationsforekomsten ikke indeholder data.

  4. Gem dit projekt. Det næste trin er at opbygge pakken.

Opbyg, og installer

De følgende afsnit beskriver, hvordan man opbygger og implementerer en pakke.

Byg

Opbygning af din pakke er beskrevet nedenfor afhængigt af hvilket værktøj du bruger.

For at bygge en pakke, der er oprettet med CLI, kan du indlæse .csproj-filen i Visual Studio, men i stedet skal vi bruge dotnet-kommandoen og MSBuild. I eksemplet nedenfor antages det, at arbejdsmappen indeholder filen *.csproj.

> dotnet publish

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

Du kan også se detaljerne i den indbyggede pakke.

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

Pakken indeholder følgende filer under mappen <Projekt>\Bin\Debug.

  • <PackageName>-mappe: Mappenavnet er det samme som det, du ændrede for dit pakkemappenavn i trin 2.g i dette afsnit Tilføj brugerdefineret kode. Denne mappe indeholder alle løsninger, konfigurationsdata, flade filer og indholdet for din pakke.

Bemærk

Du kan muligvis se en .NET-mappe (f.eks. net472), der indeholder en pdpublish-mappe. Dine DLL- og andre projektfiler findes i pdpublish-mappen.

  • <PackageName>.dll: Assemblyet indeholder den brugerdefinerede kode til pakken. Som standard er navnet på den assembly det samme som dit projektnavn.

Installer

Når du har oprettet en pakke, kan du installere den på Dataverse-forekomsten, enten ved hjælp af Package Deployer-værktøjet eller Windows PowerShell eller en CLI-kommando.

Bedste praksis

Nedenfor er der et par tip til bedste praksis, du kan følge, når du arbejder med Package Deployer-pakker.

Oprette pakker

Når udviklere opretter pakker, skal de:

  • Kontrollér, at pakke-assembly er signeret.

Installere pakker

Ved installation af pakker skal Dataverse-administratorer:

  • Insistere på en signeret pakkeassembly, så du kan spore en assembly tilbage til kilden.
  • Teste pakken på en forproduktionsforekomst, helst et spejlbillede af produktionsforekomsten, før du kører den på en produktionsforekomst.
  • Sikkerhedskopiere produktionsforekomsten, før pakken installeres.

Se også

Løsningspakkeværktøj