SolutionPackager ツール

  • [アーティクル]

SolutionPackager は、 Microsoft Dataverse 圧縮されたソリューション ファイルを複数の XML ファイルやその他のファイルに可逆的に分解できるツールです。 そうすると、ソース管理システムを使用することによりこれらのファイルを簡単に管理できます。 以下のセクションでは、ツールの実行方法と、管理ソリューションとアンマネージド ソリューションでツールを使用する方法を示します。

SolutionPackager ツールの場所

SolutionPackager ツール が Microsoft.CrmSdk.CoreTools NuGet パッケージの一部として配布されます。 プログラムをインストールするには、この手順に従います。

  1. NuGet パッケージをダウンロードします。
  2. パッケージのファイル名拡張子を .nupkg から .zip に変更します。
  3. 圧縮 (zip) ファイルのコンテンツを解凍します。

SolutionPackager.exe 実行可能ファイルは、<extracted-folder-name>/contents/bin/coretools フォルダーにあります。 coretools フォルダーからプログラムを実行するか、そのフォルダーを PATH に追加します。

SolutionPackager のコマンドライン引数

SolutionPackager は、次の表で特定されるパラメーターで起動できるコマンドライン ツールです。

引数 説明設定
/action: {Extract|Pack} 必須。 実行されるアクション。 このアクションは、ソリューションの .zip ファイルをフォルダーへ展開するか、またはフォルダーを .zip ファイルへ圧縮するかのいずれかです。
/zipfile: <ファイルパス> 必須。 ソリューションの .zip ファイルのパスおよびファイル名。 展開時に、ファイルが存在して読み取り可能である必要があります。 圧縮時に、ファイルが置き換えられます。
/folder: <フォルダー パス> 必須。 フォルダーへのパス。 展開時に、このフォルダが作成され、それにコンポーネント ファイルが実装されます。 圧縮時には、このフォルダーが既に存在していて、前に展開されたコンポーネント ファイルが格納されている必要があります。
/packagetype: {Unmanaged|Managed|Both} オプション。 処理するパッケージの種類。 既定値は Unmanaged です。 パッケージの種類は .zip ファイルまたはコンポーネント ファイル内から読み取ることができるので、ほとんどの場合、この引数は省略されることがあります。 展開と Both が指定されているとき、管理ソリューションおよびアンマネージド ソリューションの .zip ファイルが存在している必要があり、処理されて単一のフォルダーへ格納されます。 圧縮と Both が指定されているときは、管理ソリューションおよびアンマネージド ソリューションの .zip ファイルが 1 つのフォルダーから生成されます。 詳細については、このトピックの後のところにある、管理ソリューションおよびアンマネージド ソリューションを使用した作業についてのセクションを参照してください。
/allowWrite:{Yes|No} オプション。 既定値は Yes です。 この引数は、展開時のみ使用されます。 /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 web リソースの使用

/map コマンド引数の使用

以下の説明で、SolutionPackager ツールへの /map 引数の使用を詳述します。

自動化したビルド システムでビルドされる、.xap Silverlight ファイルおよびプラグイン アセンブリなどのファイルは、通常は、ソース コントロールにチェックインされません。 Web リソースは、SolutionPackager ツールと直接互換性のない場所のソース コントロールに既にある場合があります。 /map パラメーターを含めることにより、SolutionPackager ツールに、通常実行している Extract フォルダ内からではなく、別の場所から当該ファイルを読み取って圧縮するように指示することができます。 /map パラメーターは、マッピング ディレクティブを含む XML ファイルの名前とパスを指定する必要があります。 これらのディレクティブは、名前とパスによってファイルを照合するように SolutionPackager に指示し、一致したファイルを見つけるための別の場所を示します。 次の情報はすべてのディレクティブに平等に適用されます。

  • 同一のファイルと一致するディレクティブを含む、複数のディレクティブが表示されることがあります。 ファイルの始めに表示されているディレクティブは、後に表示されているディレクティブよりも優先されます。

  • ファイルをディレクティブと照合する場合、少なくとも 1 つの別の場所にそのファイルが見つかる必要があります。 一致する代替が見つからない場合、SolutionPackager がエラーを発行します。

  • フォルダーとファイルのパスには絶対パスまたは相対パスがあります。 相対パスは、/folder パラメーターによって指定されるフォルダーから常に評価されます。

  • 環境変数は、%variable% 構文を使用して指定できます。

  • フォルダのワイルドカード "**" は、"すべてのサブフォルダー内" を意味するために使用できます。 これは、“c:\folderA\**” などのパスの最終の部分としてのみ使用できます。

  • ファイル名のワイルドカードは、“*.ext” または “*.*” の形式でのみ使用できます。 他のパターンはサポートされていません。

    3 種類のディレクティブ マッピングは、その使用方法を示す例とともに、ここに記載されています。

