Del via

Opprette pakker for Package Deployer-verktøyet

  • Artikkel

Package Deployer gjør det mulig for 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.

Obs!

Det finnes en annen pakketype kalt en programtilleggspakke. Denne pakketypen er for programtilleggsavhengige samlinger og har ingen relasjon til Package Deployer-pakker.

Forutsetning

  • 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

Utfør følgende trinn for å opprette en Package Deployer-pakke.

  • Opprett et Visual Studio- eller MSBuild-prosjekt
  • Legg til løsninger og andre filer i prosjektet
  • Oppdater angitte HTML-filer (valgfritt)
  • Angi konfigurasjonsverdier for pakken
  • Definer egendefinert kode for pakken
  • Bygg og distribuer pakken

Denne fremgangsmåten er beskrevet nærmere i denne artikkelen.

Opprett et pakkeprosjekt

Det første trinnet er å opprette et Visual Studio- eller MSBuild-prosjekt for pakken. For å kunne gjøre dette må du ha én av to tilgjengelige verktøyutvidelser installert på utviklingsdatamaskinen. Hvis du bruker Visual Studio Code, installerer du Microsoft Power Platform CLI. Ellers, hvis du bruker Visual Studio 2019 eller senere, installerer du Power Platform Tools for Visual Studio.

Velg den aktuelle fanen nedenfor for å finne ut hvordan du oppretter et prosjekt med ønsket verktøyutvidelse. Begge verktøyene gir prosjektet et lignende format.

Kjør kommandoen pac package init for å opprette den første pakken. Mer informasjon: pac package

pac package init help
pac package init --outputDirectory DeploymentPackage

De påfølgende CLI-utdataene inneholder mappene og filene som vises nedenfor. Mappenavnet «DeploymentPackage» ble brukt her som eksempel.

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

I det opprettede prosjektet finner du ImportConfig.xml-konfigurasjonsfilen i PkgAssets-mappen og PackageImportExtension.cs-filen. Du endrer disse filene som beskrevet senere i denne artikkelen.

Legg til pakkefiler

Etter at du har opprettet et pakkeprosjekt, kan du begynne å legge til løsninger og andre filer i dette prosjektet.

Når du bruker CLI, kan du legge til eksterne pakker, løsninger og referanser i pakkeprosjektet ved hjelp av en av underkommandoene add. Angi pac package help for å vise listen over underkommandoer. La oss legge til en løsning i 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.

Konfigurer pakken

Definer pakkekonfigurasjonen ved å legge til informasjon om pakken i filen ImportConfig.xml i prosjektet. Se ImportConfig-referanse for et eksempel og beskrivelser av de gyldige elementene og attributtene som skal brukes.

Legg til egendefinert kode

