Csomagok létrehozása a Package Deployer eszközhöz

Cikk
06/26/2024

A Package Deployer lehetővé teszi a rendszergazdák számára a csomagok Microsoft Dataverse-példányokon való központi telepítését. A Package Deployer csomag összetevői az alábbiak lehetnek:

Egy vagy több Dataverse megoldásfájl.
Egybesimított fájlok vagy a Konfigurációáttelepítő eszközből exportált konfigurációs adatfájl. További információ az eszközről: Konfigurációs adatok áthelyezése példányok és szervezetek között a Konfigurációáttelepítő eszközzel.
A csomag Dataverse-példányba való központi telepítése előtt, során vagy után futtatható egyedi kódok.
A csomagra jellemző HTML-tartalom, amely a központi telepítési folyamat elején és végén jelenhet meg. Ez egy hasznos tartalom a csomagban telepített megoldások és fájlok leírására.

Feljegyzés

Van egy másik csomagtípus is, úgynevezett beépülő modul. Az ilyen csomag beépülő moduloktól függő szerelvények számára van, és nincs kapcsolata a Package Deployer-csomagokkal.

Előfeltételek

Ügyeljen arra, hogy minden olyan megoldást és fájlt készítsen elő, amelyet fel szeretne venni a csomagba.
Visual Studio 2019 vagy újabb, vagy Visual Studio Kód.

Folyamat áttekintése

Csomag létrehozásához Package Deployer hajtsa végre a következő lépéseket.

Visual Studio vagy MSBuild projekt létrehozása
Megoldások és egyéb fájlok hozzáadása a projekthez
Html-fájlok frissítése (nem kötelező)
A csomag konfigurációs értékeinek megadása
Egyéni kód definiálása a csomaghoz
A csomag összeállítása és telepítése

Ezeket a lépéseket részletesen ebben a cikkben ismertetjük.

Csomagprojekt létrehozása

Az első lépés egy Visual Studio vagy egy MSBuild projekt létrehozása a csomaghoz. Ennek éhez telepítenie kell a fejlesztési számítógépre a két használható eszközbővítmény közül az egyiket. A Visual Studio Kód használata esetén telepítse a Microsoft Power Platform CLI programot. Ellenkező esetben, ha 2019-es vagy újabb verziót használ Visual Studio , telepítse Power Platform az eszközöket Visual Studio.

Az alábbi megfelelő lap kiválasztásával ismerje meg, hogyan hozhat létre projektet a kívánt eszközbővítmény használatával. Mindkét eszköznek hasonló a projekformátum-kimenete.

Power Platform CLI
Power Platform eszközök

Az eredeti csomag létrehozásához futtassa a pac package init parancsot. További információ: pac csomag

pac package init help
pac package init --outputDirectory DeploymentPackage

Az eredményül kapott CLI kimenet az alábbiakban látható mappákat és fájlokat tartalmazza. Az itt használt példa a "DeploymentPackage" mappa neve.

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

A létrehozott projektben keresse meg a ImportConfig.xml konfigurációs fájlt a PkgAssets mappában és a PackageImportExtension.cs fájlt. Ezeket a fájlokat a cikk későbbi részében leírtak szerint fogja módosítani.

Létrehozhat egy Visual Studio projektet a Power Platform Megoldássablon használatával, majd később hozzáadhat egy csomagprojektet a Power Platform Package Deployment Project sablonnal, vagy létrehozhat egy projektet közvetlenül a Power Platform Package Deployment Project sablonnal.

Csomagprojekt hozzáadása.

Feljegyzés

Ne válassza a Csomag sablont Power Platform . Ez a sablon beépülő modulokhoz használható.

Az eredményül kapott Visual Studio megoldás és projekt az alábbiakban látható mappákat és fájlokat tartalmazza. Az itt használt példa a "Deployment-package" név. A Content mappa tartalma itt nem jelenik meg a rövidség kedvéért.

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

A létrehozott projektben keresse meg a ImportConfig.xml konfigurációs fájlt a PkgFolder mappában és a PackageTemplate.cs fájlban. Ezeket a fájlokat a cikk későbbi részében leírtak szerint fogja módosítani.

További információk az Power Platform-eszközök bővítmény használatával kapcsolatban: Gyorsindítás: Power Platform-eszközök projekt létrehozása

Új csomagfájl

A csomag projekt létrehozása után elkezdhet megoldásokat és egyéb fájlokat hozzáadni a projekthez.

Power Platform CLI
Power Platform eszközök