フォルダーのマッピング

次の情報は、フォルダのマッピングの詳細を示します。

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 コード サンプルは、CRMDevTookitSample という名前の 開発者ツール プロジェクトから、SolutionPackager ツールによる Web リソースと 2 つの既定の生成されたアセンブリの読み取りを可能にする完全なマッピング ファイルを示しています。

<?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) ファイルは、ここに示す 2 種類のいずれかでエクスポートできます。

マネージド ソリューション
組織へのインポートの準備が整っている完全なソリューションです。 いったんインポートされると、コンポーネントをさらに任意にカスタマイズすることは可能ですが、コンポーネントを追加または削除することはできません。 これは、ソリューションの開発が完了したときにお勧めします。

アンマネージド ソリューション
追加、削除または変更の内容に制限のないオープン ソリューション。 これは、ソリューション開発時に推奨されます。

圧縮されるソリューション ファイルの形式は、管理またはアンマネージドの種類に基づいて異なります。 SolutionPackager は、いずれかの種類の圧縮されたソリューション ファイルを処理します。 ただし、ツールは一方の種類から他方の種類に変更できません。 ソリューション ファイルを別の種類へ、たとえば、アンマネージドから管理へ変換する唯一の方法は、アンマネージド ソリューション .zip ファイルを Dataverse サーバーへインポートし、そのソリューションを管理ソリューションとしてエクスポートすることです。

SolutionPackager は、 /PackageType:Both パラメーターを通して、アンマネージド ソリューションと管理ソリューションの .zipファイルを組み合わせたセットとして処理できます。 この操作を実行するには、次のように、.zip ファイルに名前を付けて、ソリューションを 2 回それぞれの種類でエクスポートする必要があります。
アンマネージド .zipファイル: AnyName.zip マネージド .zipファイル: AnyName_managed.zip

ツールは、マネージド zip ファイルがアンマネージド ファイルと同じフォルダーにあることを前提としており、管理コンポーネントとアンマネージド コンポーネントにある差異を保持する 1 つのフォルダーに両方のファイルを展開します。

ソリューションがアンマネージドと管理の両方で展開された後、作成する種類を /PackageType パラメーターを使用して指定することで、その単一のフォルダーから各種類を個別にまたは両方を圧縮することができます。 両方のファイルを指定すると、2 つの .zip ファイルが、上記の命名規則を使用して生成されます。 2 つから構成された管理およびアンマネージド フォルダーから圧縮されるときに /PackageType パラメーターが欠落している場合、既定は単一のアンマネージド ファイルを作成することです。

トラブルシューティング​​

Visual Studioを使用して、SolutionPackagerにより作成したリソース ファイルを編集する場合、“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 リソース ファイルのメタデータとデータタグが置換するためです。

回避策

  1. 任意のテキスト エディタでリソース ファイルを開き、次タグを検索および更新します。

    <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">

  2. ノード名を <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 リソース エディターを使用する場合にのみ観察されています。

関連項目

ソリューション ファイルでのソース コントロールの使用

ソリューションの概念