Package Deployer ツールで使用するパッケージを作成する

[アーティクル]
06/26/2024

Package Deployer を使用すると、管理者は Microsoft Dataverse のインスタンスにパッケージを展開できます。 Package Deployer パッケージ は、次の一部またはすべてで構成されます:

1 つ以上のDataverseソリューションファイル。
フラットファイルまたは構成移行ツールからエクスポートされた構成データファイル。ツールの詳細については、構成移行ツールでインスタンスと組織間を移動する構成データを移動を参照してください。
パッケージの前、間、または後に実行できるカスタムコードは、Dataverse インスタンスに展開されます。
展開プロセスの最初か最後に表示可能なパッケージに固有の HTML コンテンツ。このコンテンツは、パッケージに展開されるソリューションとファイルの説明を提供する場合に役立ちます。

Note

プラグインパッケージ と呼ばれる別のパッケージタイプがあります。この種のパッケージは、プラグイン依存アセンブリ用であり、Package Deployer パッケージとは関係ありません。

前提条件

パッケージに含めるすべてのソリューションとその他のファイルがそろっていることを確認します。
Visual Studio 2019 (またはそれ以降)、または Visual Studio Code です。

プロセスの概要

Package Deployer パッケージを作成するには、次の手順に従います。

Visual Studio または MSBuild プロジェクトを作成する
ソリューションとその他のファイルをプロジェクトに追加する
指定された HTML ファイルを更新する (オプション)
パッケージの構成値を指定する
パッケージ用のカスタムコードを定義する
パッケージをビルドおよび展開する

これらの手順については、この記事で詳しく説明います。

パッケージプロジェクトを作成する

最初の手順は、パッケージの Visual Studio または MSBuild プロジェクトを作成することです。これを行うには、使用可能な 2 つのツール拡張機能のいずれかを開発用コンピューターにインストールする必要があります。 Visual Studio Code を使用する場合、Microsoft Power Platform CLI をインストールします。それ以外の場合、Visual Studio 2019 以降なら、Visual Studio 向け Power Platform Tools をインストールします。

以下の適切なタブを選択し、目的のツール拡張機能を使用してプロジェクトを作成する方法を確認してください。どちらのツールも、プロジェクトを同様の形式で出力します。

Power Platform CLI
Power Platform tools

pac package init コマンドを実行して、初期パッケージを作成します。詳細情報: pac package

pac package init help
pac package init --outputDirectory DeploymentPackage

結果の CLI 出力には、以下に示すフォルダーとファイルが含まれます。ここでは例として "DeploymentPackage" フォルダー名を使用しました。

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

作成したプロジェクトで、PkgAssets フォルダー内の ImportConfig.xml 構成ファイルと PackageImportExtension.cs ファイルを見つけます。この記事で後述するように、これらのファイルを変更します。

Power Platform ソリューションテンプレートを使用して Visual Studio プロジェクトを作成し、後で Power Platform パッケージデプロイメントプロジェクトテンプレートを使用してパッケージプロジェクトを追加するか、または Power Platform パッケージデプロイメントプロジェクトテンプレートを使用してプロジェクトを直接作成することができます。

パッケージプロジェクトを追加します。

Note

Power Platform パッケージテンプレートを選択しないでください。そのテンプレートはプラグインパッケージ用です。

結果の Visual Studio ソリューションとプロジェクトには、以下に示すフォルダーとファイルが含まれます。ここでは例として "Deployment-package" という名前を使用しました。簡潔にするために、コンテントフォルダーの内容はここには示されていません。

C:.
│   Deployment-package.csproj
│   Deployment-package.sln
│   GettingStarted.html
│   PackageTemplate.cs
│
├───PkgFolder
│   │   ImportConfig.xml
│   │
│   └───Content

作成したプロジェクトで、PkgFolder フォルダー内の ImportConfig.xml 構成ファイルと PackageTemplate.cs ファイルを見つけます。この記事で後述するように、これらのファイルを変更します。

Power Platform ツールの拡張機能の使用に関する詳細: クイックスタート: Power Platform Tools プロジェクトを作成する

