Opprette pakker for Package Deployer-verktøyet

Pakkedistribusjon lar administratorer distribuere pakker på Microsoft Dataverse forekomster. En Package Deployer-pakke kan bestå av enhver eller alle av følgende:

• Én eller flere løsningsfiler for Dataverse.
• Flate filer eller eksporterte konfigurasjonsdatafiler fra verktøyet for konfigurasjonsoverføring. For mer informasjon om verktøyet, se Flytte konfigurasjonsdata på tvers av forekomster og organisasjoner med Configuration Migration Tool.
• Egendefinert kode som kan kjøre før, samtidig eller etter at pakken distribueres til Dataverse-forekomsten.
• HTML-innhold som er spesifikk for pakken som kan vises i begynnelsen og mot slutten av distribusjonsprosessen. Dette innholdet kan være nyttig for å gi en beskrivelse av løsninger og filer som distribueres i pakken.

Forutsetninger

• Kontroller at du har alle løsningene og alle de andre filene klare som du vil ha med i pakken.
• Visual Studio 2019 eller nyere, eller Visual Studio Code.

Prosessoversikt

Hvis du vil opprette en Package Deployer-pakke, gjør du følgende:

Denne artikkelen beskriver disse trinnene i detalj.

Opprett et pakkeprosjekt

Først må du opprette et Visual Studio- eller MSBuild-prosjekt for pakken. Hvis du vil opprette prosjektet, installerer du én av to tilgjengelige verktøyutvidelser på utviklingsdatamaskinen. Hvis du bruker Visual Studio Code, må du installere Microsoft Power Platform CLI. Hvis du bruker Visual Studio 2019 eller nyere, installer Power Platform-verktøy for Visual Studio.

Hvis du vil lære hvordan du oppretter et prosjekt ved hjelp av ønsket verktøyutvidelse, velger du den aktuelle fanen i delen nedenfor. Begge verktøyene gir prosjektet 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

Legg til pakkefiler

Når du har opprettet et pakkeprosjekt, kan du begynne å legge til løsningsfiler og andre filer i prosjektet.

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

Konfigurer pakken

Definer pakkekonfigurasjonen ved å legge til informasjon om pakken i filen ImportConfig.xml i prosjektet. Hvis du vil ha et eksempel og beskrivelser av de gyldige elementene og attributtene som skal brukes, kan du se ImportConfig Reference.

Legg til egendefinert kode

Du kan legge til egendefinert kode som kjøres før, under og etter import av en pakke til et miljø. Følg disse instruksjonene for å legge til egendefinert kode:

1. Rediger filen PackageTemplate.cs eller PackageImportExtension.cs i rotmappen for prosjektet.