A CLI használata során külső csomagokat, megoldásokat és hivatkozásokat adhat hozzá a csomag projektjéhez az egyik alparancs segítségével. Az alparancsok listájához adja meg a következőt: pac package help. Adjuk hozzá a megoldást a csomagunkhoz.

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

A Megoldástallózó panelen adja hozzá a PkgFolder mappa alá a Dataverse-megoldásokat és a fájlokat. A HTML-fájlok a Tartalom mappába tartoznak. Erről a HTML-tartalomról bővebben később lesz szó.
Az összes Tulajdonságok panelben megadott fájl esetén állítsa a Kimeneti könyvtárba másolás értékét Mindig másolja lehetőségre. Ezen érték beállítása biztosítja, hogy a hozzáadott fájljai elérhetők legyenek a létrehozott csomagban.

Következő lépésként frissítse a HTML-nyelvhez megfelelő fájlokat.

A Megoldástallózó panelen bontsa ki a PkgFolder>Tartalom>en-us pontot. Keressen két és EndHTML nevű WelcomeHTMLmappát. Ezek a mappák tartalmazzák az olyan HTML-fájlokat és társított fájlokat, amelyek lehetővé teszik, hogy a csomag központi telepítési folyamatának végén és elején információkat lehessen megjeleníteni (a felhasználónak). Ha megjelenítendő információkat szeretne hozzáadni a csomaghoz, módosítsa az ezen mappák HTML mappájában lévő fájlokat.
A csomagban lévő HTML-fájlokat más nyelveken is felveheti, így a HTML-tartalom a felhasználó számítógépének nyelvi beállításainak megfelelő nyelven jelenik meg. Ehhez szükséges:
1. Hozzon létre egy másolatot az en-us mappáról a PkgFolder>Tartalom részen.
2. Nevezze át az átmásolt mappát a megfelelő nyelvre. A spanyol nyelv esetén például nevezze át es-ES-re.
3. Módosítsa a HTML-fájlok tartalmát a spanyol tartalom hozzáadásához.

A csomag konfigurálása

Adja meg a csomag konfigurációját a csomagra vonatkozó információk ImportConfig. xml fájlhoz való hozzáadásával a projektben. Tekintse meg az ImportConfig referenciát a használandó érvényes elemek és attribútumok példájáért és leírásáért.

Egyéni kód hozzáadása

A csomag környezetbe importálása előtt, közben és után végrehajtható egyéni kódot is hozzáadhat. Ehhez tegye a következők lépéseket.

Módosítsa a PackageTemplate.cs (vagy PackageImportExtension.cs) fájlt a projekt gyökérmappjában.

Az C# fájlban a következőket teheti:

Egyéni végrehajtandó kódot adhat meg, amelyet akkor kell végrehajtani, amikor a rendszer inicializálja a csomagot az InitializeCustomExtension felülbírálási metódusának definíciójában.

Ezzel a metódussal engedélyezheti, hogy a felhasználók a futásidejű paramétereket használják a csomag futtatásakor. Fejlesztőként a RuntimeSettings tulajdonsággal támogathatja bármelyik futásidejű paramétert a csomaghoz, ha rendelkezik megfelelő kóddal, hogy feldolgozza a paramétert a felhasználói bevitel alapján.

A következő mintakód például a két lehetséges értékkel (true vagy false) rendelkező SkipChecks futásidejű paramétert engedélyezi a csomaghoz. A mintakód ellenőrzi, hogy a felhasználó adott-e meg futásidejű paramétereket a Package Deployer (parancssorból vagy PowerShell használatával történő) futtatásakor, és ennek megfelelően dolgozza fel az információkat. Ha a csomag futtatásakor a felhasználó nem ad meg futásidejű paramétert, a RuntimeSettings tulajdonság értéke null lesz.
```
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");  
}  
```
Ez a kód lehetővé teszi, hogy a rendszergazda a parancssorból vagy az Import-CrmPackage parancsmaggal megadja, hogy ki kell-e hagyni a biztonsági ellenőrzéseket a csomag Package Deployer eszközzel történő importálásakor. További információ: Csomagok központi telepítése a Package Deployer és a Windows PowerShell használatával.
Adja meg azt az egyéni kódot, amelyet végre kell hajtani, mielőtt a megoldásokat importálná a PreSolutionImport felülbírálási metódusának definíciójába ahhoz, hogy meghatározza, hogy a testreszabásokat meg kell-e tartani, vagy felül kell-e bírálni a cél Dataverse-példány adott megoldásának frissítésekor, illetve hogy automatikusan aktiválni kell-e a beépülő modulokat és a munkafolyamatokat.

