Креирање пакета за алатку Package Deployer

Чланак
06/26/2024

Package Deployer омогућава администраторима примену пакета на инстанцама услуге Microsoft Dataverse. Package Deployer пакет може да се састоји од било чега следећег:

Једна или више датотека Dataverse решења.
Просте датотеке или извезена датотека конфигурације из алатке Миграција конфигурације. За више информација о алатки, погледајте чланак Премештање података о конфигурацији између инстанци и организација помоћу алатке Миграција конфигурације.
Прилагођени кôд који може да се покреће пре, током или после примене пакета у Dataverse инстанци.
HTML садржај карактеристичан за пакет који може бити приказан на почетку и на крају процеса примене. Овај садржај може бити користан за пружање описа решења и датотека примењених у пакету.

Белешка

Постоји још један тип пакета који се зове пакет додатних компоненти. Таква врста пакета је за зависне склопове додатних компоненти и нема никакав однос са Package Deployer пакетима.

Предуслови

Проверите да ли сте спремили сва решења и друге датотеке које желите да укључите у пакет.
Visual Studio 2019 . или касније, или Visual Studio Шифра.

Преглед процеса

Да бисте креирали Package Deployer пакет, извршите следеће кораке.

Креирајте Visual Studio или MSBuild пројекат
Додајте решење и друге датотеке пројекту
Ажурирајте обезбеђене HTML датотеке (опционално)
Наведите вредности конфигурације за пакет
Дефинишите прилагођени кôд за пакет
Израдите и примените пакет

Ови кораци су детаљно описани у овом чланку.

Креирајте пројекат за пакет

Први корак је креирање Visual Studio или MSBuild пројекта за пакет. Да бисте то урадили, на развојном рачунару морате имати инсталирано једно од два доступна проширења алатке. Ако користите Visual Studio Code, инсталирајте Microsoft Power Platform CLI. У супротном, ако користите Visual Studio 2019 или новију, инсталирајте Power Platform алатке за Visual Studio.

Изаберите одговарајућу картицу испод да бисте сазнали како да креирате пројекат користећи жељено проширење алатке. Обе алатке излазе из пројекта у сличном формату.

Power Platform CLI
Power Platform Tools

Покрените команду pac package init да бисте креирали почетни пакет. Још информација: pac package

pac package init help
pac package init --outputDirectory DeploymentPackage

Резултујући CLI излаз садржи фасцикле и датотеке приказане испод. Назив фасцикле „DeploymentPackage“ је овде коришћен као пример.

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

У креираном пројекту пронађите датотеку за ИмпортЦонфиг.xмл у фасцикли ПкгАссетс и датотеци #пии_ијфидејз уређаја. Изменићете ове датотеке као што је описано у овом чланку.

Пројекат можете да креирате Visual Studio помоћу предлошка Power Platform решења, а касније да додате пакет пројекат помоћу Power Platform предлошка пројекта примене пакета или да креирате пројекат директно помоћу предлошка Power Platform пројекта распоређивања пакета.

Додајте пакет пројекат.

Белешка

Немојте бирати предложак Power Platform пакета. Тај предложак је за пакете додатних компоненти.

Резултујуће Visual Studio решење и пројекат садржи фасцикле и датотеке приказане у наставку. Назив фасцикле „Deployment-package“ је овде коришћен као пример. Садржај фасцикле "Садржај" није приказан овде због бревитације.

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

У креираном пројекту пронађите датотеку за ИмпортЦонфиг.xмл у фасцикли ПкгФолдер и у датотеци #пии_ијфидеаз уређаја. Изменићете ове датотеке као што је описано у овом чланку.

Више информација о коришћењу проширења Power Platform Tools: Брзи старт: Креирање пројекта Power Platform Tools

Додајте датотеке пакета

Када креирате пројекат пакета, можете почети да додајете решења и друге датотеке том пројекту.

Power Platform CLI
Power Platform Tools

Када користите CLI, можете да додате спољне пакете, решења и референце на пројекат пакета помоћу једне од поткоманди add. Унесите pac package help да бисте видели листу поткоманди. Хајде да додамо решење у наш пакет.

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

У окну Истраживач решења, додајте своја Dataverse решења и друге датотеке испод фасцикле PkgFolder. HTML датотекама је место у фасцикли Садржај. Више о овом HTML садржају касније.
За сваку датотеку коју додате у фасциклу Својства, подесите вредност Копирај у излазни директоријум на Копирај увек. Подешавање ове вредности обезбеђује да датотека коју сте додали буде доступна у генерисаном пакету.

Затим ажурирајте датотеке специфичне за HTML језик.

