Средство SolutionPackager
SolutionPackager — это инструмент, который может обратимо разбить сжатый файл решения Microsoft Dataverse на несколько XML-файлов и других файлов. Затем вы сможете легко управлять этими файлами с помощью системы управления версиями. В следующих разделах показано, как запустить инструмент и как использовать инструмент с управляемыми и неуправляемыми решениями.
Где найти инструмент SolutionPackager
Инструмент SolutionPackager распространяется как часть пакета NuGet Microsoft.CrmSdk.CoreTools. Чтобы установить программу, выполните следующие действия.
- Загрузите пакет NuGet.
- Переименуйте расширение имени файла пакета с .nupkg на .zip.
- Извлеките содержимое сжатого zip-файла.
Вы найдете исполняемый файл SolutionPackager.exe в папке <extracted-folder-name>/contents/bin/coretools. Запустите программу из папки coretools или добавьте эту папку в PATH.
Аргументы командной строки средства SolutionPackager
SolutionPackager — это инструмент командной строки, который можно вызывать с параметрами, указанными в следующей таблице.
| Аргумент | Description |
|---|---|
| /action: {Extract|Pack} | Обязательное. Действие для выполнения. Действие может быть либо извлечением ZIP-файла решения в папку, либо упаковкой папки в ZIP-файл. |
| /zipfile: <путь к файлу> | Обязательное. Путь и имя ZIP-файла решения. При извлечении файл должен существовать и быть читаемым. При упаковке файл заменяется. |
| /folder: <путь к файлу> | Обязательное. Путь к папке. При извлечении эта папка создается и заполняется файлами компонентов. При упаковке эта папка должна уже существовать и содержать ранее извлеченные файлы компонентов. |
| /packagetype: {Unmanaged|Managed|Both} | Необязательно. Тип обрабатываемого пакета. По умолчанию используется значение Unmanaged (Неуправляемое). Этот аргумент может быть опущен в большинстве случаев, потому что тип пакета можно прочитать из ZIP-файла или файлов компонентов. Если при извлечении указан параметр Both, должны присутствовать ZIP-файлы управляемого и неуправляемого решений, которые обрабатываются в одной папке. Когда указана упаковка и Both, 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: {Off|Error|Warning|Info|Verbose} | Необязательно. По умолчанию используется значение Info. Этот аргумент указывает уровень регистрации информации для вывода. |
| /map: <путь к файлу> | Необязательно. Путь и имя XML-файла, содержащего директивы сопоставления файлов. При использовании во время извлечения файлы, которые обычно считываются из папки, указанной параметром /folder, считываются из альтернативных мест, как указано в файле сопоставления. Во время операции упаковки файлы, соответствующие директивам, не записываются. |
| /nologo | Необязательно. Подавляет баннер во время выполнения. |
| /log: <путь к файлу> | Необязательно. Путь и имя файла журнала. Если файл уже существует, новая информация журнала добавляется в файл. |
| @ <путь к файлу> | Необязательно. Путь и имя файла, который содержит аргументы командной строки для инструмента. |
| /sourceLoc: <строка> | Необязательно. Этот аргумент генерирует файл ресурса шаблона и действителен только при извлечении. Возможные значения: auto или код LCID/ISO для языка, который вы хотите экспортировать. Когда этот аргумент используется, строковые ресурсы из данного языкового стандарта извлекаются как нейтральный файл .resx. Если указано значение auto или только длинная или короткая форма переключателя, используется базовый языковой стандарт или решение. Вы можете использовать краткую форму команды: /src. |
| /localize | Необязательно. Извлечение или объединение все строковых ресурсов в файлы .resx. Вы можете использовать краткую форму команды: /loc. Параметр локализации поддерживает общие компоненты для файлов RESX. Дополнительные сведения: Использование веб-ресурсов RESX |
Использование аргумента команды /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”.
Иерархия подпапок для каждой папки должна точно совпадать.
Подстановочные знаки папок не поддерживаются.
Имена файлов не могут быть указаны.
Примеры
<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 sub-folders -->
<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-файл.
Устранение неполадок
Если вы используете 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.
См. также
Использование управления версиями с файлами решений
Основные понятия решения