A felülbírálási metódus definíciójának RunSolutionUpgradeMigrationStep használata adatátalakítás vagy frissítés végrehajtásához egy megoldás két verziója között Ezt a metódust csak akkor hívja meg a rendszer, ha az importált megoldás már jelen van a célpéldányban Dataverse .

Ez a függvény a következő paramétereket várja:

Paraméter	Ismertetés
`solutionName`	A megoldás neve
`oldVersion`	A régi megoldás verziószáma
`newVersion`	Az új megoldás verziószáma
`oldSolutionId`	A régi megoldás GUID azonosítója.
`newSolutionId`	Az új megoldás GUID azonosítója.

A BeforeImportStage metódus felülbírálási definíciójában egyéni végrehajtandó kódot adhat meg, amelynek a végrehajtására a megoldás importálásának befejeződése előtt kerül sor. Mielőtt a megoldás importálása befejeződik, a rendszer importálja az ImportConfig.xml fájlban meghatározott megoldásokban szereplő mintaadatokat és néhány bennük szereplő egybesimított fájlt.
Bírálja felül a konfigurációs adatok importálásához aktuálisan kiválasztott nyelvet a felülbírálási metódus definíciójával OverrideConfigurationDataFileLanguage. Ha a megadott nyelv megadott területibeállítás-azonosítója (LCID) nem található a csomagban elérhető nyelvek listájában, a rendszer importálja az alapértelmezett adatfájlt.

A konfigurációs adatokhoz rendelkezésre álló nyelveket a <cmtdatafiles> csomópontban, az ImportConfig.xml fájlban adhatja meg. A konfigurációs adatok alapértelmezett importálási fájlja az ImportConfig.xml fájlban található crmmigdataimportfile attribútumban van megadva.

Az adatellenőrzések kihagyása (OverrideDataImportSafetyChecks = igaz) itt akkor lehet hatékony, ha biztos abban, hogy a célpéldány Dataverse nem tartalmaz adatokat.
Az AfterPrimaryImport> metódus felülbíráló definíciójában egyéni kódot adhat meg, amelyet az importálás befejezése után kell végrehajtani. A fennmaradó egyszerű fájlok, amelyeket korábban nem importáltak a megoldás importálásának megkezdése előtt, most importálódnak.

Módosítsa a csomag mappájának alapértelmezett nevét a kívánt csomagnévre. Ehhez nevezze át a PkgFolder (vagy Pkg) mappát a Megoldástallózó paneljén, és szerkessze a visszatérési értéket a GetImportPackageDataFolderName tulajdonságnál.

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

Módosítsa a csomag nevét a visszatérési érték GetNameOfImport tulajdonságnál történő módosításával.
```
public override string GetNameOfImport(bool plural)  
{  
return "Package Short Name";  
}  
```
Ez a visszaadott érték a csomag neve, amely megjelenik a Dynamics 365 Package Deployer varázsló csomagválasztó oldalán.
Módosítsa a csomag leírását a visszatérési érték GetImportPackageDescriptionText tulajdonságnál történő módosításával.
```
public override string GetImportPackageDescriptionText  
{  
get { return "Package Description"; }  
}  
```
Ez a visszaadott érték a csomag leírása, amely a varázsló csomagkiválasztási lapján a csomag neve mellett jelenik meg Package Deployer .
Módosítsa a csomag hosszú nevét a visszatérési érték GetLongNameOfImport tulajdonságnál történő módosításával.
```
public override string GetLongNameOfImport  
{  
get { return "Package Long Name"; }  
}  
```
A csomag hosszú neve a telepítendő csomag kiválasztása után következő oldalon látható.

Emellett a következő függvény és változók is használhatók a csomaghoz:

