Ustvarjanje paketov za orodje Package Deployer

Članek
06/26/2024

Orodje Package Deployer skrbnikom omogoča uvajanje paketov pri primerkih Microsoft Dataverse. Paket Package Deployer je lahko sestavljen iz nekaterih ali vseh naslednjih elementov:

Ena ali več datotek z rešitvijo Dataverse.
Datoteke z nestrukturiranimi podatki ali datoteka s konfiguracijskimi podatki, izvožena iz orodja za selitev konfiguracije. Za več informacij o orodju glejte Premikanje konfiguracijskih podatkov med primerki in organizacijami z orodjem Configuration Migration Tool.
Koda po meri, ki se lahko izvaja pred, med ali po uvedbi paketa v primerek Dataverse.
Vsebina HTML, značilna za paket, ki se lahko prikaže na začetku in ob koncu procesa uvajanja. Ta vsebina je lahko koristna za zagotavljanje opisa rešitev in datotek, ki se uvedejo v paketu.

opomba,

Obstaja še ena vrsta paketa, imenovana paket vtičnikov. Ta vrsta paketa je primerna za sklope, odvisne od vtičnikov, in ni v nobeni povezavi s paketi Package Deployer.

Zahteve

Prepričajte se, da imate pripravljeno rešitev in druge datoteke, ki jih želite vključiti v paket.
Visual Studio 2019 ali pozneje ali Visual Studio kodo.

Pregled procesa

Če želite ustvariti Package Deployer paket, izvedite naslednje korake.

Ustvarjanje projekta Visual Studio ali MSBuild
Dodajanje rešitev in drugih datotek v projekt
Posodobitev zagotovljenih datotek HTML (izbirno)
Določitev konfiguracijskih vrednosti za paket
Določitev kode po meri za paket
Gradnja in uvedba paketa

Ti koraki so podrobno opisani v tem članku.

Ustvarjanje paketa projekta

Prvi korak je ustvarjanje projekta Visual Studio ali MSBuild za paket. Če želite to narediti, morate imeti v računalniku za razvoj nameščeno eno od dveh razpoložljivih razširitev orodja. Če uporabljate Visual Studio Code, namestite vmesnik ukazne vrstice za Microsoft Power Platform. V nasprotnem primeru, če uporabljate Visual Studio 2019 ali novejšo različico, namestite Power Platform orodja za Visual Studio.

Izberite ustrezen zavihek spodaj, če želite izvedeti, kako ustvariti projekt z želeno razširitvijo orodja. Obe orodji ustvarita projekt v podobni obliki.

Power Platform CLI
Power Platform orodja

Zaženite ukaz pac package init, da ustvarite začetni paket. Več informacij: pac package

pac package init help
pac package init --outputDirectory DeploymentPackage

Nastali vmesnik ukazne vrstice vsebuje spodaj prikazane mape in datoteke. Ime mape »DeploymentPackage« je bilo tukaj uporabljeno kot primer.

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

V ustvarjenem projektu poiščite konfiguracijsko datoteko ImportConfig.xml v mapi PkgAssets in datoteko PackageImportExtension.cs. Te datoteke boste spremenili, kot je opisano kasneje v tem članku.

Ustvarite lahko Visual Studio projekt s predlogo Power Platform Solution Template in pozneje dodate projekt paketa s predlogo Power Platform Package Deployment Project ali ustvarite projekt neposredno z Power Platform Predloga projekta za razmestitev paketa.

Dodajte paketni projekt.

opomba,

Ne izberite predloge paketa Power Platform. Ta predloga velja za pakete vtičnikov.

Nastala rešitev Visual Studio in projekt vsebujeta spodaj prikazane mape in datoteke. Ime »Deployment-package« je bilo tukaj uporabljeno kot primer. Vsebina mape Content tukaj ni prikazana zaradi kratkosti.

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

V ustvarjenem projektu poiščite konfiguracijsko datoteko ImportConfig.xml v mapi PkgFolder in datoteko PackageTemplate.cs. Te datoteke boste spremenili, kot je opisano kasneje v tem članku.

Več informacij o uporabi razširitve orodij Power Platform: Hitri začetek: ustvarite projekt orodij Power Platform

Dodajanje datotek paketa

