Oprette pakker til Package Deployer-værktøjet
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.
Rediger filen PackageTemplate.cs (eller PackageImportExtension.cs) i projektets rodmappe.
I C# filen kan du:
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
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.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. 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 iImportConfig.xml
-filen, importeres, før importen af løsningen er fuldført.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 iImportConfig.xml
-filen. Standardimportfilen for konfigurationsdata er angivet icrmmigdataimportfile
-attributten iImportConfig.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.
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.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 egenskabenGetImportPackageDataFolderName
.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"; } }
Æ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.
Æ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.
Æ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.
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 = 4RaiseFailEvent(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
ellerfalse
. Standard erfalse
.
Du skal kun angive denne egenskab tiltrue
, hvis Dataverse-destinationsforekomsten ikke indeholder data.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.
Hvis du vil installere ved hjælp af Package Deployer-værktøjet, skal du først hente værktøjet som beskrevet i Dataverse-udviklingsværktøjerne. Følg derefter de detaljerede oplysninger om pakkeimplementering i artiklen Implementer pakker ved hjælp af Package Deployer eller Windows PowerShell.
Anvend CLI ved hjælp af
pac package deploy
-kommando.> pac package deploy --package .\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip
Bemærk
Hvis du vil installere en pakke i et destinationsmiljø ved hjælp af CLI, skal du først konfigurere en godkendelsesprofil og vælge en organisation. Flere oplysninger: pac auth create, pac org select
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.