2. I C#-filen kan du gjøre følgende:

   1. Skriv inn egendefinert kode som skal kjøres når pakken initialiseres, i definisjonen av overstyringsmetoden for InitializeCustomExtension.

      Bruk denne metoden til å gjøre det mulig for brukere å bruke kjøretidsparametere når de kjører en pakke. Som utvikler kan du legge til støtte for alle kjøretidsparametere i pakken ved å bruke RuntimeSettings-egenskapen så lenge du har kode som behandler den basert på brukerinndataene.

      Eksempelkoden nedenfor aktiverer for eksempel en kjøretidsparameter kalt SkipChecks for pakken som har to mulige verdier: true eller false. Eksempelkoden kontrollerer om brukeren angir kjøretidsparametere under kjøring av Package Deployer (enten ved hjelp av kommandolinjen eller PowerShell), og behandler deretter informasjonen tilsvarende. Hvis brukeren ikke angir en kjøretidsparameter under kjøring av pakken, er verdien for RuntimeSettings egenskapen 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 koden gjør det mulig for administratoren å bruke kommandolinjen eller Import-CrmPackage-cmdleten til å angi om sikkerhetskontrollene skal hoppes over mens pakkedistribusjonsverktøyet kjører for å importere pakken. Hvis du vil ha mer informasjon, kan du se Distribuere pakker ved hjelp av Package Deployer og Windows PowerShell.

   2. Skriv inn egendefinert kode som skal kjøres før løsningene importeres i definisjonen av overstyringsmetoden for PreSolutionImport. Bruk denne metoden til å angi om du vil beholde eller overskrive tilpassinger mens du oppdaterer den angitte løsningen i en mål-Dataverse-forekomst, og om du vil aktivere plugin-moduler og arbeidsflyter automatisk.

   3. Bruk overstyringsmetodedefinisjonen til RunSolutionUpgradeMigrationStep for å utføre datatransformasjon eller oppgradering mellom to versjoner av en løsning. Denne metoden kjører bare hvis løsningen du importerer, allerede finnes i Dataverse-forekomsten for målet.

      Denne funksjonen forventer følgende parametere:

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

   4. Overstyr metoden OverrideSolutionImportDecision for å returnere en UserRequestedImportAction-enum som styrer om import av en løsning hoppes over, oppdateres eller oppgraderes (standardinnstillingen).

      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. Angi egendefinert kode som skal kjøres før løsningsimporten fullføres i overstyringsdefinisjonen for BeforeImportStage metoden. Verktøyet importerer eksempeldataene og noen flate filer for løsninger som er angitt i ImportConfig.xml filen før løsningsimporten fullføres.

   6. Overstyr språket som er valgt for øyeblikket for import av konfigurasjonsdata ved å bruke overstyringsmetodedefinisjonen til OverrideConfigurationDataFileLanguage. Hvis angitt nasjonal innstillings-ID (LCID) for det angitte språket ikke finnes i listen over tilgjengelige språk i pakken, importeres standarddatafilen.

      Du angir tilgjengelige språk for konfigurasjonsdataene i <cmtdatafiles>-noden i ImportConfig.xml-filen. Du angir standard importfil for konfigurasjonsdata i crmmigdataimportfile-attributtet i filen ImportConfig.xml.

      Det kan være effektiv å hoppe over datakontroller (OverrideDataImportSafetyChecks = true) her hvis du er sikker på at Dataverse-målforekomsten ikke inneholder data.

   7. Angi egendefinert kode som skal kjøres etter at importen er fullført i overstyringsdefinisjonen for AfterPrimaryImport metoden. Verktøyet importerer de gjenværende flate filene som ikke ble importert tidligere, før løsningsimporten startet.

   8. Endre standardnavnet på pakkemappen til pakkenavnet du vil ha. Hvis du vil gjøre dette, kan du gi nytt navn til PkgFolder eller PkgAssets-mappen i løsningsutforsker-ruten, og deretter redigere returverdien under egenskapen 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. Endre pakkenavnet ved å redigere returverdien under GetNameOfImport-egenskapen.

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

      Denne returnerte verdien er navnet på pakken som vises på siden for pakkevalg i veiviseren for Dynamics 365 pakkedistribusjon.

   10. Endre pakkebeskrivelsen ved å redigere returverdien under GetImportPackageDescriptionText-egenskapen.

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

       Denne returnerte verdien er pakkebeskrivelsen som vises sammen med pakkenavnet på pakkeutvalgssiden i Package Deployer-veiviseren.

   11. Endre det lange pakkenavnet ved å redigere returverdien under GetLongNameOfImport-egenskapen.

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

       Det lange pakkenavnet vises på neste side etter at du har valgt pakken du vil installere.