Név szerint	Típus szerint	Ismertetés
CreateProgressItem(String)	Function	Új folyamatban lévő elem felhasználói felületen (UI) történő létrehozására használható.
RaiseUpdateEvent(String, ProgressPanelItemStatus)	Function	A hívás által létrehozott folyamatot a következőre frissíti: CreateProgressItem(String). A ProgressPanelItemStatus a következő értékekkel rendelkező felsorolás: Működik = 0 Befejeződött = 1 Sikertelen = 2 Figyelmeztetés = 3 Ismeretlen = 4
RaiseFailEvent(String, Exception)	Function	Az aktuális állapot importálásának sikertelenségét okozza, kivételről tájékoztató üzenettel.
IsRoleAssoicatedWithTeam(Guid, Guid)	Function	Annak megállapítására szolgál, hogy egy szerepkört egy adott csoporthoz társítottak-e.
IsWorkflowActive(Guid)	Function	Annak megállapítására használható, hogy egy adott munkafolyamat aktív-e.
PackageLog	Osztály mutatója	Egy mutató, amely a csomag inicializált naplózási felületére mutat. Ezt az interfészt egy csomag használja a csomag naplófájljában lévő üzenetek és kivételek naplózására.
RootControlDispatcher	Tulajdonság	Egy továbbító felület, amely lehetővé teszi, hogy a vezérlő renderelje a saját kezelőfelületét a csomag központi telepítése során. Ezzel az interfésszel bármilyen felhasználói felületi elemet vagy parancsot becsomagolhat. Fontos, hogy használat előtt ellenőrizze a változó null értékeit, mivel előfordulhat, hogy nincs értékre állítva.
CrmSvc	Tulajdonság	Egy olyan mutató, amely a CrmServiceClient osztályra mutat, és lehetővé teszi, hogy egy csomag megcímezze a Dynamics 365-öt a csomagon belül. A mutató használatával SDK-metódusokat és egyéb műveleteket hajthat végre a felülbírált metódusokban.
DataImportBypass	Tulajdonság	Ezzel meghatározhatja, hogy a Dynamics 365 Package Deployer átugorja-e az összes adatimportálási műveletet (például a Dataverse mintaadatainak, az egybesimított fájl adatainak vagy a Konfigurációáttelepítő eszközből exportált adatok importálását). True vagy false értéket kell megadni. Az alapértelmezett a `false`.
OverrideDataImportSafetyChecks	Tulajdonság	Adja meg, hogy a Dynamics 365 Package Deployer megkerül-e néhány biztonsági ellenőrzést, ami segít javítani az importálási teljesítményt. A `true` vagy a `false` értéket adja meg. Az alapértelmezett a `false`. Ezt a tulajdonságot csak akkor állítsa be, `true` ha a célpéldány Dataverse nem tartalmaz adatokat.

Mentse a projektet. A következő lépés a csomag buildelése.

Buildelés és üzembe helyezés

A következő szakaszok a csomagok összeállítását és központi telepítését ismertetik.

Buildelés

A csomag felépítését az alábbiakban ismertetjük, attól függően, hogy melyik eszközt használja.

Power Platform CLI
Power Platform eszközök

A CLI-vel létrehozott csomag létrehozásához betöltheti a .csproj fájlt Visual Studio, de ehelyett a dotnet parancsot és az MSBuild parancsot fogjuk használni. Az alábbi példa feltételezi, hogy a működő könyvtár tartalmazza a *.csproj fájlt.

> dotnet publish

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

Nem kötelezően meg is használhatja a felépített csomag részleteit.

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

A csomag a következő fájlokat tartalmazza a <Project>\Bin\Debug mappában.

<PackageName> mappa: A mappa neve megegyezik azzal, amelyet a csomag mappájának nevéhez lépés szakasz 2.g részében módosított. Egyéni kód hozzáadása. Ez a mappa tartalmazza a csomag megoldásait, konfigurációs adatait, egybesimított fájljait és tartalmát.

Feljegyzés

Előfordulhat, hogy egy .NET mappát (pl. net472) lát, amely egypublish mappát tartalmaz. A DLL-fájlja és az egyéb projektfájlok abban a nyilvános mappában vannak.

<PackageName>.dll: A szerelvény tartalmazza a csomag egyéni kódját. Alapértelmezés szerint a szerelvény neve megegyezik projektjének nevével.

Üzembe helyezés

A csomag létrehozását követően elvégezheti a csomag központi telepítését a Dataverse-példányon a Package Deployer vagy a Windows PowerShell vagy a parancssori felületi parancs eszközzel.

A Package Deployer eszköz használatának telepítéséhez először töltse le az eszközt a Dataverse fejlesztési eszközökben leírtak szerint. Ezután kövesse a csomagok központi telepítésével kapcsolatos részletes információkat a Csomagok központi telepítése a Windows PowerShell Package Deployer használatával vagy használatával.
A parancssori felület használatával való telepítéshez használja a pac package deploy parancsot.
```
> pac package deploy --package .\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip
```
Feljegyzés

Ha a parancssori felület használatával telepít egy csomagot egy célkörnyezetben, először be kell állítania egy hitelesítési profilt, és ki kell választania egy szervezetet. További információ: pac auth létrehozás, pac org kiválasztás

Ajánlott eljárások

Az alábbiakban néhány gyakorlati tanács található a Package Deployer csomagok használatához.