パッケージファイルを追加する

パッケージプロジェクトを作成したら、そのプロジェクトにソリューションやその他のファイルを追加することができます。

Power Platform CLI
Power Platform tools

CLI を使用する場合、追加サブコマンドのいずれかを使用して、外部パッケージ、ソリューション、参照をパッケージプロジェクトに追加できます。 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.

ソリューション Explorer ペインで、PkgFolder フォルダーの下に Dataverse ソリューションとその他のファイルを追加します。 HTML ファイルは、Content フォルダーの下に属します。この HTML コンテンツについては後で詳しく説明します。
追加するファイルごとに プロパティ ペインで、出力ディレクトリにコピー の値を 常にコピー に設定します。この値を設定すると、ファイルを生成されたパッケージで利用できるようになります。

次に、HTML 言語固有ファイルを更新します。

ソリューション Explorer ペインで、PkgFolder>コンテンツ>en-us を展開します。 EndHTML および WelcomeHTML という名前の 2 つのフォルダーが見つかります。これらのフォルダーには、パッケージの展開プロセスの最初と最後に情報を (ユーザーに) 表示できる HTML と関連ファイルが含まれます。これらのフォルダーの HTML フォルダーにあるファイルを編集して、パッケージに表示する情報を追加します。
パッケージに他の言語の HTML ファイルを追加できます。それにより、ユーザーのコンピューターのロケール設定に基づいた言語で、HTML コンテンツが表示されます。そのためには次のようにします。
1. en-us フォルダーのコピーを PkgFolder>コンテンツの下に作成します。
2. コピーしたフォルダーの名前を適切な言語に変更します。たとえば、スペイン語には、名前をes-ESに変更します。
3. HTML ファイルのコンテンツを変更して、スペイン語のコンテンツを追加します。

パッケージを構成する

プロジェクトにある ImportConfig.xml ファイルにパッケージに関する情報を追加することにより、パッケージ構成を定義します。使用できる有効な要素と属性の例と説明については、ImportConfig リファレンスをご覧ください。

カスタムコードを追加する

パッケージを環境にインポートする前、インポート中、インポート後に実行するカスタムコードを追加できます。これを行うには、次の手順に従います。

プロジェクトのルートフォルダーにある PackageTemplate.cs (または PackageImportExtension.cs) ファイルを編集します。

C# ファイルで、次のことができます:

パッケージがInitializeCustomExtensionのオーバーライドメソッドの定義で初期化されるときに実行するカスタムコードを入力します。

パッケージの実行中、このメソッドは、ユーザーがランタイムパラメータを使用できるようにするのに使用することができます。開発者として、ユーザーの入力によって処理するコードが存在する限り、RuntimeSettings プロパティを使用することで、任意のランタイムパラメーターのサポートをパッケージに追加することができます。

たとえば、次のサンプルコードは、可能性のある 2 つの値 true または false を持つパッケージに対して SkipChecks と呼ばれるランタイムパラメーターを有効にします。サンプルコードは、ユーザーが 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 を使用してパッケージをデプロイする
ソリューションがPreSolutionImportの上書きメソッドの定義にインポートされる前に実行するカスタムコードを入力して、ターゲットDataverseインスタンスの指定されたソリューションの更新中に、カスタマイズを維持または上書きするかどうか、プラグインとワークフローを自動的にアクティブ化するかどうかを指定します。

RunSolutionUpgradeMigrationStep の上書きメソッド定義を使用して、データ転送を実行または 2つのバージョンのソリューション間でアップグレードします。このメソッドは、ユーザーがインポートするソリューションが既に対象の Dataverse インスタンスに存在する場合にのみ呼び出されます。

この関数は、次のパラメーターが必要です。

パラメーター	内容
`solutionName`	ソリューションの名前
`oldVersion`	古いソリューションのバージョン番号。
`newVersion`	新しいソリューションのバージョン番号。
`oldSolutionId`	古いソリューションのGUID。
`newSolutionId`	新しいソリューションのGUID。

