Kreiranje paketa za alatku Package Deployer

Članak
06/26/2024

Package Deployer omogućava administratorima primenu paketa na instancama usluge Microsoft Dataverse. Package Deployer paket može da se sastoji od bilo čega sledećeg:

Jedna ili više datoteka Dataverse rešenja.
Proste datoteke ili izvezena datoteka konfiguracije iz alatke Configuration Migration Tool. Za više informacija o alatki, pogledajte članak Premeštanje podataka o konfiguraciji između instanci i organizacija pomoću alatke Configuration Migration Tool.
Prilagođeni kôd koji može da se pokreće pre, tokom ili posle primene paketa u Dataverse instanci.
HTML sadržaj karakterističan za paket koji može biti prikazan na početku i na kraju procesa primene. Ovaj sadržaj može biti koristan za pružanje opisa rešenja i datoteka primenjenih u paketu.

Belešku

Postoji još jedan tip paketa koji se zove paket dodatnih komponenti. Takva vrsta paketa je za zavisne sklopove dodatnih komponenti i nema nikakav odnos sa Package Deployer paketima.

Preduslovi

Proverite da li ste spremili sva rešenja i druge datoteke koje želite da uključite u paket.
Visual Studio 2019. ili kasnije, ili Visual Studio Šifra.

Pregled procesa

Da biste kreirali Package Deployer paket, izvršite sledeće korake.

Kreirajte Visual Studio ili MSBuild projekat
Dodajte rešenje i druge datoteke projektu
Ažurirajte obezbeđene HTML datoteke (opcionalno)
Navedite vrednosti konfiguracije za paket
Definišite prilagođeni kôd za paket
Izradite i primenite paket

Ovi koraci su detaljno opisani u ovom članku.

Kreirajte projekat za paket

Prvi korak je kreiranje Visual Studio ili MSBuild projekta za paket. Da biste to uradili, na razvojnom računaru morate imati instalirano jedno od dva dostupna proširenja alatke. Ako koristite Visual Studio Code, instalirajte Microsoft Power Platform CLI. U suprotnom, ako koristite Visual Studio 2019 ili noviju, instalirajte Power Platform alatke za Visual Studio.

Izaberite odgovarajuću karticu ispod da biste saznali kako da kreirate projekat koristeći željeno proširenje alatke. Obe alatke izlaze iz projekta u sličnom formatu.

Power Platform CLI
Power Platform Tools

Pokrenite komandu pac package init da biste kreirali početni paket. Još informacija: pac package

pac package init help
pac package init --outputDirectory DeploymentPackage

Rezultujući CLI izlaz sadrži fascikle i datoteke prikazane ispod. Naziv fascikle „DeploymentPackage“ je ovde korišćen kao primer.

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

U kreiranom projektu pronađite datoteku za ImportConfig.xml u fascikli PkgAssets i datoteci PackageImportExtension.cs uređaja. Izmenićete ove datoteke kao što je opisano u ovom članku.

Projekat možete da kreirate Visual Studio pomoću predloška Power Platform rešenja, a kasnije da dodate paket projekat pomoću Power Platform predloška projekta primene paketa ili da kreirate projekat direktno pomoću predloška Power Platform projekta raspoređivanja paketa.

Dodajte paket projekat.

Belešku

Nemojte birati predložak Power Platform paketa. Taj predložak je za pakete dodatnih komponenti.

Rezultujuće Visual Studio rešenje i projekat sadrži fascikle i datoteke prikazane u nastavku. Naziv fascikle „Deployment-package“ je ovde korišćen kao primer. Sadržaj fascikle "Sadržaj" nije prikazan ovde zbog brevitacije.

C:.
│   Deployment-package.csproj
│   Deployment-package.sln
│   GettingStarted.html
│   PackageTemplate.cs
│
├───PkgFolder
│   │   ImportConfig.xml
│   │
│   └───Content

U kreiranom projektu pronađite datoteku za ImportConfig.xml u fascikli PkgFolder i u datoteci PackageTemplate.cs uređaja. Izmenićete ove datoteke kao što je opisano u ovom članku.

Više informacija o korišćenju proširenja Power Platform Tools: Brzi start: Kreiranje projekta Power Platform Tools

Dodajte datoteke paketa