Ko ustvarite projekt paketa, lahko začnete dodajati rešitve in druge datoteke temu projektu.

Power Platform CLI
Power Platform orodja

Ko uporabljate vmesnik ukazne vrstice, lahko svojemu projektu paketa dodate zunanje pakete, rešitve in reference z enim od podukazov add. Vnesite pac package help za ogled seznama podukazov. Dodajmo rešitev v 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.

V podoknu Raziskovalec rešitev dodajte svoje rešitve Dataverse in druge datoteke pod mapo PkgFolder. Datoteke HTML spadajo v mapo Vsebina. Več o tej vsebini HTML pozneje.
Za vsako datoteko, ki jo dodate, v podoknu Lastnosti nastavite vrednost za Kopiraj v izhodni imenik na Kopiraj vedno. Z nastavitvijo te vrednosti boste zagotovili, da bodo datoteke na voljo v ustvarjenem paketu.

Nato posodobite datoteke, specifične za jezik HTML.

V podoknu Raziskovalec rešitev razširite PkgFolder>Vsebina>en-us. Poiščite dve mapi z imenom EndHTML in WelcomeHTML. Ti mapi vsebujeta HTML in povezane datoteke, ki vam omogočajo prikaz informacij (uporabniku) na koncu in začetku postopka uvajanja paketa. Uredite datoteke v mapi HTML teh map, da dodate prikazne informacije za svoj paket.
Datoteke HTML v svojem paketu lahko dodate tudi v drugih jezikih, da se vsebina v HTML prikaže v jeziku, ki temelji na območnih nastavitvah uporabnikovega računalnika. To naredite tako:
1. Ustvarite kopijo mape en-us v razdelku PkgFolder>Vsebina.
2. Kopirano mapo preimenujte v ustrezen jezik. Za španski jezik jo na primer preimenujte v es-ES.
3. Spremenite vsebino datotek HTML, da dodate špansko vsebino.

Konfiguracija paketa

Določite konfiguracijo paketa tako, da dodate informacije o paketu v datoteko ImportConfig.xml, ki je na voljo v projektu. Za primer in opise veljavnih elementov in atributov, ki jih je treba uporabiti, si oglejte Referenco ImportConfig .

Dodajanje kode po meri

Dodate lahko kodo po meri, ki se izvaja pred, med in po uvozu paketa v okolje. To naredite tako, da sledite spodnjim navodilom.

Uredite datoteko PackageTemplate.cs (ali PackageImportExtension.cs) v korenski mapi projekta.

V datoteki C# lahko:

Vnesete kodo po meri, ki jo želite izvesti, ko se paket inicializira v opredelitvi načina preglasitve InitializeCustomExtension.

Ta način se lahko uporablja, da uporabnikom omogoči uporabo parametrov izvajanja med izvajanjem paketa. Kot razvijalec lahko paketu dodate podporo za kateri koli parameter izvajanja z lastnostjo RuntimeSettings, dokler imate kodo za njegovo obdelavo na podlagi uporabnikovega vnosa.