У окну истраживача решења, проширите PkgFolder>Садржај>en-us. Пронађите две фасцикле које се зову EndHTML и WelcomeHTML. Те фасцикле садрже HTML и придружене датотеке које вам омогућавају да прикажете информације (кориснику) на крају и на почетку процеса примене пакета. Уредите датотеке у HTML фасцикли ових фасцикли да бисте додали информације у приказ за свој пакет.
Такође можете додати HTML датотеке у вашем пакету на другим језицима тако да се садржај у HTML-у приказује на језику заснованом на поставкама локалног стандарда рачунара корисника. Да бисте то урадили:
1. Креирајте копију фасцикле en-us у фасцикли PkgFolder>Садржај.
2. Преименујте копирану фасциклу у одговарајући језик. На пример, за шпански језик преименујте фасциклу у es-ES.
3. Измените садржај HTML датотека тако да додате садржај на шпанском.

Конфигуришите пакет

Дефинишите конфигурацију пакета додавањем информација о вашем пакету у датотеци ImportConfig.xml у пројекту. Погледајте референцу "ИмпортЦонфиг " за пример и описе важећих елемената и атрибута које треба користити.

Додајте прилагођени кôд

Можете да додате прилагођени кôд који се извршава пре, током и након увоза пакета у окружење. Да бисте то урадили, следите следећа упутства.

Уредите датотеку PackageTemplate.cs (или PackageImportExtension.cs) у основној фасцикли пројекта.

У C# датотеци можете да урадите следеће:

Унесите прилагођени кôд који ће се извршити када се пакет покрене дефиницији метода за измену InitializeCustomExtension.

Ова метода се може користити за омогућавање корисницима да користе параметре извођења током извођења пакета. Као програмер, можете у свој пакет додати подршку за било који параметар извршавања користећи својство RuntimeSettings док год имате кôд за обраду на основу корисничког уноса.

На пример, следећи пример кода омогућава параметар извођења који се зове SkipChecks за пакет који има две могуће вредности: true или false. Пример кода проверава да ли је корисник навео било какве параметре извођења током извођења алатке Package Deployer (било коришћењем командне линије или платформе PowerShell), а затим у складу с тим обрађује информације. Ако корисник током извођења пакета не наведе ниједан параметар извођења, својство RuntimeSettings ће бити без вредности.
```
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");  
}  
```
Овај кôд омогућава администратору да користи командну линију или cmdlet команду Import-CrmPackage да одреди да ли да прескочи безбедносне провере током покретања алатке Package Deployer за увоз пакета. Још информација: Примена пакета коришћењем алатке Package Deployer и платформе Windows PowerShell
Унесите прилагођени кôд који треба извршити пре увоза решења у дефиницији замене методе PreSolutionImport да бисте одредили да ли треба да одржавају или замене прилагођавања током ажурирања наведеног решења у циљној Dataverse инстанци и да ли треба аутоматски активирати додатне компоненте и токове посла.

Користите дефиницију метода замене да бисте RunSolutionUpgradeMigrationStep извршили трансформацију података или надоградњу између две верзије решења Овај метод је позван само ако је решење које увозите већ присутно у циљној Dataverse инстанци.

Ова функција очекује следеће параметре:

Параметар	Опис
`solutionName`	Назив решења
`oldVersion`	Број верзије старог решења
`newVersion`	Број верзије новог решења
`oldSolutionId`	GUID старог решења.
`newSolutionId`	GUID новог решења.

Унесите прилагођени кôд који ће се извршити пре него што се доврши увоз решења у дефиницији замене методе BeforeImportStage. Подаци примера и неке просте датотеке за решења наведена у датотеци ImportConfig.xml се увозе пре него што се увоз решења доврши.
Замените тренутно изабрани језик за увоз података за конфигурацију користећи дефиницију метода замене OverrideConfigurationDataFileLanguage. Ако наведени ИД локалног стандарда (ЛЦИД) наведеног језика није пронађен на листи доступних језика у пакету, подразумевана датотека са подацима се увози.

Можете навести доступне језике за податке конфигурације у чвору <cmtdatafiles> у датотеци ImportConfig.xml. Подразумевана датотека за увоз података конфигурације наведена је у атрибуту crmmigdataimportfile у датотеци ImportConfig.xml.