Kada kreirate projekat paketa, možete početi da dodajete rešenja i druge datoteke tom projektu.

Power Platform CLI
Power Platform Tools

Kada koristite CLI, možete da dodate spoljne pakete, rešenja i reference na projekat paketa pomoću jedne od potkomandi add. Unesite pac package help da biste videli listu potkomandi. Hajde da dodamo rešenje u naš paket.

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

U oknu Istraživač rešenja, dodajte svoja Dataverse rešenja i druge datoteke ispod fascikle PkgFolder. HTML datotekama je mesto u fascikli Sadržaj. Više o ovom HTML sadržaju kasnije.
Za svaku datoteku koju dodate u fasciklu Svojstva, podesite vrednost Kopiraj u izlazni direktorijum na Kopiraj uvek. Postavka ove vrednosti obezbeđuje da datoteka koju ste dodali bude dostupna u generisanom paketu.

Zatim ažurirajte datoteke specifične za HTML jezik.

U oknu istraživača rešenja, proširite PkgFolder>Sadržaj>en-us. Pronađite dve fascikle koje se zovu EndHTML i WelcomeHTML. Te fascikle sadrže HTML i pridružene datoteke koje vam omogućavaju da prikažete informacije (korisniku) na kraju i na početku procesa primene paketa. Uredite datoteke u HTML fascikli ovih fascikli da biste dodali informacije u prikaz za svoj paket.
Takođe možete dodati HTML datoteke u vašem paketu na drugim jezicima tako da se sadržaj u HTML-u prikazuje na jeziku zasnovanom na postavkama lokalnog standarda računara korisnika. Da biste to uradili:
1. Kreirajte kopiju fascikle en-us u fascikli PkgFolder>Sadržaj.
2. Preimenujte kopiranu fasciklu u odgovarajući jezik. Na primer, za španski jezik preimenujte fasciklu u es-ES.
3. Izmenite sadržaj HTML datoteka tako da dodate sadržaj na španskom.

Konfigurišite paket

Definišite konfiguraciju paketa dodavanjem informacija o vašem paketu u datoteci ImportConfig.xml u projektu. Pogledajte referencu "ImportConfig " za primer i opise važećih elemenata i atributa koje treba koristiti.

Dodajte prilagođeni kôd

Možete da dodate prilagođeni kôd koji se izvršava pre, tokom i nakon uvoza paketa u okruženje. Da biste to uradili, sledite sledeća uputstva.

Uredite datoteku PackageTemplate.cs (ili PackageImportExtension.cs) u osnovnoj fascikli projekta.

U C# datoteci možete da uradite sledeće:

Unesite prilagođeni kôd koji će se izvršiti kada se paket pokrene definiciji metoda za izmenu InitializeCustomExtension.

Ova metoda se može koristiti za omogućavanje korisnicima da koriste parametre izvođenja tokom izvođenja paketa. Kao programer, možete u svoj paket dodati podršku za bilo koji parametar izvršavanja koristeći svojstvo RuntimeSettings dok god imate kôd za obradu na osnovu korisničkog unosa.

Na primer, sledeći primer koda omogućava parametar izvođenja koji se zove SkipChecks za paket koji ima dve moguće vrednosti: true ili false. Primer koda proverava da li je korisnik naveo bilo kakve parametre izvođenja tokom izvođenja alatke Package Deployer (bilo korišćenjem komandne linije ili platforme PowerShell), a zatim u skladu s tim obrađuje informacije. Ako korisnik tokom izvođenja paketa ne navede nijedan parametar izvođenja, svojstvo RuntimeSettings će biti bez vrednosti.
```
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");  
}  
```
Ovaj kôd omogućava administratoru da koristi komandnu liniju ili cmdlet komandu Import-CrmPackage da odredi da li da preskoči bezbednosne provere tokom pokretanja alatke Package Deployer za uvoz paketa. Još informacija: Primena paketa korišćenjem alatke Package Deployer i platforme Windows PowerShell
Unesite prilagođeni kôd koji treba izvršiti pre uvoza rešenja u definiciji zamene metode PreSolutionImport da biste odredili da li treba da održavaju ili zamene prilagođavanja tokom ažuriranja navedenog rešenja u ciljnoj Dataverse instanci i da li treba automatski aktivirati dodatne komponente i tokove posla.

