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.

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

Hvis du vil oprette en Package Deployer-pakke, skal du udføre følgende trin:

I denne artikel beskrives disse trin i detaljer.

Oprette et pakkeprojekt

Først skal du oprette et Visual Studio eller MSBuild-projekt for pakken. Hvis du vil oprette projektet, skal du installere en af to tilgængelige værktøjsudvidelser på din udviklingscomputer. Hvis du bruger Visual Studio Code, skal du installere Microsoft Power Platform CLI. Hvis du bruger Visual Studio 2019 eller nyere, skal du installere Power Platform-værktøjer til Visual Studio.

Hvis du vil vide mere om, hvordan du opretter et projekt ved hjælp af den ønskede værktøjsudvidelse, skal du vælge den relevante fane i følgende afsnit. Begge værktøjer output projektet i et lignende format.

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

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.

> 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. Du kan finde et eksempel på og beskrivelser af de gyldige elementer og attributter, der skal bruges, under ImportConfig Reference.

Tilføje brugerdefineret kode

Du kan tilføje brugerdefineret kode, der kører før, under og efter, at pakken importeres i et miljø. Hvis du vil tilføje brugerdefineret kode, skal du følge disse instruktioner:

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

2. I C# filen kan du:

   1. Angiv den brugerdefinerede kode, der skal køres, når pakken initialiseres, i override-metodens definition for InitializeCustomExtension.

      Brug denne metode til at lade brugerne bruge kørselsparametrene 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 angiver kørselsparametre under kørsel af Package Deployer (enten ved hjælp af kommandolinjen eller PowerShell), og behandler derefter oplysningerne i overensstemmelse hermed. Hvis brugeren ikke angiver en kørselsparameter under kørsel af pakken, er værdien af RuntimeSettings egenskaben 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");
        }  
      } 
      

      Denne kode gør det muligt for administratoren at bruge kommandolinjen eller Import-CrmPackage-cmdlet'en til at angive, om sikkerhedskontrollen skal springes over, mens package Deployer-værktøjet køres for at importere pakken. Du kan få flere oplysninger under Installér og udrul pakker ved hjælp af Package Deployer og Windows PowerShell.

   2. Angiv den brugerdefinerede kode, der skal køres, før løsningerne importeres, i definitionen af tilsidesættelsesmetoden for PreSolutionImport. Brug denne metode til at angive, om tilpasninger skal vedligeholdes eller overskrives under opdatering af den angivne løsning i en mål-Dataverse-forekomst, og om plug-ins og arbejdsprocesser automatisk skal aktiveres.

   3. Brug definitionen af metoden Override for RunSolutionUpgradeMigrationStep til at udføre datatransformation eller opgradere en løsning mellem to versioner. Denne metode kører kun, hvis den løsning, du importerer, allerede findes i destinationsforekomsten af Dataverse.

      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'en til den nye løsning.

   4. Tilsidesæt metoden OverrideSolutionImportDecision til at returnere en UserRequestedImportAction-enum, der styrer, om importen af en løsning springes over, opdateres eller opgraderes (standarden).

      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. Angiv den brugerdefinerede kode, der skal køres, før løsningsimporten fuldføres i tilsidesættelsesdefinitionen BeforeImportStage for metoden. Værktøjet importerer eksempeldataene og nogle flade filer til løsninger, der er angivet i ImportConfig.xml filen, før løsningsimporten fuldføres.

   6. Tilsidesæt det sprog, der er valgt i øjeblikket, ved import af konfigurationsdata ved hjælp af definitionen af tilsidesættelsesmetoden for OverrideConfigurationDataFileLanguage. Hvis det angivne landestandard-id/locale-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. Du angiver importfilen for standardkonfigurationsdata i attributten crmmigdataimportfileImportConfig.xml i filen.

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

   7. Angiv den brugerdefinerede kode, der skal køres, når importen er fuldført, i override-definitionen for metoden AfterPrimaryImport. Værktøjet importerer de resterende flade filer, som ikke blev importeret tidligere, inden løsningsimporten startede.

   8. Skift standardnavnet på din pakkemappe til det ønskede pakkenavn. Det gør du ved at omdøbe PkgFolder mappen eller PkgAssets i ruden Løsningsoversigt og derefter redigere returværdien under GetImportPackageDataFolderName egenskaben .

      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. Æ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å pakken, der vises på siden til valg af pakke i guiden Dynamics 365 Package Deployer.

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

   11. Æ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 den pakke, der skal installeres.