ソリューションのインポートがBeforeImportStageメソッドの上書き定義で完了する前に実行するカスタムコードを入力します。ソリューションのインポートが完了する前に、ImportConfig.xml ファイルで指定されたソリューションのサンプルデータおよびいくつかのフラットファイルがインポートされます。
OverrideConfigurationDataFileLanguage の上書きメソッドの定義を使用して構成データのインポートに対して現在選択されている言語を上書きします。指定した言語の指定されたロケール ID (LCID) がパッケージの利用可能な言語の一覧にない場合、既定のデータファイルがインポートされます。

ImportConfig.xml ファイルの <cmtdatafiles> ノードの構成データに対して利用可能な言語を指定します。既定の構成データインポートファイルは crmmigdataimportfile ファイルのImportConfig.xml 属性で指定されます。

データチェック (OverrideDataImportSafetyChecks = true) は、対象の Dataverse インスタンスにデータ何も含まれていないことを確認する場合に、ここで有効になります。
インポートが AfterPrimaryImport>メソッドの上書き定義で完了した後に実行するカスタムコードを入力します。ソリューションのインポートが開始する前に、これまでにインポートされなかった残りのフラットファイルがインポートされるようになりました。

目的のパッケージ名に、パッケージフォルダーの既定の名前を変更します。そのようにするには、ソリューション Explorer ペインの 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";  
}  
}

GetNameOfImportプロパティで戻り値を編集することによって、パッケージの名前を変更します。
```
public override string GetNameOfImport(bool plural)  
{  
return "Package Short Name";  
}  
```
この戻り値は、Dynamics 365 Package Deployer ウィザードのパッケージの選択ページに表示されるパッケージ名です。
GetImportPackageDescriptionTextプロパティで戻り値を編集することによって、パッケージの説明を変更します。
```
public override string GetImportPackageDescriptionText  
{  
get { return "Package Description"; }  
}  
```
この戻り値は、Package Deployer ウィザードのパッケージの選択ページで、パッケージの名前の横に表示されるパッケージの説明です。
GetLongNameOfImportプロパティで戻り値を編集することによって、パッケージの詳しい名前を変更します。
```
public override string GetLongNameOfImport  
{  
get { return "Package Long Name"; }  
}  
```
インストールするパッケージを選択した後、次のページで、パッケージの長い名前が表示されます。

また、次の関数と変数はパッケージに使用できます。

名前	種類	説明
CreateProgressItem(String)	関数	ユーザーインターフェイス (UI) で新しい処理中項目を作成するときに使用します。
RaiseUpdateEvent(String, ProgressPanelItemStatus)	関数	CreateProgressItem(String).の呼び出しによって作成された処理中の更新に使用します。 ProgressPanelItemStatus は次の値の列挙体です: 作業中 = 0 完了 = 1 失敗 = 2 警告 = 3 不明 = 4
RaiseFailEvent(String, Exception)	関数	現在の状態のインポートが失敗する場合に例外メッセージと共に使用します。
IsRoleAssoicatedWithTeam(Guid, Guid)	関数	ロールが特定のチームに関連付けられているかどうかを判断する場合に使用します。
IsWorkflowActive(Guid)	関数	指定したワークフローがアクティブになっているかどうかを判断する場合に使用します。
PackageLog	クラスのポインター	パッケージの初期化されたログインターフェイスへのポインター。このインターフェイスは、パッケージのログファイルにメッセージと例外をログするのに、パッケージによって使用されます。
RootControlDispatcher	Property	パッケージの展開中に、コントロールが独自の UI をレンダリングするのを許可するのに使用されるディスパッチャーインターフェイス。 UI 要素やコマンドをラップするのにも、このインターフェイスを使用します。値を設定しているかどうかわからないので、それを使用する前に null 値のこの変数を確認することは重要です。
CrmSvc	Property	パッケージがパッケージ内から Dynamics 365 に対応できるようにする CrmServiceClient クラスに対するポインター。このポインターを使用して、上書きされたメソッドで SDK メソッドと他のアクションを実行します。
DataImportBypass	Property	Dataverse サンプルデータ、フラットファイルデータ、および構成移行ツールからエクスポートされたデータのインポートなど、Dynamics 365 Package Deployer がすべてのデータインポート操作をスキップするかどうかを指定します。 true または false を指定します。既定は`false`です。
OverrideDataImportSafetyChecks	Property	Dynamics 365 Package Deployer の安全性チェックの一部をバイパスして、インポートのパフォーマンスを向上させるかどうかを指定します。 `true`または`false`を指定します。既定は`false`です。対象の `true` インスタンスにデータが含まれていない場合のみ、このプロパティを Dataverse に設定する必要があります。