Koristite definiciju metoda zamene da biste RunSolutionUpgradeMigrationStep izvršili transformaciju podataka ili nadogradnju između dve verzije rešenja Ovaj metod je pozvan samo ako je rešenje koje uvozite već prisutno u ciljnoj Dataverse instanci.

Ova funkcija očekuje sledeće parametre:

Parametar	Opis
`solutionName`	Naziv rešenja
`oldVersion`	Broj verzije starog rešenja
`newVersion`	Broj verzije novog rešenja
`oldSolutionId`	GUID starog rešenja.
`newSolutionId`	GUID novog rešenja.

Unesite prilagođeni kôd koji će se izvršiti pre nego što se dovrši uvoz rešenja u definiciji zamene metode BeforeImportStage. Podaci primera i neke proste datoteke za rešenja navedena u datoteci ImportConfig.xml se uvoze pre nego što se uvoz rešenja dovrši.
Zamenite trenutno izabrani jezik za uvoz podataka za konfiguraciju koristeći definiciju metoda zamene OverrideConfigurationDataFileLanguage. Ako navedeni ID lokalnog standarda (LCID) navedenog jezika nije pronađen na listi dostupnih jezika u paketu, podrazumevana datoteka sa podacima se uvozi.

Možete navesti dostupne jezike za podatke konfiguracije u čvoru <cmtdatafiles> u datoteci ImportConfig.xml. Podrazumevana datoteka za uvoz podataka konfiguracije navedena je u atributu crmmigdataimportfile u datoteci ImportConfig.xml.

Preskakanje provere podataka (OverrideDataImportSafetyChecks = tačno) može biti efikasno ovde ako ste sigurni da Dataverse ciljna instanca ne sadrži podatke.
Unesite prilagođeni kôd koji će se izvršiti nakon što se dovrši uvoz rešenja u definiciji zamene metode AfterPrimaryImport>. Preostale ravne datoteke koje ranije nisu uvezene, pre nego što je započet uvoz rešenja, sada se uvoze.

Promenite podrazumevani naziv fascikle paketa u naziv paketa koji želite. Da biste to učinili, preimenujte fasciklu PkgFolder(ili PkgAssets) u oknu Istraživač rešenja, a zatim izmenite povratnu vrednost ispod svojstva 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";  
}  
}

Promenite ime paketa tako što ćete urediti povratnu vrednost ispod svojstva GetNameOfImport.
```
public override string GetNameOfImport(bool plural)  
{  
return "Package Short Name";  
}  
```
Ova vraćena vrednost je ime paketa koji se pojavljuje na stranici za izbor paketa u čarobnjaku za Dynamics 365 Package Deployer .
Promenite opis paketa tako što ćete urediti povratnu vrednost ispod svojstva GetImportPackageDescriptionText.
```
public override string GetImportPackageDescriptionText  
{  
get { return "Package Description"; }  
}  
```
Ova vraćena vrednost je opis paketa koji se pojavljuje zajedno sa imenom paketa na stranici za izbor paketa u čarobnjaku Package Deployer .
Promenite dugi naziv paketa tako što ćete urediti povratnu vrednost ispod svojstva GetLongNameOfImport.
```
public override string GetLongNameOfImport  
{  
get { return "Package Long Name"; }  
}  
```
Dugi naziv paketa se prikazuje na sledećoj stranici nakon što ste izabrali paket za instalaciju.

Pored toga, u paketu su dostupne sledeće funkcije i promenljive:

