Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
SolutionPackager — это средство, которое может обратимо разложить Microsoft Dataverse сжатый файл решения в несколько XML-файлов и других файлов. Затем вы сможете легко управлять этими файлами с помощью системы управления версиями. В следующих разделах показано, как запустить средство и как использовать его с управляемыми и неуправляемыми решениями.
Important
Инструмент SolutionPackager больше не является рекомендуемым способом распаковки и упаковки решений. Возможности средства SolutionPackager включены в интерфейс командной строки Power Platform. Команда pac solution содержит много команд, включая unpack, packcloneи sync которые включают те же базовые возможности средства SolutionPackager.
Где найти инструмент SolutionPackager
Средство SolutionPackager распространяется как часть Microsoft.CrmSdk.CoreTools пакета NuGet. Чтобы установить программу, выполните следующие действия.
- Загрузите пакет NuGet.
- Переименуйте расширение имени файла пакета с .nupkg на .zip.
- Извлеките содержимое сжатого zip-файла.
Найдите исполняемый файл SolutionPackager.exe в папке <extracted-folder-name>/contents/bin/coretools. Запустите программу из папки coretools или добавьте эту папку в PATH.
Аргументы командной строки SolutionPackager
SolutionPackager — это средство командной строки, которое можно вызвать с параметрами, указанными в следующей таблице.
| Аргумент | Description |
|---|---|
| /action: {Извлечь|Упаковать} | Обязательно. Действие, которое нужно выполнить. Действие может быть либо извлечением ZIP-файла решения в папку, либо упаковкой папки в ZIP-файл. |
| /zipfile: <путь к файлу> | Обязательно. Путь и имя файла решения .zip. При извлечении файл должен существовать и быть читаемым. При упаковке файл заменяется. |
| /folder: <путь к папке> | Обязательно. Путь к папке. При распаковке эта папка создается и заполняется файлами компонентов. При упаковке эта папка должна уже существовать и содержать ранее извлеченные файлы компонентов. |
| /packagetype: {Неуправляемый|Управляемый|И то, и другое} | Необязательно. Тип обрабатываемой упаковки. Значение по умолчанию — Unmanaged. В большинстве случаев этот аргумент может быть пропущен, так как тип пакета может быть прочитан из файла .zip или файлов компонентов. Если при извлечении указан параметр Both, должны присутствовать ZIP-файлы управляемого и неуправляемого решений, которые обрабатываются в одной папке. Когда указана упаковка и Both, ZIP-файлы управляемого и неуправляемого решения создаются из одной папки. Для получения дополнительной информации см. раздел о работе с управляемыми и неуправляемыми решениями далее в этой статье. |
| /allowWrite:{Да|Нет} | Необязательно. По умолчанию используется значение Да. Этот аргумент используется только во время извлечения. Когда указан параметр /allowWrite:No, инструмент выполняет все операции, но не может записывать или удалять какие-либо файлы. Операцию извлечения можно безопасно оценить без перезаписи или удаления существующих файлов. |
| /allowDelete:{Yes|No|Prompt} | Необязательно. Значение по умолчанию — Prompt. Этот аргумент используется только во время извлечения. Если указано значение /allowDelete:Yes, любые файлы, присутствующие в папке, указанной параметром /folder, которые не ожидаются, автоматически удаляются. Когда указано значение /allowDelete:No, удаления не происходит. Когда указан параметр /allowDelete:Prompt, пользователю предлагается через консоль разрешить или запретить все операции удаления. Если указано значение /allowWrite:No, удаление не будет выполняться, даже если также указано значение /allowDelete:Yes. |
| /clobber | Необязательно. Этот аргумент используется только во время извлечения. Если указан параметр /clobber, файлы, для которых установлен атрибут «только для чтения», перезаписываются или удаляются. Если не указано, файлы с атрибутом только для чтения не перезаписываются или удаляются. |
| /errorlevel: {Off|Ошибка|Предупреждение|Сведения|Подробные сведения} | Необязательно. По умолчанию используется значение Info. Этот аргумент указывает уровень регистрации информации для вывода. |
| /map: <путь к файлу> | Необязательно. Путь и имя файла .xml, содержащего директивы сопоставления файлов. При использовании во время извлечения файлы, обычно считываемые из папки, указанной параметром /folder, считываются из альтернативных мест, указанных в файле сопоставления. Во время операции пакета файлы, соответствующие директивам, не записываются. |
| /nologo | Необязательно. Скрыть баннер во время работы. |
| /log: <путь к файлу> | Необязательно. Путь и имя к файлу журнала. Если файл уже существует, к нему добавляется новая информация для ведения журнала. |
| <@ путь к файлу> | Необязательно. Путь и имя к файлу, содержащему аргументы командной строки для средства. |
| /sourceLoc: <строка> | Необязательно. Этот аргумент создает файл ресурсов шаблона и действителен только при извлечении. Возможными значениями являются auto код LCID/ISO для языка, который вы хотите экспортировать. При использовании этого аргумента строковые ресурсы из данной локали извлекаются в виде нейтрального файла .resx. Если указано значение auto или только длинная или короткая форма переключателя, используется базовый языковой стандарт или решение. Вы можете использовать краткую форму команды: /src. |
| /localize | Необязательно. Извлекайте или объединяйте все строковые ресурсы в файлы .resx. Вы можете использовать краткую форму команды: /loc. Параметр локализации поддерживает общие компоненты для файлов RESX. Дополнительные сведения: Использование веб-ресурсов RESX |
| /SolutionName: <имя> | Необязательно. Уникальное имя решения для упаковки или извлечения, если исходная папка содержит несколько решений под solutions/*/solution.yml. Требуется при обнаружении нескольких решений. Применяется только к формату YAML системы управления версиями. Вы можете использовать короткую форму команды: /sn. |
| /remapPluginTypeNames | Необязательно. При указании полные имена типов подключаемого модуля переназначаются на основе сборок, включенных в решение. В формате контроля версий YAML включен по умолчанию. Вы можете использовать короткую форму команды: /fp. |
Форматы файлов системы управления версиями
SolutionPackager поддерживает два макета папок при извлечении и упаковке решений.
ФОРМАТ XML (устаревшая версия)
Исходный формат. Метаданные решения хранятся в Other\Solution.xml и Other\Customizations.xml, и все файлы компонентов извлекаются в плоскую иерархию папок вместе с этими файлами. Этот формат используется по умолчанию при извлечении .zip файла без дополнительной конфигурации.
Формат контроля версий YAML
Представлено вместе с интеграцией Dataverse Git, в этом формате хранятся метаданные решения в виде файлов YAML, распределенных по структурированной иерархии папок. Это формат, используемый при фиксации решений с помощью встроенной интеграции Git в Power Apps.
Преимущества в формате XML
- Создает более чистые, более легко читаемые компонентные диффы в системе контроля версий
- Поддержка нескольких решений в одной папке репозитория
- Файлы приложений
.msappCanvas и современные потоки процессов поддерживаются только в этом формате - Переименование имени типа подключаемого модуля включено по умолчанию
Требуемая структура папок
<rootFolder>/
├── solutions/
│ └── <SolutionUniqueName>/
│ ├── solution.yml (solution metadata)
│ ├── solutioncomponents.yml (paths to all component files)
│ ├── rootcomponents.yml (root-level components)
│ └── missingdependencies.yml (dependency info)
├── publishers/
│ └── <PublisherUniqueName>/
│ └── publisher.yml (publisher definition)
├── entities/ (entity components, if present)
├── workflows/ (classic workflows, if present)
├── modernflows/ (Power Automate cloud flows, if present)
├── canvasapps/ (canvas app .msapp files, if present)
└── [other component folders]/
Important
Формат YAML автоматически определяется наличием вложенной solutions/ папки, содержащей *solution.yml файлы.
Если файлы манифеста YAML (solution.yml, solutioncomponents.yml и т. д.) помещаются в корень папки, а не в папку solutions/<SolutionUniqueName>/, средство не распознает формат YAML. Средство возвращается к XML-пути и сообщает вводящую в заблуждение ошибку о отсутствующей Customizations.xml. Сведения об устранении этой проблемы см. в статье об устранении неполадок.
Дополнительные сведения: справочник по формату управления исходным кодом в формате YAML для решения
Форматирование правил автоматического обнаружения
| Состояние | Используемый формат |
|---|---|
solutions/*/solution.yml найдено. Ровно одно решение |
Формат YAML, в котором имя решения выводится из папки |
solutions/*/solution.yml найдено — несколько решений |
Формат YAML, где аргумент /SolutionName обязателен |
В настоящее время нет solutions/ подкаталога |
ФОРМАТ XML (устаревшая версия) |
Упаковка папки формата YAML
Следующая команда упаковывает папку формата YAML.
SolutionPackager.exe /action:Pack /zipfile:MySolution.zip /folder:C:\repos\myrepo
Упаковка из папки с несколькими проектными решениями
Следующая команда упаковывает указанное решение в папке с несколькими решениями.
SolutionPackager.exe /action:Pack /zipfile:SolutionA.zip /folder:C:\repos\myrepo /SolutionName:SolutionA
Использование аргумента команды /map
В следующем обсуждении подробно описывается использование аргумента /map в средстве SolutionPackager.
Файлы, встроенные в автоматизированную систему сборки, такие как файлы .xap Silverlight и сборки подключаемых модулей, как правило не регистрируются в системе контроля версий. Веб-ресурсы могут уже присутствовать в системе контроля версий в местах, которые не совместимы напрямую со средством SolutionPackager. Включив параметр /map, инструмент SolutionPackager может быть направлен на чтение и упаковку таких файлов из альтернативных мест, а не из папки Extract, как это обычно делается. Параметр /map должен указывать имя и путь к файлу XML, содержащему директивы сопоставления. Эти директивы предписывают средству SolutionPackager сопоставлять файлы по их имени и пути и указывают альтернативное расположение для поиска соответствующего файла. Приведенная ниже информация в равной степени относится ко всем директивам.
Можно указать несколько директив, включая те, которые сопоставляют одинаковые файлы. Директивы, перечисленные ближе к началу файла, имеют приоритет над теми директивами, которые перечислены позже.
Если файл соответствует какой-либо директиве, он должен быть найден по крайней мере в одном альтернативном месте. Если не найдено подходящих альтернатив, SolutionPackager выдает ошибку.
Пути к папкам и файлам могут быть абсолютными или относительными. Относительные пути всегда оцениваются из папки, указанной параметром /folder.
Переменные среды могут быть определены с использованием синтаксиса %variable%.
Подстановочный знак папки "**" может использоваться для обозначения "в любой вложенной папке". Его можно использовать только в качестве конечной части пути, например "c:\folderA\*".
Подстановочные знаки имени файла могут использоваться только в формах "*.ext" или "*.*". Никакой другой шаблон не поддерживается.
Здесь описаны три типа сопоставлений директив, а также пример, показывающий, как их использовать.
Сопоставление папок
Ниже приведена информация о сопоставлении папок.
Формат XML
<Folder map="folderA" to="folderB" />
Описание
Пути к файлам, которые соответствуют folderA, переключаются на folderB.
Иерархия подпапок для каждой папки должна точно совпадать.
Подстановочные знаки папок не поддерживаются.
Имена файлов не могут быть указаны.
Examples
<Folder map="folderA" to="folderB" /> <Folder map="folderA\folderB" to="..\..\folderC\" /> <Folder map="WebResources\subFolder" to="%base%\WebResources" />
Сопоставление файлов с файлами
Ниже приведена более подробная информация о сопоставлении файлов с файлами.
Формат XML
<FileToFile map="path\filename.ext" to="path\filename.ext" />
Описание
Любой файл, соответствующий параметру map, будет считан из имени и пути, указанных в параметре to.
Для параметра map:
Необходимо указать имя файла. Путь необязателен. Если путь не указан, файлы из любой папки могут быть сопоставлены.
Подстановочные знаки имен файлов не поддерживаются.
Подстановочный знак папки поддерживается.
Для параметра
to:Необходимо указать имя файла и путь к нему.
Имя файла может отличаться от имени в параметре
map.Подстановочные знаки имен файлов не поддерживаются.
Подстановочный знак папки поддерживается.
Examples
<FileToFile map="assembly.dll" to="c:\path\folder\assembly.dll" />
<FileToFile map="PluginAssemblies\**\this.dll" to="..\..\Plugins\**\that.dll" />
<FileToFile map="Webresrouces\ardvark.jpg" to="%SRCBASE%\CrmPackage\WebResources\JPG format\aardvark.jpg" />
<FileToFile
map="pluginpackages\cr886_PluginPackageTest\package\cr886_PluginPackageTest.nupkg"
to="myplg\bin\Debug\myplg.1.0.0.nupkg" />
В приведенном выше примере пакета NuGet файл cr886_PluginPackageTest.nupkg не перезаписывается, если файл уже существует в указанном месте.
Сопоставление файлов с путями
Ниже приведена подробная информация о сопоставлении файлов с путями.
Формат XML
<FileToPath map="path\filename.ext" to="path" />
Описание
Любой файл, соответствующий параметру map , считывается из пути, указанного в параметре to .
Для параметра map:
Необходимо указать имя файла. Путь необязателен. Если путь не указан, файлы из любой папки могут быть сопоставлены.
Поддерживаются подстановочные знаки в именах файлов.
Подстановочный знак папки поддерживается.
Для параметра to:
Должен быть указан путь.
Подстановочный знак папки поддерживается.
Имя файла указывать не нужно.
Examples
<FileToPath map="assembly.dll" to="c:\path\folder" />
<FileToPath map="PluginAssemblies\**\this.dll" to="..\..\Plugins\bin\**" />
<FileToPath map="*.jpg" to="%SRCBASE%\CrmPackage\WebResources\JPG format\" />
<FileToPath map="*.*" to="..\..\%ARCH%\%TYPE%\drop" />
Пример сопоставления
В следующем примере кода XML показан полный файл сопоставления, который позволяет средству SolutionPackager считывать любой веб-ресурс и две сборки, созданные по умолчанию, из проекта Developer Toolkit с именем CRMDevTookitSample.
<?xml version="1.0" encoding="utf-8"?>
<Mapping>
<!-- Match specific named files to an alternate folder -->
<FileToFile map="CRMDevTookitSamplePlugins.dll" to="..\..\Plugins\bin\**\CRMDevTookitSample.plugins.dll" />
<FileToFile map="CRMDevTookitSampleWorkflow.dll" to="..\..\Workflow\bin\**\CRMDevTookitSample.Workflow.dll" />
<!-- Match any file in and under WebResources to an alternate set of subfolders -->
<FileToPath map="WebResources\*.*" to="..\..\CrmPackage\WebResources\**" />
<FileToPath map="WebResources\**\*.*" to="..\..\CrmPackage\WebResources\**" />
</Mapping>
Управлямые и неуправляемые решения
Файл сжатого решения Dataverse (.zip) можно экспортировать в одном из двух типов, как показано здесь.
Управляемое решение
Готовое решение, готовое к импорту в организацию. После импорта компоненты не могут быть добавлены или удалены, хотя они могут дополнительно разрешить дальнейшую настройку. Это рекомендуется сделать после завершения разработки решения.
Неуправляемые решения
Открытое решение без ограничений на то, что можно добавлять, удалять или изменять. Это рекомендуется при разработке решения.
Формат сжатого файла решения будет различаться в зависимости от его типа: управляемый или неуправляемый. SolutionPackager может обрабатывать сжатые файлы решений любого типа. Однако средство не может преобразовать один тип в другой. Единственный способ преобразовать файлы решения в другой тип, например из неуправляемого в управляемый, — это импортировать файл .zip неуправляемого решения на сервер Dataverse и затем экспортировать решение как управляемое решение.
SolutionPackager может обрабатывать неуправляемые и управляемые файлы решения .zip как объединенный набор с помощью параметра /PackageType:Both. Чтобы выполнить эту операцию, необходимо экспортировать ваше решение дважды для каждого типа, назвав .zip файлы следующим образом.
Неуправляемый файл .zip: AnyName.zip
Управляемый ZIP-файл: AnyName_managed.zip
Средство будет предполагать наличие управляемого zip-файла в той же папке, что и неуправляемый файл, и извлечет оба файла в одну папку, сохраняя различия между управляемыми и неуправляемыми компонентами.
После того как решение было извлечено как неуправляемое и управляемое, из этой одной папки можно упаковать оба типа или каждый тип по отдельности, используя параметр /PackageType, чтобы указать, какой тип следует создать. При указании обоих файлов, два ZIP-файла будут созданы с использованием соглашения об именах, как указано выше. Если параметр /PackageType отсутствует при упаковке из двойной управляемой и неуправляемой папки, по умолчанию создается один неуправляемый файл .zip.
Troubleshooting
Сообщение, отображаемое при использовании Visual Studio для редактирования файлов ресурсов
Если вы используете Visual Studio для редактирования файлов ресурсов, созданных пакетировщиком решений, вы можете получить сообщение, аналогичное этому: "Failed to determine version id of the resource file <filename>.resx the resource file must be exported from the solutionpackager.exe tool in order to be used as part of the pack process." Это происходит потому, что Visual Studio заменяет теги метаданных ресурсного файла на теги данных.
Обходной путь
Откройте файл ресурсов в вашем любимом текстовом редакторе, найдите и обновите следующие теги:
<data name="Source LCID" xml:space="preserve"> <data name="Source file" xml:space="preserve"> <data name="Source package type" xml:space="preserve"> <data name="SolutionPackager Version" mimetype="application/x-microsoft.net.object.binary.base64">Измените имя узла с
<data>на<metadata>.Например, эта строка:
<data name="Source LCID" xml:space="preserve"> <value>1033</value> </data>Изменяется на:
<metadata name="Source LCID" xml:space="preserve"> <value>1033</value> </metadata>Это позволяет упаковщику решения считывать и импортировать файл ресурсов. Эта проблема наблюдалась только при использовании редактора ресурсов Visual Studio.
Ошибка: "Не удается найти обязательный файл ...\Other\Customizations.xml" с папкой YAML
Эта ошибка возникает при запуске SolutionPackager (или pac solution pack) в папке, содержащей файлы YAML, например solution.yml, но эти файлы помещаются в корне папки, а не внутри требуемой solutions/<SolutionUniqueName>/ вложенной папки.
Причина: Средство определяет формат управления версиями YAML, обнаруживая solutions/ подпапку, содержащую *solution.yml файлы. Если этот каталог отсутствует, средство автоматически возвращается в формат XML (устаревшее) и ожидает Other\Customizations.xml. Полученное сообщение об ошибке ссылается на XML-файл и не упоминает YAML, который вводит в заблуждение.
Исправить: Переорганизуйте папку, чтобы файлы манифеста YAML были под правильными путями:
<rootFolder>/
solutions/<YourSolutionUniqueName>/ ← move solution.yml here
solution.yml
solutioncomponents.yml
rootcomponents.yml
missingdependencies.yml
publishers/<YourPublisherUniqueName>/
publisher.yml
Если вы получили папку в результате коммита интеграции Git или pac solution clone, структура папок уже должна быть правильной. Папка, содержащая только основные файлы YAML без solutions/ подкаталога, представляет собой неполную выдержку и не может быть упакована напрямую.
Предупреждение: компонент, объявленный в rootcomponents.yml, не имеет исходных файлов
Это предупреждение отображается, когда компонент, например приложение холста, указан в rootcomponents.yml списке, но в ожидаемой папке компонентов отсутствуют соответствующие исходные файлы (например, canvasapps/<schema-name>/).
Эффект: Средство по-прежнему выполняется успешно (код выхода 0) и создает допустимый .zip файл, но объявленный компонент опущен из упакованного решения.
Причина: Папка была создана в результате частичного извлечения, или исходные файлы компонента не были включены в репозиторий. Например, только файлы манифеста решения были зафиксированы, а не само приложение холста.
Исправление: Убедитесь, что для всех компонентов, объявленных в rootcomponents.yml, имеются соответствующие исходные файлы в папке. Для приложений на основе холста .msapp файл должен существовать в разделе canvasapps/<schema-name>/. Если отсутствуют файлы, повторно экспортируйте полное решение из Dataverse и распакуйте его еще раз или используйте pac solution clone для получения полного извлечения.