Споделяне чрез

Създайте пакети за инструмента Package Deployer

  • Статия

Package Deployer позволява на администраторите да разполагат пакети екземпляри на Microsoft Dataverse. Един пакет на Package Deployer може да се състои от някои или всички от следните неща:

  • Един или повече файлове на Dataverse решение.
  • Фиксирани файлове или файлове с конфигурационни данни от Configuration Migration Tool. За повече информация за инструмента вижте Преместване на конфигурационни данни между екземпляри и организации с Configuration Migration Tool.
  • Потребителски код, който може да работи преди, по време или след внедряването на пакет в екземпляр на 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.

Изберете съответния раздел по-долу, за да разберете как да създадете проект с помощта на желаното разширение на инструмента. И двата инструмента извеждат проекта в подобен формат.

Изпълнете командата 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

В създадения проект намерете конфигурационния файл ImportConfig.xml в папката PkgAssets и файла PackageImportExtension.cs. Ще промените тези файлове, както е описано по-нататък в тази статия.

Добавяне на пакетни файлове

След като сте създали пакетен проект, можете да започнете да добавяте решения и други файлове към този проект.

Когато използвате 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.

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

Определете конфигурацията на пакета, като добавите информация за вашия пакет в ImportConfig.xml файла в проекта. Вижте Справка за ImportConfig за пример и описания на валидните елементи и атрибути, които да използвате.

Добавяне на персонализиран код

Можете да добавите персонализиран код, който се изпълнява преди, по време и след като пакетът бъде импортиран в среда. За да го направите, следвайте следните инструкции.

  1. Редактирайте файла PackageTemplate.cs (или PackageImportExtension.cs) в основната папка на проекта.

  2. Във файла на C# можете да:

    1. Въведете персонализиран код, който да се изпълни, когато пакетът се инициализира в дефиницията на метода за отмяна на InitializeCustomExtension.

      Този метод може да се използва, за да позволи на потребителите да използват параметрите на изпълнение, докато изпълняват пакет. Като програмист можете да добавите поддръжка за всеки параметър на изпълнение към вашия пакет, като използвате RuntimeSettings свойство, стига да имате код, за да го обработвате въз основа на въвеждането на потребителя.

      Например, следният примерен код активира параметър за изпълнение, наречен SkipChecks за пакета, който има две възможни стойности: вярна или невярна. Примерният код проверява дали потребителят е посочил параметри на изпълнение по време на работа 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");  
}

      Този код позволява на администратора да използва командния ред или Import-CrmPackage командлет, за да посочите дали да пропуснете проверките за безопасност, докато стартирате инструмента Package Deployer за импортиране на пакета. Повече информация: Внедряване на пакети с помощта на Package Deployer и Windows PowerShell

    2. Въведете персонализиран код, който да се изпълни преди да бъдат импортирани решенията в дефиницията на метода на отмяна на PreSolutionImport, за да зададете дали да поддържате или презаписвате персонализиране, докато актуализирате определеното решение в цел Dataverse например и дали автоматично да активирате приставки и работни процеси.

    3. Използване на дефиницията на метода за отмяна за RunSolutionUpgradeMigrationStep извършване на трансформация на данни или надстройка между две версии на решение Този метод се извиква само ако решението, което импортирате, вече присъства в целевия Dataverse екземпляр.

      Тази функция очаква следните параметри:

      Параметър Описание
      solutionName Име на решението
      oldVersion Номер на версията на старото решение
      newVersion Номер на версията на новото решение
      oldSolutionId GUID на старото решение.
      newSolutionId GUID на новото решение.

    4. Въведете персонализиран код за изпълнение, преди завършването на импортирането на решението в дефиницията за отмяна на модела на BeforeImportStage. Примерни данни и някои плоски файлове за решения, посочени във файл ImportConfig.xml, се импортират, преди да завърши импортирането на решение.

    5. Заместете текущо избрания език за импортиране на конфигурационни данни, като използвате дефиницията на метода за отмяна. OverrideConfigurationDataFileLanguage Ако посоченият ИД на езикова променлива (LCID) на посочения език не бъде намерен в списъка с налични езици в пакета, файлът с данни по подразбиране се импортира.

      Вие посочвате наличните езици за конфигурационните данни в <cmtdatafiles> възел в ImportConfig.xml файл. Файлът за импортиране на данни по подразбиране е посочен в crmmigdataimportfile атрибут в ImportConfig.xml файл.

      Пропускането на проверки на данни (OverrideDataImportSafetyChecks = true) може да бъде ефективно тук, ако сте сигурни, че целевият Dataverse екземпляр не съдържа никакви данни.

    6. Въведете персонализиран код за изпълнение, след завършването на импортирането в дефиницията за отмяна на метода AfterPrimaryImport>. Останалите плоски файлове, които не са били импортирани по-рано, преди да започне импортирането на решението, се импортират сега.

    7. Променете името по подразбиране на папката на вашия пакет на името на пакета, което искате. За да направите това, преименувайте папката PkgFolder (или PkgAssets) в прозореца на Solution Explorer и след това редактирайте стойността за връщане в свойството 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";  
}  
}

    8. Променете името на пакета, като редактирате стойността за връщане под свойството GetNameOfImport.

      public override string GetNameOfImport(bool plural)  
{  
return "Package Short Name";  
}

      Тази върната стойност е името на вашия пакет, което се показва на страницата за избор на пакет в съветника на Dynamics 365 Package Deployer .

    9. Променете описанието на пакета, като редактирате стойността за връщане под свойството GetImportPackageDescriptionText.

      