Прескакање провере података ( OverrideDataImportSafetyChecks = тачно) може бити ефикасно овде ако сте сигурни да Dataverse циљна инстанца не садржи податке.
Унесите прилагођени кôд који ће се извршити након што се доврши увоз решења у дефиницији замене методе AfterPrimaryImport>. Преостале равне датотеке које раније нису увезене, пре него што је започет увоз решења, сада се увозе.
Промените подразумевани назив фасцикле пакета у назив пакета који желите. Да бисте то учинили, преименујте фасциклу PkgFolder(или PkgAssets) у окну Истраживач решења, а затим измените повратну вредност испод својства 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";  
}  
}  
```
Промените име пакета тако што ћете уредити повратну вредност испод својства GetNameOfImport.
```
public override string GetNameOfImport(bool plural)  
{  
return "Package Short Name";  
}  
```
Ова враћена вредност је име пакета који се појављује на страници за избор пакета у чаробњаку за Дyнамицс 365 Package Deployer .
Промените опис пакета тако што ћете уредити повратну вредност испод својства GetImportPackageDescriptionText.
```
public override string GetImportPackageDescriptionText  
{  
get { return "Package Description"; }  
}  
```
Ова враћена вредност је опис пакета који се појављује заједно са именом пакета на страници за избор пакета у чаробњаку Package Deployer .
Промените дуги назив пакета тако што ћете уредити повратну вредност испод својства GetLongNameOfImport.
```
public override string GetLongNameOfImport  
{  
get { return "Package Long Name"; }  
}  
```
Дуги назив пакета се приказује на следећој страници након што сте изабрали пакет за инсталацију.

Поред тога, у пакету су доступне следеће функције и променљиве:

Назив	Тип	Опис
CreateProgressItem(String)	Function	Користи се за креирање нове ставке напретка у корисничком интерфејсу (UI).
RaiseUpdateEvent(String, ProgressPanelItemStatus)	Function	Користи се за ажурирање напретка креираног позивом CreateProgressItem(String). ProgressPanelItemStatus је нумеричка вредност са следећим вредностима: Working = 0 Complete = 1 Failed = 2 Warning = 3 Unknown = 4
RaiseFailEvent(String, Exception)	Function	Користи се за неуспех увоза тренутног статуса са поруком о изузимању.
IsRoleAssoicatedWithTeam(Guid, Guid)	Function	Користи се за утврђивање да ли је улога повезана са одређеним тимом.
IsWorkflowActive(Guid)	Function	Користи се за утврђивање да ли је одређени ток посла активан.
PackageLog	Показивач класе	Показивач на покренути интерфејс за евидентирање пакета. Овај интерфејс се користи у пакету за евидентирање порука и изузетака у датотеци евиденције пакета.
RootControlDispatcher	Својство	Ово је интерфејс за диспечера који се користи како би контрола могла да прикаже сопствени кориснички интерфејс током примене пакета. Користите овај интерфејс да обухватите све елементе или команде корисничког интерфејса. Важно је да проверите да ли у овој променљивој има вредности "нулл" пре него што је употребите јер можда није постављена на вредност.
CrmSvc	Својство	Показивач на класу CrmServiceClient која омогућава пакету да се обраћа систему Dynamics 365 из пакета. Користите овај показивач за извршавање SDK метода и других радњи у замењеним методама.
DataImportBypass	Својство	Наведите да ли Dynamics 365 Package Deployer прескаче све операције увоза података, као што је увоз Dataverse пробних података, података простих датотека и података извезених из алатке Миграција конфигурације. Наведите „true“ или „false“. Подразумевано је `false`.
OverrideDataImportSafetyChecks	Својство	Наведите да ли Дyнамицс 365 Package Deployer заобилази неке од својих безбедносних провера, што помаже у побољшању перформанси увоза. Наведите `true` или `false`. Подразумевано је `false`. Ово својство би требало да поставите `true` само ако циљна Dataverse инстанца не садржи податке.

Сачувајте пројекат. Следећи корак је да изградите пакет.

Изградите и примените

Следећи одељци описују како се прави и примењује пакет.

Прављење

Израда пакета је описана испод у зависности од алатке коју користите.

Power Platform CLI
Power Platform Tools

Да бисте направили пакет креиран помоћу ЦЛИ-ја, можете да учитате .цспрој датотеку Visual Studio у, али уместо тога користићемо команду дотнет и МСБуилд. Пример у наставку претпоставља да радни директоријум садржи датотеку *.csproj.

> dotnet publish

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

Опционално можете погледати детаље изграђеног пакета.

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

Пакет сачињавају следеће датотеке испод фасцикле <Project>\Bin\Debug.

<Фасцикла ПацкагеНаме >: Име фасцикле је исто као и оно које сте променили за име фасцикле пакета у корак 2.г овог одељка Додајте прилагођени кôд. Ова фасцикла садржи сва решења, податке конфигурације, просте датотеке и садржај пакета.

Белешка

Можда ћете видети фасциклу .NET (нпр. net472) која садржи фасциклу pdpublish. DLL и друге датотеке пројекта се налазе у фасцикли pdpublish.

<PackageName>.dll: Склоп садржи прилагођени кôд за ваш пакет. Назив склопа је подразумевано исти као и назив вашег пројекта.

Примена

Када креирате пакет, можете га применити на Dataverse инстанцу користећи алатку Package Deployer, Windows PowerShell или CLI команду.

Да бисте је применили помоћу алатке Package Deployer, прво преузмите алатку као што је описано у Dataverse алаткама за развој. Затим следите детаљне информације о примени пакета у пакетима за примену чланка помоћу Package Deployer или Wиндоwс ПоwерСхелл пакета.
Да бисте је применили помоћу CLI ,користите команду pac package deploy.
```
> pac package deploy --package .\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip
```
Белешка

Да бисте применили пакет у циљно окружење помоћу CLI, прво морате да подесите профил потврде идентитета и изаберете организацију. Још информација: pac auth create, pac org select

Најбољи примери из праксе

У наставку је наведено неколико најбољих савета за вежбање које треба следити приликом рада са Package Deployer пакетима.