+Ime	Tip	Opis
CreateProgressItem(String)	Function	Koristi se za kreiranje nove stavke napretka u korisničkom interfejsu (UI).
RaiseUpdateEvent(String, ProgressPanelItemStatus)	Function	Koristi se za ažuriranje napretka kreiranog pozivom CreateProgressItem(String). ProgressPanelItemStatus je numerička vrednost sa sledećim vrednostima: Working = 0 Complete = 1 Failed = 2 Warning = 3 Unknown = 4
RaiseFailEvent(String, Exception)	Function	Koristi se za neuspeh uvoza trenutnog statusa sa porukom o izuzimanju.
IsRoleAssoicatedWithTeam(Guid, Guid)	Function	Koristi se za utvrđivanje da li je uloga povezana sa određenim timom.
IsWorkflowActive(Guid)	Function	Koristi se za utvrđivanje da li je određeni tok posla aktivan.
PackageLog	Pokazivač klase	Pokazivač na pokrenuti interfejs za evidentiranje paketa. Ovaj interfejs se koristi u paketu za evidentiranje poruka i izuzetaka u datoteci evidencije paketa.
RootControlDispatcher	Svojstvo	Ovo je interfejs za dispečera koji se koristi kako bi kontrola mogla da prikaže sopstveni korisnički interfejs tokom primene paketa. Koristite ovaj interfejs da obuhvatite sve elemente ili komande korisničkog interfejsa. Važno je da proverite da li u ovoj promenljivoj ima vrednosti "null" pre nego što je upotrebite jer možda nije postavljena na vrednost.
CrmSvc	Svojstvo	Pokazivač na klasu CrmServiceClient koja omogućava paketu da se obraća sistemu Dynamics 365 iz paketa. Koristite ovaj pokazivač za izvršavanje SDK metoda i drugih radnji u zamenjenim metodama.
DataImportBypass	Svojstvo	Navedite da li Dynamics 365 Package Deployer preskače sve operacije uvoza podataka, kao što je uvoz Dataverse probnih podataka, podataka prostih datoteka i podataka izvezenih iz alatke Configuration Migration Tool. Navedite „true“ ili „false“. Podrazumevano je `false`.
OverrideDataImportSafetyChecks	Svojstvo	Navedite da li Dynamics 365 Package Deployer zaobilazi neke od svojih bezbednosnih provera, što pomaže u poboljšanju performansi uvoza. Navedite `true` ili `false`. Podrazumevano je `false`. Ovo svojstvo bi trebalo da postavite `true` samo ako ciljna Dataverse instanca ne sadrži podatke.

Sačuvajte projekat. Sledeći korak je da izgradite paket.

Izgradite i primenite

Sledeći odeljci opisuju kako se pravi i primenjuje paket.

Pravljenje

Izrada paketa je opisana ispod u zavisnosti od alatke koju koristite.

Power Platform CLI
Power Platform Tools

Da biste napravili paket kreiran pomoću CLI-ja, možete da učitate .csproj datoteku Visual Studio u, ali umesto toga koristićemo komandu dotnet i MSBuild. Primer u nastavku pretpostavlja da radni direktorijum sadrži datoteku *.csproj.

> dotnet publish

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

Opcionalno možete pogledati detalje izgrađenog paketa.

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

Paket sačinjavaju sledeće datoteke ispod fascikle <Project>\Bin\Debug.

<Fascikla PackageName>: Ime fascikle je isto kao i ono koje ste promenili za ime fascikle paketa u korak 2.g ovog odeljka Dodajte prilagođeni kôd. Ova fascikla sadrži sva rešenja, podatke konfiguracije, proste datoteke i sadržaj paketa.

Belešku

Možda ćete videti fasciklu .NET (npr. net472) koja sadrži fasciklu pdpublish. DLL i druge datoteke projekta se nalaze u fascikli pdpublish.

<PackageName>.dll: Sklop sadrži prilagođeni kôd za vaš paket. Naziv sklopa je podrazumevano isti kao i naziv vašeg projekta.

Primena

Kada kreirate paket, možete ga primeniti na Dataverse instancu koristeći alatku Package Deployer, Windows PowerShell ili CLI komandu.

Da biste je primenili pomoću alatke Package Deployer, prvo preuzmite alatku kao što je opisano u Dataverse alatkama za razvoj. Zatim sledite detaljne informacije o primeni paketa u paketima za primenu članka pomoću Package Deployer ili Windows PowerShell paketa.
Da biste je primenili pomoću CLI, koristite komandu pac package deploy.
```
> pac package deploy --package .\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip
```
Belešku

Da biste primenili paket u ciljno okruženje pomoću CLI, prvo morate da podesite profil potvrde identiteta i izaberete organizaciju. Još informacija: pac auth create, pac org select

Najbolji primeri iz prakse

U nastavku je navedeno nekoliko najboljih saveta za vežbanje koje treba slediti prilikom rada sa Package Deployer paketima.