public override string GetImportPackageDescriptionText  
{  
get { return "Package Description"; }  
}

      Тази върната стойност е описанието на пакета, което се показва до името на пакета на страницата за избор на пакет в Package Deployer съветника.

    10. Променете дългото име на пакета, като редактирате стойността за връщане под свойството GetLongNameOfImport.

      
public override string GetLongNameOfImport  
{  
get { return "Package Long Name"; }  
}

      Дългото име на пакета се появява на следващата страница, след като сте избрали пакета за инсталиране.

  3. Освен това в пакета са достъпни следните функции и променливи:

    Име Тип Описание
    CreateProgressItem(String) Function Използва се за създаване на нов елемент на прогрес в потребителския интерфейс (UI).
    RaiseUpdateEvent(String, ProgressPanelItemStatus) Function Използва се за актуализиране на напредъка, създаден от повикването до CreateProgressItem(String).

    ProgressPanelItemStatus е изброяване със следните стойности:

    Работи = 0
    Завършено = 1
    Неуспешно = 2
    Предупреждение = 3
    Неизвестно = 4
    RaiseFailEvent(String, Exception) Function Използва се за неуспех на импортирането на текущо състояние с съобщение за изключение.
    IsRoleAssoicatedWithTeam(Guid, Guid) Function Използва се за определяне дали роля е свързана с определен отбор.
    IsWorkflowActive(Guid) Function Използва се за определяне дали активен е определен работен процес.
    PackageLog Класови указател Указател към инициализирания интерфейс за регистриране на пакета. Този интерфейс се използва от пакет за регистриране на съобщения и изключения от файла на дневника на пакета.
    RootControlDispatcher Свойство Диспечерски интерфейс, използван, за да позволи на вашия контрол да предостави собствен потребителски интерфейс по време на разгръщане на пакета. Използвайте този интерфейс, за да увиете всички UI елементи или команди. Важно е да проверите тази променлива за нулеви стойности, преди да я използвате, тъй като може да не е зададена на стойност.
    CrmSvc Свойство Показалец към CrmServiceClient клас, който позволява на пакет да адресира Dynamics 365 отвътре в пакета. Използвайте този показалец, за да изпълните SDK методи и други действия в презаписаните методи.
    DataImportBypass Свойство Укажете дали Dynamics 365 Package Deployer пропуска всички операции за импортиране на данни като импортиране на примерни данни на Dataverse, плоски данни и данни, изнесени от Configuration Migration Tool. Укажете „вярно” или „невярно”. По подразбиране е false.
    OverrideDataImportSafetyChecks Свойство Задайте дали Dynamics 365 Package Deployer заобикаля някои от проверките за безопасност, което помага за подобряване на производителността на импортирането. Посочете true или false. По подразбиране е false.

    Трябва да зададете това свойство само true ако целевият Dataverse екземпляр не съдържа данни.

  4. Запишете проекта. Следващата стъпка е да създадете пакета.

Изграждане и внедряване

Следващите раздели описват как да създадете и внедрите пакет.

Компилация

Изграждането на вашия пакет е описано по-долу в зависимост от инструмента, който използвате.

За да създадете пакет, създаден с CLI, можете да заредите .csproj файла в Visual Studio него, но вместо това ще използваме командата dotnet и MSBuild. Примерът по-долу предполага, че работната директория съдържа файла *.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.

  • <Папка> PackageName: Името на папката е същото като това, което сте променили за името на папката на вашия пакет в стъпка 2.g на този раздел Добавяне на код по избор. Тази папка съдържа всички решения, данни за конфигурация, фиксирани файлове и съдържанието за вашия пакет.

Бележка

Може да видите папка .NET (напр. net472), съдържаща папка pdpublish. Вашият DLL и други файлове на проекта са в тази папка pdpublish.

  • <PackageName>.dll: Сглобката съдържа персонализирания код за вашия пакет. По подразбиране името на блока е същото като името на вашия проект.

Внедряване

След като създадете пакет, можете да го разгърнете в екземпляр на Dataverse, като използвате Package Deployer инструмент, Windows PowerShell, или CLI команда.

  • За внедряване с помощта на инструмента Package Deployer, първо изтеглете инструмента, както е описано в инструменти за разработка на Dataverse. След това следвайте подробната информация за разполагането на пакети в статията Разполагане на пакети с помощта Package Deployer или Windows PowerShell.

  • За внедряване с помощта на 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.

Създаване на пакети

Когато създават пакети, разработчиците трябва:

  • Уверете се, че пакетите са подписани.

Разгръщане на пакети

При внедряването на пакети Dataverse администраторите трябва да:

  • Настоявайте за подписани пакетни сглобки, за да можете да проследите сглобката обратно до източника му.
  • Тествайте опаковката на предпроизводствен екземпляр, за предпочитане огледален образ на производствен екземпляр, преди да го стартирате на производствен екземпляр.
  • Архивирайте производствен екземпляр , преди да внедрите пакета.

Вижте също

Инструмент за опаковане на решения