3. Pakken har også tilgang til følgende funksjoner og variabler:

   Navn	Type	Beskrivelse
   CreateProgressItem(String)	Funksjon	Oppretter et nytt fremdriftselement i brukergrensesnittet.
   RaiseUpdateEvent(String, ProgressPanelItemStatus)	Funksjon	Oppdaterer fremdriften som ble opprettet av kallet til CreateProgressItem(String). ProgressPanelItemStatus er en enum med følgende verdier: Arbeider = 0 Fullført = 1 Mislykket = 2 Advarsel = 3 Ukjent = 4
   RaiseFailEvent(String, Exception)	Funksjon	Mislykk import av gjeldende status med en unntaksmelding.
   IsRoleAssociatedWithTeam(Guid, Guid)	Funksjon	Bestemmer om en rolle er knyttet til et angitt team.
   IsWorkflowActive(Guid)	Funksjon	Bestemmer om en angitt arbeidsflyt er aktiv.
   PackageLog	Klassepeker	En peker til det initialiserte grensesnittet for loggføring for pakken. Pakken bruker dette grensesnittet til å logge meldinger og unntak til pakkeloggfilen.
   RootControlDispatcher	Egenskap	Et dispatchergrensesnitt som kontrollen bruker til å gjengi sitt eget brukergrensesnitt under pakkedistribuering. Bruk dette grensesnittet til å pakke alle grensesnittelementer eller kommandoer. Kontroller denne variabelen for nullverdier før du bruker den, da den kanskje ikke er satt til en verdi.
   CrmSvc	Egenskap	En peker til CrmServiceClient-klassen som gjør det mulig for en pakke å få tilgang til Dynamics 365 fra pakken. Bruk denne pekeren til å utføre SDK-metoder og andre handlinger i overstyrte metoder.
   DataImportBypass	Egenskap	Angi om Dynamics 365 Pakkedistribusjon hopper over alle dataimportoperasjoner, for eksempel import av dataverse eksempeldata, flate fildata og data som eksporteres fra verktøyet for konfigurasjonsoverføring. Angi true eller false. Standard er false.
   OverrideDataImportSafetyChecks	Egenskap	Angi om Dynamics 365 Package Deployer omgår noen av sikkerhetskontrollene, noe som bidrar til å forbedre importytelsen. Angi true eller false. Standard er false. Angi denne egenskapen til true bare hvis mål-Dataverse-forekomsten ikke inneholder noen data.

4. Lagre prosjektet. Det neste trinnet er å bygge pakken.

Bygg og distribuer

De følgende delene beskriver hvordan du bygger og distribuerer en pakke.

Bygg

Avsnittene nedenfor beskriver hvordan du bygger pakken, avhengig av hvilket verktøy du bruker.

> 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 av følgende filer under *<Project>*\Bin\Debug mappen:

• <PackageName> mappe: Mappenavnet samsvarer med navnet du valgte for pakkemappen i trinn 2.g i delen Legg til egendefinert kode . Denne mappen inneholder alle løsninger, konfigurasjonsdata, flate filer og alt innhold for pakken.

• <PackageName>.dll: Assemblyen inneholder den egendefinerte koden for pakken. Som standard samsvarer navnet på assemblyen med prosjektnavnet.

Distribuere

Når du har opprettet en pakke, distribuerer du den på Dataverse-forekomsten ved hjelp av Package Deployer-verktøyet, Windows PowerShell eller en CLI-kommando.

• Hvis du vil distribuere ved hjelp av pakkedistribusjonsverktøyet, må du først laste ned verktøyet som beskrevet i dataverse utviklingsverktøy. Deretter følger du den detaljerte informasjonen om pakkedistribusjon i artikkelen Deploy-pakker ved hjelp av Pakkedistribusjonsprogram eller Windows PowerShell.

• Hvis du vil distribuere ved hjelp av CLI, bruker du pac package deploy kommandoen.

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

  Notat

  Hvis du vil distribuere en pakke til et målmiljø ved hjelp av CLI, må du først konfigurere en godkjenningsprofil og velge en organisasjon. Hvis du vil ha mer informasjon, kan du se pac auth create og pac org select.

Anbefalte fremgangsmåter

Nedenfor finner du noen anbefalte fremgangsmåter du kan følge når du arbeider med Package Deployer-pakker.

Opprettelse av pakker

Når utviklere oppretter pakker, må de gjøre følgende:

• Sørg for at pakkesamlinger er signert.

Distribusjon av pakker

Under distribusjon av pakker må Dataverse-administratorer gjøre følgende:

• Insister på signerte pakkesamlinger , slik at du kan spore en samling tilbake til kilden.
• Test pakken på en førproduksjonsforekomst, fortrinnsvis et speilbilde av produksjonsforekomsten, før du kjører den på en produksjonsforekomst.
• Sikkerhetskopier produksjonsforekomsten før du distribuerer pakken.

Se også

Løsningspakkeprogram (verktøy)