プロジェクトを保存します。次の手順は、パッケージをビルドすることです。

ビルドと展開

次のセクションでは、パッケージを構築してデプロイする方法について説明します。

ビルド

パッケージのビルドについては、使用しているツールに応じて以下で説明します。

Power Platform CLI
Power Platform tools

CLI で作成したパッケージをビルドするには、.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 フォルダーの下にある以下のファイルで構成されています。

<PackageName> フォルダー: フォルダー名は、このセクションカスタムコードを追加するのステップ 2.g でパッケージフォルダー名に対して変更したものと同じです。このフォルダーには、すべてのソリューション、構成データ、フラットファイル、およびパッケージ内容が含まれています。

Note

pdpublish フォルダーを含む .NET フォルダー (例: net472) が表示される場合があります。 DLL およびその他のプロジェクトファイルは、その pdpublish フォルダーにあります。

<PackageName>.dll: このアセンブリには、パッケージのカスタムコードが含まれています。既定では、アセンブリの名前はプロジェクト名と同じになります。

デプロイ

パッケージの作成後、Package Deployer ツール、Windows PowerShell、または CLI コマンドを使用して、Dataverse インスタンスに展開することができます。

Package Deployer ツールを使用して展開するには、Dataverse 開発ツールの説明に従ってまずツールをダウンロードします。次に、 Package Deployer または Windows PowerShell を使用してパッケージを展開するのパッケージ展開の詳細情報に従ってください。
CLI を使用して展開するには、pac package deploy コマンドを使用します。
```
> pac package deploy --package .\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip
```
Note

CLI を使用してターゲット環境にパッケージを展開するには、まずに認証プロファイルを設定し、組織を選択する必要があります。詳細: pac auth create、pac org select

ベストプラクティス

Package Deployer パッケージを使用する際に従うべきいくつかのベストプラクティスのヒントを以下に示します。

パッケージの作成

パッケージを作成するときに、開発者は次のことを行う必要があります:

パッケージアセンブリが署名されていることを確認します。

パッケージの展開

パッケージを展開するときに、Dataverse 管理者は次のことを行う必要があります:

署名付きパッケージアセンブリを使用 して、アセンブリをそのソースまで追跡できるようにします。
実稼働インスタンスにそれを実行する前に、事前運用インスタンス (可能であれば、実稼働インスタンスのミラーイメージ) にパッケージをテストします。
パッケージを展開する前に、運用環境インスタンスをバックアップ します。

次の方法で共有

Package Deployer ツールで使用するパッケージを作成する

前提条件

プロセスの概要

パッケージプロジェクトを作成する

パッケージファイルを追加する

パッケージを構成する

カスタムコードを追加する

ビルドと展開

ビルド

デプロイ

ベストプラクティス

パッケージの作成

パッケージの展開

関連項目

フィードバック

フィードバック

その他のリソース

次の方法で共有

Package Deployer ツールで使用するパッケージを作成する

前提条件

プロセスの概要

パッケージ プロジェクトを作成する

パッケージ ファイルを追加する

パッケージを構成する

カスタム コードを追加する

ビルドと展開

ビルド

デプロイ

ベスト プラクティス

パッケージの作成

パッケージの展開

関連項目

フィードバック

フィードバック

その他のリソース

パッケージプロジェクトを作成する

パッケージファイルを追加する

カスタムコードを追加する

ベストプラクティス