Naslednja vzorčna koda na primer omogoča parameter izvajanja, imenovan SkipChecks, za paket, ki ima dve možni vrednosti: true ali false. Vzorčna koda preverja, ali je uporabnik med izvajanjem orodja Package Deployer določil kakšne parametre izvajanja (bodisi z uporabo ukazne vrstice ali storitve PowerShell), nato pa informacije ustrezno obdela. Če uporabnik med izvajanjem paketa ne določi nobenega parametra izvajanja, je vrednost lastnosti 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");  
}  
```
Ta koda skrbniku omogoča uporabo ukazne vrstice ali ukaza cmdlet Import-CrmPackage, da določi, ali naj se varnostno preverjanje preskoči med izvajanjem orodja Package Deployer za uvoz paketa. Več informacij: Uvajanje paketov z orodji Package Deployer in Windows PowerShell
Vnesete kodo po meri, ki jo želite izvesti pred uvozom rešitev v opredelitev načina preglasitve PreSolutionImport, da določite, ali naj se prilagoditve ohranijo ali prepišejo, medtem ko posodabljate določeno rešitev v ciljnem primeru Dataverse, ter ali naj se vtičniki in poteki dela samodejno aktivirajo.

Uporabite definicijo metode preglasitve RunSolutionUpgradeMigrationStep za izvedbo pretvorbe podatkov ali nadgradnje med dvema različicama rešitve. Ta metoda se pokliče le, če je rešitev, ki jo uvažate, že prisotna v cilju Dataverse primerek.

Ta funkcija pričakuje naslednje parametre:

Parameter	Opis
`solutionName`	Ime rešitve
`oldVersion`	Številka različice stare rešitve
`newVersion`	Številka različice nove rešitve
`oldSolutionId`	GUID stare rešitve.
`newSolutionId`	GUID nove rešitve.

Vnesete kodo po meri, ki jo želite izvesti pred dokončanjem uvoza rešitve v opredelitev preglasitve načina BeforeImportStage. Vzorčni podatki in nekaj datotek z nestrukturiranimi podatki za rešitve, navedene v datoteki ImportConfig.xml, se uvozijo, preden se uvoz rešitve zaključi.
Preglasite trenutno izbrani jezik za uvoz konfiguracijskih podatkov z uporabo definicije metode preglasitve OverrideConfigurationDataFileLanguage. Če podanega področnega ID-ja (LCID) navedenega jezika ni na seznamu razpoložljivih jezikov v paketu, se uvozi privzeta podatkovna datoteka.

Sami določite razpoložljive jezike za konfiguracijske podatke v vozlišču <cmtdatafiles> v datoteki ImportConfig.xml. Privzeta datoteka za uvoz konfiguracijskih podatkov je določena v atributu crmmigdataimportfile v datoteki ImportConfig.xml.

Preskok preverjanja podatkov (OverrideDataImportSafetyChecks = true) je tukaj lahko učinkovit, če ste prepričani, da ciljni Dataverse primerek ne vsebuje nobenih podatkov.
Vnesite kodo po meri, ki jo želite izvesti po dokončanju uvoza v definiciji za preglasitev načina AfterPrimaryImport>. Preostale ravne datoteke, ki niso bile uvožene prej, preden se je začel uvoz rešitve, so uvožene zdaj.

Spremenite privzeto ime mape paketov v želeno ime paketa. Če želite to narediti, preimenujte mapo PkgFolder (ali PkgAssets) v podoknu Raziskovalec rešitev in nato uredite vrnjeno vrednost v lastnosti 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";  
}  
}

Spremenite ime paketa tako, da uredite vrnjeno vrednost v lastnosti GetNameOfImport.
```
public override string GetNameOfImport(bool plural)  
{  
return "Package Short Name";  
}  
```
Ta vrnjena vrednost je ime vašega paketa, ki se pojavi na strani za izbiro paketa v čarovniku Dynamics 365 Package Deployer .
Spremenite opis paketa tako, da uredite vrnjeno vrednost v lastnosti GetImportPackageDescriptionText.
```
public override string GetImportPackageDescriptionText  
{  
get { return "Package Description"; }  
}  
```
Ta vrnjena vrednost je opis paketa, ki se pojavi poleg imena paketa na strani za izbiro paketa v Package Deployer čarovniku.
Spremenite dolgo ime paketa tako, da uredite vrnjeno vrednost v lastnosti GetLongNameOfImport.
```
public override string GetLongNameOfImport  
{  
get { return "Package Long Name"; }  
}  
```
Dolgo ime paketa se prikaže na naslednji strani, potem ko ste izberete paket za namestitev.

Poleg tega so v paketu na voljo naslednje funkcije in spremenljivke:

Imenu	Vrsti	Opis
CreateProgressItem(String)	Function	Uporablja se za ustvarjanje novega elementa napredka v uporabniškem vmesniku.
RaiseUpdateEvent(String, ProgressPanelItemStatus)	Function	Uporablja se za posodabljanje napredka, ustvarjenega s pozivom CreateProgressItem(String). ProgressPanelItemStatus je oštevilčenje z naslednjimi vrednostmi: Delovanje = 0 Dokončano = 1 Ni uspelo = 2 Opozorilo = 3 Neznano = 4
RaiseFailEvent(String, Exception)	Function	Uporablja se za neuspeh uvoza trenutnega stanja s sporočilom o izjemi.
IsRoleAssoicatedWithTeam(Guid, Guid)	Function	Uporablja se za določitev, ali je vloga povezana z določeno ekipo.
IsWorkflowActive(Guid)	Function	Uporablja se za določitev, ali je določen potek dela dejaven.
PackageLog	Kazalec razreda	Kazalec na inicializiran vmesnik za beleženje paketa. Paket uporablja ta vmesnik za beleženje sporočil in izjem v datoteki dnevnika paketov.
RootControlDispatcher	Lastnost	Vmesnik odpravitelja, ki se uporablja, da vašemu kontrolniku omogoča upodabljanje lastnega uporabniškega vmesnika med uvajanjem paketa. S tem vmesnikom lahko ovijete vse elemente ali ukaze uporabniškega vmesnika. Pomembno je, da preverite, ali ima ta spremenljivka ničelne vrednosti, preden jo uporabite, saj morda ni nastavljena na vrednost.
CrmSvc	Lastnost	Kazalec na razred CrmServiceClient, ki omogoča, da paket obravnava Dynamics 365 znotraj paketa. Uporabite ta kazalec za izvajanje načinov kompleta za razvoj programske opreme in drugih dejanj v preglašenih načinih.
DataImportBypass	Lastnost	Določite, ali naj Dynamics 365 Package Deployer preskoči vse postopke uvoza podatkov, kot je uvoz vzorčnih podatkov storitve Dataverse, podatkov datotek z nestrukturiranimi podatki in podatkov, izvoženih iz orodja Configuration Migration Tool. Določite »true« ali »false«. Privzeta nastavitev je `false`.
OverrideDataImportSafetyChecks	Lastnost	Določite, ali Dynamics 365 Package Deployer obide nekatera svoja varnostna preverjanja, kar pomaga pri izboljšanju zmogljivosti uvoza. Določite `true` ali `false`. Privzeta nastavitev je `false`. To lastnost nastavite na `true` samo, če ciljni Dataverse primerek ne vsebuje nobenih podatkov.

Shranite projekt. Naslednji korak je gradnja paketa.

Gradnja in uvedba

Naslednji razdelki opisujejo, kako zgraditi in razmestiti paket.

Graditev

Gradnja vašega paketa je opisana spodaj glede na to, katero orodje uporabljate.

Power Platform CLI
Power Platform orodja

Če želite zgraditi paket, ustvarjen s CLI, lahko naložite datoteko .csproj v Visual Studio, vendar bomo namesto tega uporabili ukaz dotnet in MSBuild. Spodnji primer predvideva, da delovni imenik vsebuje datoteko *.csproj.

> dotnet publish

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

Po želji si lahko ogledate podrobnosti zgrajenega paketa.

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

Vaš paket je sestavljen iz naslednjih datotek v mapi <Project>\Bin\Debug.

<PackageName> mapa: Ime mape je enako tistemu, ki ste ga spremenili za ime mape paketa v korak 2.g tega razdelka Dodaj koda po meri. Ta mapa vsebuje vse rešitve, konfiguracijske podatke, datoteke z nestrukturiranimi podatki in vsebine za vaš paket.

opomba,

Morda boste videli mapo .NET (npr. net472), ki vsebuje mapo pdpublish. Vaš DLL in druge projektne datoteke so v tej mapi pdpublish.

<PackageName>.dll: Sklop vsebuje kodo po meri za vaš paket. Privzeto je ime zbira enako kot ime projekta.

Uvedi

Ko ustvarite paket, ga lahko uvedete v primerek Dataverse z uporabo orodja Package Deployer, storitve Windows PowerShell ali ukaza vmesnika ukazne vrstice.

Za uvedbo z orodjem Package Deployer najprej prenesite orodje, kot je opisano v razvojnih orodjih Dataverse. Nato sledite podrobnim informacijam o uvajanju paketov v članku Uvedba paketov z uporabo Package Deployer ali Windows PowerShell.
Za uvedbo s pomočjo vmesnika ukazne vrstice uporabite ukaz pac package deploy.
```
> pac package deploy --package .\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip
```
opomba,

Če želite uvesti paket v ciljno okolje z uporabo vmesnika ukazne vrstice, morate najprej nastaviti profil za preverjanje pristnosti in izbrati organizacijo. Več informacij: pac auth create, pac org select

Najboljše prakse

Spodaj je navedenih nekaj nasvetov, ki jih je dobro upoštevati pri delu s paketi Package Deployer.