Нотатка
Доступ до цієї сторінки потребує авторизації. Можна спробувати ввійти або змінити каталоги.
Доступ до цієї сторінки потребує авторизації. Можна спробувати змінити каталоги.
SolutionPackager — це інструмент, який може оборотно розкласти стиснений файл рішення Microsoft Dataverse на кілька XML-файлів та інших файлів. Після цього ви зможете легко керувати цими файлами за допомогою системи контролю джерел. У наведених нижче розділах показано, як запустити цей інструмент та способи використання цього інструмента з керованими та некерованими рішеннями.
Important
Інструмент SolutionPackager більше не є рекомендованим способом розпакування та пакування рішень. Можливості інструменту SolutionPackager інтегровані в Power Platform CLI. Команда pac solution має багато дієслів, включаючи unpack, pack, clone, і sync які поєднують ті ж базові можливості, що й інструмент SolutionPackager.
Де знайти інструмент SolutionPackager
Інструмент SolutionPackager розповсюджується як частина Microsoft. CrmSdk.CoreTools пакет NuGet. Щоб встановити програму, виконайте такі дії.
- Завантажити пакет. NuGet
- Перейменуйте розширення файлу пакета з .nupkg на .zip.
- Розпакуйте вміст стисненого (zip) файлу.
Знайдіть виконуваний файл SolutionPackager.exe у <папці extracted-folder-name>/contents/bin/coretools. Запустіть програму з папки coretools або додайте цю папку до свого PATH.
Аргументи командного рядка SolutionPackager
SolutionPackager — це інструмент командного рядка, який можна викликати з параметрами, визначеними в наведеній нижче таблиці.
| Аргумент | Опис |
|---|---|
| /дія: {Витяг|Згорнути} | Обов’язково. Дія, яку потрібно виконати. Цією дією може бути видобування ZIP-файлу рішення в папку або пакування папки в ZIP-файл. |
| /zipfile: <шлях до файлу> | Обов’язково. Шлях та ім’я ZIP-файлу рішення. При розпакуванні файл повинен існувати і бути читабельним. Під час пакування файл буде замінено. |
| /folder: <шлях до папки> | Обов’язково. Шлях до папки. Під час видобування ця папка створюється та заповнюється файлами компонентів. У разі пакування ця папка має вже існувати та містити попередньо видобуті файли компонентів. |
| /packagetype: {Некерований|Керований|Обидва} | Необов'язково. Тип пакета для обробки. Значення за замовчуванням: "Некероване". Цей аргумент може бути пропущений у більшості випадків, оскільки тип пакета можна прочитати з ZIP-файлу або з файлів компонентів. Під час видобування, якщо вказано значення "Обидва", ZIP-файли керованого та некерованого рішення мають бути присутніми та обробляються в одну папку. Коли вказано пакування та обидва, кероване та некероване рішення .zip файли створюються з однієї папки. Щоб отримати додаткові відомості, перегляньте розділ про роботу з керованими та некерованими рішеннями далі в цій статті. |
| /allowWrite:{Yes|No} | Необов'язково. Значення за промовчанням: Так. Цей аргумент використовується лише під час видобування. Якщо задано параметр /allowWrite:No, цей інструмент виконує всі операції, але не може записувати або видаляти будь-які файли. Операція видобування може бути безпечно оцінена без перезапису або видалення наявних файлів. |
| /allowDelete:{Yes|No|Prompt} | Необов'язково. Значення за замовчуванням: "Prompt". Цей аргумент використовується лише під час видобування. Коли вказано /allowDelete:Yes, будь-які файли, присутні в папці, вказаній параметром /folder і які не очікуються, автоматично видаляються. Коли вказано /allowDelete:No, видалення не відбувається. Якщо задано параметр /allowDelete:Prompt, користувачу буде відображено консоль із запитом, яка дає змогу дозволити або відхилити всі операції видалення. Якщо вказано /allowWrite:No, видалення не відбувається, навіть якщо також вказано /allowDelete:Yes. |
| /clobber | Необов'язково. Цей аргумент використовується лише під час видобування. Якщо задано параметр /clobber, файли, для яких задано атрибут лише для читання, буде перезаписано або видалено. Якщо це не вказано, файли з атрибутом лише для читання не перезаписуються і не видаляються. |
| /errorlevel: {Вимкнено|Помилка |Попередження|Інфо|Багатослівний} | Необов'язково. Значення за замовчуванням: "Info". Цей аргумент вказує на рівень даних журналювання для виводу. |
| /map: <шлях до файлу> | Необов'язково. Шлях і ім’я XML-файлу, що містить директиви із зіставлення файлів. У разі використання під час видобування файли, які зазвичай зчитуються з папки, указаної в параметрі /folder, зчитуються з альтернативних розташувань, указаних у файлі зіставлення. Під час операції pack файли, що відповідають директивам, не записуються. |
| /nologo | Необов'язково. Не показувати банер під час виконання. |
| /log: <шлях до файлу> | Необов'язково. Ім’я та шлях до файлу журналу. Якщо файл уже існує, до файлу додаються нові відомості журналювання. |
| <@ шлях до файлу> | Необов'язково. Ім’я та шлях до файлу, який містить аргументи командного рядка для цього інструмента. |
| /sourceLoc: <рядок> | Необов'язково. Цей аргумент створює файл ресурсів шаблону та дійсний лише для видобування. Можливими значеннями є auto або код LCID/ISO для мови, яку потрібно експортувати. Якщо цей аргумент використовується, рядок ресурсів із заданої мови видобувається як нейтральний RESX-файл. Якщо задано значення auto або лише довгу або коротку форму перемикача, використовується базова мова або рішення. Можна використовувати скорочену форму команди: /src. |
| /localize | Необов'язково. Розпакуйте або об'єднайте всі рядкові ресурси у файли .resx. Можна використовувати скорочену форму команди: /loc. Параметр локалізації підтримує спільні компоненти для файлів .resx. Докладніше: Використання веб-ресурсів RESX |
| /SolutionName: <name> | Необов'язково. Унікальна назва рішення для пакування або витягування, коли вихідна папка містить кілька рішень у 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 manifest (solution.yml, solutioncomponents.yml, і так далі) розміщені в корені папки, а не під solutions/<SolutionUniqueName>/, інструмент не визначає формат YAML. Інструмент повертається до XML-шляху і повідомляє про оманливу помилку про відсутній Customizations.xml. Дивіться розділ «Усунення несправностей » для інформації про те, як вирішити цю проблему.
Додаткова інформація: Reference Solution YAML format control source reference
Правила автоматичного визначення форматування
| Стан | Використаний формат |
|---|---|
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 і збірки компонентів plug-in, зазвичай не перевіряються в системі керування вхідним кодом. Веб-ресурси вже можуть бути присутніми в системі контролю вихідного коду в місцях, які безпосередньо не сумісні з інструментом SolutionPackager. Якщо додати параметр /map, інструмент SolutionPackager може бути спрямований на читання та пакування таких файлів з альтернативних розташувань, а не з папки видобування, як виконується зазвичай. Параметр /map повинен вказувати ім’я та шлях до XML-файлу, що містить директиви відображення. Ці директиви вказують SolutionPackager зіставляти файли за їхнім іменем та шляхом, а також вказують альтернативне місце для пошуку відповідного файлу. Зазначена нижче інформація стосується всіх директив однаково.
Може бути вказано декілька директив, включно з тими директивами, які відповідають ідентичним файлам. Директиви, перелічені на початку файлу, мають пріоритет над директивами, переліченими пізніше.
Якщо файл відповідає будь-якій директиві, вона має бути виявлена принаймні в одному альтернативному розташуванні. Якщо відповідних альтернатив не знайдено, SolutionPackager видає помилку.
Шляхи папок і файлів можуть бути абсолютними або відносними. Відносні шляхи завжди оцінюються з папки, вказаної у параметрі /folder.
Змінні середовища можна вказати за допомогою синтаксису %variable%.
Wildcard папки "**" може використовуватися для позначення "у будь-якій підпапці". Його можна використовувати лише як фінальну частину шляху, наприклад: "c:\folderA\**".
Wildcard імен файлів можна використовувати лише у формах "*.ext" або "*.*". Інші шаблони не підтримуються.
Тут описано три типи зіставлень директив, а також приклад, в якому показано, як їх використовувати.
Зіставлення папок
Наведена нижче інформація містить детальну інформацію про прив’язку папок.
Формат XML
<Folder map="folderA" to="folderB" />
опис
Шляхи файлу, що відповідають «папці A», переключаються на «folderB».
Ієрархія вкладених папок для кожної з них має точно збігатися.
Символи узагальнення папок не підтримуються.
Не можна вказати імена файлів.
Приклади
<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.Символи узагальнення імен файлів не підтримуються.
Підтримується символ узагальнення папок.
Приклади
<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:
Потрібно вказати шлях.
Підтримується символ узагальнення папок.
Ім’я файлу не потрібно вказувати.
Приклади
<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 читати будь-який веб-ресурс, і дві створені за замовчуванням збірки з проекту засобів розробки, який називається 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>
Керовані та некеровані рішення
Стиснутий файл (.zip) рішення Dataverse можна експортувати в один із двох типів, як показано тут.
Кероване рішення
Готове рішення, яке необхідно імпортувати в організацію. Після імпорту компоненти не можна додавати чи видаляти, хоча за бажанням можна дозволити подальше налаштування. Це рекомендовано застосовувати, якщо розробку рішення завершено.
Некероване рішення
Відкрите рішення без обмежень, яке можна додавати, видаляти або змінювати. Цей тип рішення рекомендовано застосовувати під час розробки рішення.
Формат стиснутого файлу рішення буде відрізнятися залежно від його типу (кероване чи некероване). SolutionPackager може обробляти стиснуті файли рішень будь-якого типу. Однак інструмент не може конвертувати один тип у інший. Єдиний спосіб перетворити файли рішень на інший тип (наприклад, з некерованого на кероване) – імпорт ZIP-файлу некерованого рішення в сервер Dataverse, а потім експорт цього рішення як керованого рішення.
SolutionPackager може обробляти ZIP-файли некерованих і керованих рішень як комбінований набір за допомогою параметра /PackageType:Both. Для виконання цієї операції необхідно експортувати рішення двічі для кожного типу, називаючи ZIP-файли, як зазначено нижче.
ZIP-файл некерованого рішення: AnyName.zip
ZIP-файл керованого рішення: AnyName_managed.zip
Цей інструмент буде вважати, що ZIP-файл керованого рішення присутній в тій самій папці, що й файл некерованого рішення, і розпаковуватиме обидва файли в одну папку, зберігаючи відмінності в яких існують керовані та некеровані компоненти.
Після видобування рішення як некерованого та керованого, можливо з цієї однієї папки упакувати обидва або кожен тип окремо, використовуючи параметр /PackageType, щоб указати, який тип потрібно створити. При визначенні обох файлів буде створено два .zip файлів з використанням правил іменування, як зазначено вище. Якщо параметр /PackageType відсутній під час пакування з подвійної папки керованого та некерованого рішень, за замовчуванням створюється один ZIP-файл некерованого рішення.
Виправлення неполадок
Повідомлення, що відображається при використанні 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, не має вихідних файлів
Це попередження з'являється, коли компонент, наприклад додаток Canvas, зазначений у rootcomponents.yml в, але відповідних вихідних файлів у папці очікуваного компонента немає (наприклад, canvasapps/<schema-name>/).
Ефект: Інструмент все одно успішно працює (вихідний код 0) і створює дійсний .zip файл, але оголошений компонент опускається з упакованого рішення.
Причина: Папка створювалася частковим витягом, або вихідні файли компонента не були включені до репозиторію. Наприклад, лише файли маніфесту рішень були зафіксовані, а сам додаток Canvas — ні.
Виправлення: Переконайтеся, що всі компоненти, заявлені в, rootcomponents.yml мають відповідні вихідні файли у папці. Для додатків Canvas файл .msapp має існувати під canvasapps/<schema-name>/. Якщо якісь файли відсутні, повторно експортуйте повне рішення з Dataverse і розпакуйте його знову, або використовуйте pac solution clone для отримання повного витягу.