Du kan legge til egendefinert kode som kjører før, under og etter at pakken er importert til et miljø. Følg instruksjonene nedenfor for å gjøre dette.

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

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

    1. Angi en egendefinert kode som skal kjøres når pakken er initialisert i definisjonen for overstyringsmetode for InitializeCustomExtension.

      Denne metoden kan brukes til å la brukere bruke kjøretidsparameterne under kjøring av 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 har angitt eventuelle kjøretidsparametere under kjøring av Package Deployer (enten ved hjelp av kommandolinjen eller PowerShell), og behandler deretter informasjonen tilsvarende. Hvis det ikke er angitt en kjøretidparameter for brukeren mens pakken kjører, vil verdien av RuntimeSettings-egenskapen være 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 koden gjør at administratoren kan bruke kommandolinjen eller Import-CrmPackage til å angi om sikkerhetskontrollene skal hoppes over mens Package Deployer-verktøyet kjøres for å importere pakken. Mer informasjon: Distribuere pakker ved hjelp av Package Deployer og Windows PowerShell

    2. Angi en egendefinert kode som skal kjøres før løsningene importeres i definisjonen av overstyringsmetode for PreSolutionImport for å angi om du vil vedlikeholde eller overskrive tilpassinger mens du oppdaterer den angitte løsningen i en målforekomst av Dataverse, og om du automatisk vil aktivere plugin-moduler og arbeidsflyter.

    3. Bruk definisjonen for overstyringsmetoden for RunSolutionUpgradeMigrationStep til å utføre datatransformasjon eller oppgradering mellom to versjoner av en løsning. Denne metoden kalles bare hvis løsningen du importerer, allerede finnes i Dataverse-målforekomsten.

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

    5. Overstyr det valgte språket for konfigurasjonsdataimport ved hjelp av definisjonen av overstyringsmetode for OverrideConfigurationDataFileLanguage. Hvis angitt ID for nasjonale innstillinger (LCID) for det angitte språket ikke finnes i listen over tilgjengelige språk i pakken, importeres standard datafil.

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

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

    6. Angi en egendefinert kode som skal kjøres etter at løsningsimporten er fullført i overstyringsdefinisjonen for AfterPrimaryImport>-metoden. De gjenværende flate filene som ikke ble importert tidligere før løsningsimporten startet, blir importert nå.

    7. Endre standardnavnet på pakkemappen til pakkenavnet du vil ha. Dette gjør du ved å gi nytt navn til mappen PkgFolder (eller PkgAssets) 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 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. 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å pakkeutvalgssiden i Dynamics 365 Package Deployer-veiviseren.

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

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

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

      Pakkens lange navn vises på neste side etter at du har valgt pakken som skal installeres.

  3. I tillegg er følgende funksjoner og variabler tilgjengelige for pakken:

    Navn Type Beskrivelse
    CreateProgressItem(String) Function Brukes til å opprette et nytt fremdriftelement i brukergrensesnittet (UI).
    RaiseUpdateEvent(String, ProgressPanelItemStatus) Function Brukes til å oppdatere fremdriften som ble opprettet av kallet til CreateProgressItem(String).

    ProgressPanelItemStatus er en opplisting med følgende verdier:

    Arbeider = 0
    Fullført = 1
    Mislykket = 2
    Advarsel = 3
    Ukjent = 4
    RaiseFailEvent(String, Exception) Function Brukes til å angi at gjeldende statusimport er mislykket med en unntaksmelding.
    IsRoleAssoicatedWithTeam(Guid, Guid) Function Brukes til å avgjøre om en rolle er tilknyttet et bestemt team.
    IsWorkflowActive(Guid) Function Brukes til å avgjøre om en angitt arbeidsflyt er aktiv.
    PackageLog Klassepeker En peker til grensesnittet for initialisert logging for pakken. Dette grensesnittet brukes av en pakke til å logge meldinger og unntak til pakkeloggfilen.
    RootControlDispatcher Egenskap Et fordelingsgrensesnitt som brukes til å tillate at kontrollen gjengir sitt eget brukergrensesnitt under pakkedistribusjon. Bruk dette grensesnittet til å pakke alle grensesnittelementer eller kommandoer. Det er viktig å kontrollere denne variabelen for nullverdier før du bruker den, fordi det kan hende at den ikke er satt til en verdi.
    CrmSvc Egenskap En peker til CrmServiceClient-klasse som gjør at en pakke kan kommunisere med Dynamics 365 innenfra pakken. Bruk denne pekeren til å utføre SDK-metoder og andre handlinger i overstyrte metoder.
    DataImportBypass Egenskap Angi om Dynamics 365 Package Deployer skal hoppe over alle dataimportoperasjoner, for eksempel import av Dataverse-eksempeldata, flate fildata og data eksportert fra verktøyet for konfigurasjonsoverføring. Angi usann eller usann. Standard er false.
    OverrideDataImportSafetyChecks Egenskap Angi om Dynamics 365 Package Deployer skal hoppe over noen av sikkerhetskontrollene, noe som bidrar til å forbedre importytelsen. Angi true eller false. Standard er false.

    Du bør bare angi denne egenskapen til true hvis Dataverse-målforekomsten 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.

Build

Å bygge pakken er beskrevet nedenfor avhengig av hvilket verktøy du bruker.

Hvis du vil bygge en pakke opprettet med CLI, kan du laste inn .csproj-filen i Visual Studio, men i stedet skal vi bruke DotNet-kommandoen og MSBuild. Eksemplet nedenfor forutsetter at arbeidsmappen inneholder filen *.csproj.

> dotnet publish

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

Du kan eventuelt se på detaljene for den bygde pakken.

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

Pakken din består av følgende filer i mappen <Project>\Bin\Debug.

  • <Pakkenavn-mappe>: Mappenavnet er det samme som det du endret for pakkemappenavnet i trinn 2.g i denne delen Legg til egendefinert kode. Denne mappen inneholder alle løsninger, konfigurasjonsdata, flate filer og alt innhold for pakken.

Obs!

Det kan hende at du ser en .NET-mappe (for eksempel net472) som inneholder en pdpublish-mappe. DLL-filen og andre prosjektfiler ligger i denne pdpublish-mappen.

  • <PackageName.DLL>: Samlingen inneholder den egendefinerte koden for pakken. Som standard er navnet på samlingen det samme som prosjektnavnet.

Distribuere

Etter at du har opprettet en pakke, kan du distribuere den i Dataverse-forekomsten ved å bruke Package Deployer-verktøyet, Windows PowerShell eller en CLI-kommando.

  • Hvis du vil distribuere ved hjelp av Package Deployer-verktøyet, laster du først ned verktøyet som beskrevet i Dataverse-utviklingsverktøy. Deretter følger du den detaljerte informasjonen om pakkedistribusjon i artikkelen Distribuer pakker ved å bruke Package Deployer eller Windows PowerShell.

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

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

    Obs!

    Hvis du vil distribuere en pakke i et målmiljø ved hjelp av CLI, må du først konfigurere en godkjenningsprofil og velge en organisasjon. Mer informasjon: pac auth create, pac org select

Beste 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å

Solution Packager-verktøy