Поделиться через

Создание пакетов для средства Package Deployer

  • Статья

Package Deployer позволяет администраторам развертывать пакеты в экземплярах Microsoft Dataverse. Пакет Package Deployer может состоять из каких-либо или всех нижеперечисленных элементов.

  • Один или несколько файлов решения Dataverse.
  • Неструктурированные файлы или экспортированный файл данных конфигурации из средства миграции конфигурации. Дополнительные сведения об этом средстве см. в статье Перемещение данных конфигурации между экземплярами и организациями с помощью средства миграции конфигурации.
  • Пользовательский код, который может выполняться до, во время или после развертывания пакета в экземпляре Dataverse.
  • HTML-содержимое для пакета, которое можно отобразить в начале и в конце процесса развертывания. Это содержимое может быть полезно для предоставления описания решений и файлов, развертываемых в пакете.

Заметка

Существует еще один тип пакета, называемый пакетом подключаемого модуля. Такой вид пакетом предназначен для сборок, зависящих от подключаемых модулей, и не имеет отношения к пакетам Package Deployer.

Предварительные условия

  • Убедитесь, что у вас есть все файлы решения и другие файлы, которые вы хотите включить в пакет.
  • Visual Studio 2019 или позже или Visual Studio Code.

Обзор процесса

Чтобы создать пакет Package Deployer, выполните следующие действия.

  • Создание проекта Visual Studio или MSBuild
  • Добавление решений и других файлов в проект
  • Обновление предоставленных файлов HTML (необязательно)
  • Указание значений конфигурации для пакета
  • Определение пользовательского кода для пакета
  • Сборка и развертывание пакета

Эти шаги подробно описаны в данной статье.

Создание проекта пакета

Первым шагом является создание проекта Visual Studio или MSBuild для пакета. Для этого на вашем компьютере для разработки должно быть установлено одно из двух доступных расширений инструментов. При использовании Visual Studio Code установите интерфейс командной строки Microsoft Power Platform CLI. В противном случае, если вы используете Visual Studio 2019 или более позднюю версию, установите инструменты Power Platform Tools для Visual Studio.

Выберите соответствующую вкладку ниже, чтобы узнать, как создать проект с помощью нужного расширения инструмента. Оба инструмента выводят проект в одинаковом формате.

Выполните команду pac package init для создания исходного пакета. Дополнительная информация: pac package

pac package init help
pac package init --outputDirectory DeploymentPackage

Результирующий вывод интерфейса командной строки содержит папки и файлы, показанные ниже. Имя папки «DeploymentPackage» здесь использовано в качестве примера.

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

В созданном проекте найдите файл конфигурации ImportConfig.xml в папке PkgAssets и файл PackageImportExtension.cs. Вы измените эти файлы, как будет описано далее в этой статье.

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

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

При использовании интерфейса командной строки вы можете добавлять внешние пакеты, решения и ссылки в проект пакета с помощью одной из подкоманд добавить. Введите 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, для пакета, который имеет два возможных значения: true или false. Пример кода проверяет, указал ли пользователь какие-либо параметры среды выполнения при запуске Package Deployer (с помощью командной строки или PowerShell), а затем соответственно обрабатывает информацию. Если во время выполнения пакета пользователь не указал параметр среды выполнения, значение свойства RuntimeSettings будет NULL.

      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) на панели Обозреватель решений, затем отредактируйте возвращаемое значение в свойстве 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 Используется для создания нового элемента хода выполнения в пользовательском интерфейсе.
    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 Свойство Интерфейс диспетчера, который позволяет вашему элементу управления отображать собственный интерфейс пользователя во время развертывания пакета. Используйте этот интерфейс для упаковки любых элементов или команд пользовательского интерфейса. Важно проверить эту переменную на наличие значений NULL, прежде чем использовать ее, так как для нее может быть не установлено значение.
    CrmSvc Свойство Указатель на класс CrmServiceClient, который позволяет пакету обращаться к Dynamics 365 из пакета. Используйте этот указатель для выполнения методов SDK и других действий в переопределенных методах.
    DataImportBypass Свойство Укажите, будет ли средство Dynamics 365 Package Deployer пропускать все операции импорта данных, такие как импорт демонстрационных данных Dataverse, данные неструктурированных файлов и данные, экспортированные из средства миграции конфигурации. Укажите true или false. По умолчанию — false.
    OverrideDataImportSafetyChecks Свойство Укажите, пропускает ли Dynamics 365 Package Deployer некоторые свои проверки безопасности, что помогает улучшить производительность импорта. Укажите true или false. По умолчанию — false.

    Вы должны устанавливать для этого свойства значение true, только если целевой экземпляр Dataverse не содержит никаких данных.

  4. Сохраните проект. Следующим шагом является сборка пакета.

Сборка и развертывание

В следующих разделах описывается, как собрать и развернуть пакет.

Сборка

Сборка пакета описана ниже в зависимости от того, какой инструмент вы используете.

Чтобы выполнить сборку созданного пакета с помощью интерфейса командной строки, можно было бы загрузить файл .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.

  • <ИмяПакета> папка : Имя папки такое же, как то, которое вы изменили для имени папки вашего пакета в шаг 2.g этого раздела. Добавить пользовательский код. Эта папка содержит все решения, данные конфигурации, неструктурированные файлы и содержимое для вашего пакета.

Заметка

Вы можете увидеть папку .NET (например, net472), содержащую папку pdpublish. Ваша библиотека DLL и другие файлы проекта находятся в этой папке pdpublish.

  • <ИмяПакета> .библиотека DLL : Сборка содержит пользовательский код для вашего пакета. По умолчанию имя сборки совпадает с именем проекта.

Развернуть

После создания пакета его можно развернуть в экземпляре Dataverse, используя инструмент Package Deployer, Windows PowerShell или команду интерфейса командной строки.

  • Для развертывания с помощью инструмента Package Deployer сначала загрузите инструмент, как описано в разделе Инструменты разработки Dataverse. Далее руководствуйтесь подробной информацией по развертыванию пакетов в статье Развертывание пакетов с помощью Package Deployer или Windows PowerShell.

  • Для развертывания с помощью интерфейса командной строки используйте команду pac package deploy.

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

    Заметка

    Чтобы развернуть пакет в целевой среде с помощью интерфейса командной строки, необходимо сначала настроить профиль проверки подлинности и выбрать организацию. Дополнительная информация: pac auth create, pac org select

Рекомендации

Ниже перечислены несколько практических советов, которым следует следовать при работе с пакетами Package Deployer.

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

При создании пакетов разработчики должны:

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

Развертывание пакетов

При развертывании пакетов администраторы Dataverse должны:

  • Настаивайте на подписанных комплектах поставки так что вы можете отследить сборку до ее источника.
  • Протестируйте пакет на опытном экземпляре, желательно зеркальное отражение производственный экземпляр, перед запуском его на производственный экземпляр.
  • Сохраните производственный экземпляр перед развертыванием пакета.

См. также

Инструмент Solution Packager