3. Pakken har også adgang til følgende funktioner og variabler:

   Name	Type	Beskrivelse
   CreateProgressItem(String)	Funktion	Opretter et nyt fremdriftselement i brugergrænsefladen.
   RaiseUpdateEvent(String, ProgressPanelItemStatus)	Funktion	Opdaterer den fremgang, der er oprettet af opkaldet til CreateProgressItem(String). ProgressPanelItemStatus er en opregning med følgende værdier: Arbejder = 0 Fuldført = 1 Mislykkedes = 2 Advarsel = 3 Ukendt = 4
   RaiseFailEvent(String, Exception)	Funktion	Får den aktuelle statusimport til at mislykkes med en undtagelsesmeddelelse.
   IsRoleAssociatedWithTeam(Guid, Guid)	Funktion	Bestemmer, om en rolle er knyttet til et angivet team.
   IsWorkflowActive(Guid)	Funktion	Bestemmer, om en angivet arbejdsproces er aktiv.
   PackageLog	Klassemarkør	En markør til den initialiserede grænseflade til logføring for pakken. Pakken bruger denne grænseflade til at logføre meddelelser og undtagelser til pakkelogfilen.
   RootControlDispatcher	Egenskab	En dispatchergrænseflade, som din kontrol bruger til at gengive sin egen brugergrænseflade under udrulning af pakken. Brug denne grænseflade til at ombryde alle elementer i brugergrænsefladen eller kommandoer. Kontrollér denne variabel for null-værdier, før du bruger den, da den muligvis ikke er angivet til en værdi.
   CrmSvc	Egenskab	En pointer til CrmServiceClient klasse, der gør det muligt for en pakke at få adgang 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, f.eks. import af Dataverse-eksempeldata, flade fildata og data, der eksporteres fra værktøjet til konfigurationsoverførsel. Angiv true eller false. Standard er false.
   OverrideDataImportSafetyChecks	Egenskab	Angiv, om Dynamics 365 Package Deployer tilsidesætter nogle af sine sikkerhedstjek, hvilket hjælper med at forbedre importydeevnen. Angiv true eller false. Standard er false. Angiv kun denne egenskab til true , hvis destinationsforekomsten af Dataverse ikke indeholder nogen 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.

Generer

I følgende afsnit beskrives det, hvordan du opretter din pakke, afhængigt af hvilket værktøj du bruger.

> 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

Pakken består af følgende filer under mappen *<Project>*\Bin\Debug :

• <PackageName> mappe: Mappenavnet svarer til det navn, du har valgt til pakkemappen i trin 2.g i afsnittet Tilføj brugerdefineret kode . Denne mappe indeholder alle løsninger, konfigurationsdata, flade filer og indholdet for din pakke.

• <PackageName>.dll: assemblyen indeholder den brugerdefinerede kode for din pakke. Navnet på assemblyen svarer som standard til dit projektnavn.

Rul ud

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

• Hvis du vil udrulle ved hjælp af Package Deployer-værktøjet, skal du først downloade værktøjet som beskrevet i Dataverse-udviklingsværktøjer. Følg derefter de detaljerede oplysninger om pakkeinstallation i artiklen Deploy-pakker ved hjælp af Package Deployer eller Windows PowerShell.

• Hvis du vil udrulle ved hjælp af CLI, skal du bruge pac package deploy-kommandoen.

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

  Bemærkning

  Hvis du vil udrulle en pakke til et destinationsmiljø ved hjælp af kommandolinjegrænsefladen, skal du først konfigurere en godkendelsesprofil og vælge en organisation. Du kan få flere oplysninger i pac auth create and 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:

• Sørg for, at pakkesamlinger er underskrevet.

Installere pakker

Ved installation af pakker skal Dataverse-administratorer:

• Insister på signerede pakkesamlinger , så du kan spore en samling tilbage til kilden.
• Test pakken på en præproduktionsforekomst, helst et spejlbillede af produktionsforekomsten, før den køres på en produktionsforekomst.
• Sikkerhedskopier produktionsforekomsten , før du installerer pakken.

Se også

Løsningspakkeværktøj