Креирање пакета за алатку 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 КСНУМКС или касније, инсталирајте Power Platform алате за Visual Studio.

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

Power Platform ЦЛИ
Power Platform Алатке

Покрените команду 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 ЦЛИ
Power Platform Алатке

Када користите 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 ЦЛИ
Power Platform Алатке

Да бисте изградили пакет креиран помоћу ЦЛИ-а, можете учитати .цспрој датотеку 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.

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

Белешка

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

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

Примена

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

Да бисте је применили помоћу алатке Package Deployer, прво преузмите алатку као што је описано у Dataverse алаткама за развој. Затим пратите детаљне информације о распоређивању пакета у чланку Деплои пакете користећи Package Deployer или Виндовс ПоверСхелл.
Да бисте је применили помоћу 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 пакетима.