Ustvarjanje paketov za orodje Package Deployer

Package Deployer omogoča administratorjem nameščanje paketov na Microsoft Dataverse instance. 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 novejši, ali Visual Studio Code.

Pregled procesa

Če želite ustvariti paket, sledite naslednjim korakom. Package Deployer

Ustvarite projekt v 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 ustvariti projekt v Visual Studio ali MSBuild za ta paket. Če želite to narediti, morate imeti v računalniku za razvoj nameščeno eno od dveh razpoložljivih razširitev orodja. Če uporabljaš Visual Studio Code, namesti Microsoft Power Platform CLI. V nasprotnem primeru, če uporabljate Visual Studio 2019 ali novejše, namestite orodja Power Platform 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.

Lahko ustvarite Visual Studio projekt z uporabo predloge rešitve Power Platform in kasneje dodate paket projekt z uporabo predloge Power Platform Package Deployment Project ali ustvarite projekt neposredno z uporabo predloge Power Platform Package Deployment Project.

Dodajte paketni projekt.

opomba,

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

Končna rešitev in projekt za Visual Studio vsebuje mape in datoteke, prikazane spodaj. Ime »Deployment-package« je bilo tukaj uporabljeno kot primer. Vsebina mape Vsebina zaradi kratkosti tukaj ni prikazana.

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 oknu Solution Explorer razširite PkgFolder>Content>en-us. Poiščite dve mapi z imenoma 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, glejte ImportConfig Reference .

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()  
{
  // 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: Namestitev paketov z uporabo Package Deployerja 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.

Za izvedbo transformacije podatkov ali nadgradnje med dvema različicama rešitve uporabite definicijo metode preglasitve RunSolutionUpgradeMigrationStep . Ta metoda se pokliče le, če je rešitev, ki jo uvažate, že prisotna v ciljnem primerku Dataverse .

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.

Preglasite metodo OverrideSolutionImportDecision , da vrnete izlim UserRequestedImportAction in nadzoruje, ali bo uvoz rešitve preskočen, posodobljen ali nadgrajen (privzeto).

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);
}

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.
Trenutno izbrani jezik za uvoz konfiguracijskih podatkov preglasite z uporabo definicije metode preglasitve OverrideConfigurationDataFileLanguage. Če podanega ID-ja jezikovnih nastavitev (LCID) podanega 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.

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

Spremenite privzeto ime mape paketov v želeno ime paketa. Za to preimenujte mapo PkgFolder (ali PkgAssets) v oknu Solution Explorer in nato uredite povratno vrednost pod lastnostjo 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";  
    }  
}

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 prikaže poleg imena paketa na strani za izbiro paketov v čarovniku. Package Deployer
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 naštevanje 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.
IsRoleAssociatedWithTeam(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. Pred uporabo je pomembno preveriti, ali ima ta spremenljivka ničelne vrednosti, saj morda ni nastavljena na nobeno vrednost.
CrmSvc	Lastnost	Kazalec na razred CrmServiceClient, ki omogoča, da paket naslovi 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 Dynamics 365 Package Deployer preskoči vse operacije uvoza podatkov, kot so uvoz vzorčnih podatkov iz Dataverse, podatkov ravnih datotek in podatkov, izvoženih iz orodja Configuration Migration. Določite »true« ali »false«. Privzeta nastavitev je `false`.
OverrideDataImportSafetyChecks	Lastnost	Določite, ali Dynamics 365 Package Deployer obide nekatere varnostne preglede, kar pomaga izboljšati zmogljivost uvoza. Določite `true` ali `false`. Privzeta nastavitev je `false`. To lastnost nastavite na `true` le, če ciljni Dataverse instanca ne vsebuje nobenih podatkov.

Shranite projekt. Naslednji korak je gradnja paketa.

Gradnja in uvedba

V naslednjih razdelkih je opisano, kako zgraditi in namestiti paket.

Graditev

Izdelava paketa je opisana spodaj, odvisno od orodja, ki ga uporabljate.

Power Platform CLI
Power Platform orodja

Za izdelavo paketa, ustvarjenega s CLI, lahko naložite .csproj datoteko 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.

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

opomba,

Morda boste videli .NET mapo (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 namestite na instanco Dataverse z uporabo orodja Package Deployer, Windows PowerShell ali ukaza CLI.

Za uvedbo z orodjem Package Deployer najprej prenesite orodje, kot je opisano v razvojnih orodjih Dataverse. Nato sledite podrobnim informacijam o nameščanju paketov v članku Deploy packages using 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.