Ustvarjanje paketov za orodje Package Deployer
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.
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.
Dodajanje datotek paketa
Ko ustvarite projekt paketa, lahko začnete dodajati rešitve in druge datoteke temu projektu.
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.
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 datotekiImportConfig.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 datotekiImportConfig.xml
. Privzeta datoteka za uvoz konfiguracijskih podatkov je določena v atributucrmmigdataimportfile
v datotekiImportConfig.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 lastnostiGetImportPackageDataFolderName
.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 = 4RaiseFailEvent(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
alifalse
. Privzeta nastavitev jefalse
.
To lastnost nastavite natrue
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.
Č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.
Ustvarjanje paketov
Pri ustvarjanju paketov morajo razvijalci storiti naslednje:
- Zagotovite, da so sklopi paketov podpisani.
Uvedba paketov
Pri uvajanju paketov morajo skrbniki Dataverse storiti naslednje:
- Vztrajajte pri podpisanih sklopih paketov tako da lahko sledite sklopu nazaj do njegovega vira.
- Preskusite paket na predprodukcijskem primerku, po možnosti zrcalni sliki produkcijski primerek, preden ga zaženete na produkcijski primerek.
- Varnostno kopirajte produkcijski primerek pred uvedbo paketa.