erp-xpp

スキル：財務・業務向け X++ 開発

重要な安全ルール — 最初にお読みください

1. Windows のみです。 pac tool xpp install と pac package compile --package-type erp は Windows が必要です。Linux／macOS や SDK ベースの代替手段をでっち上げないでください。
2. デプロイまたは DB 同期の前に、必ず対象を確認してください。 Dataverse 環境の URL を示して明示的な確認を得てから、pac org who --environment <url> を実行し、Dataverse URL と、リンクされている ERP URL／バージョンの両方を確認してください。
3. Full DB 同期を前提にしないでください。 単独実行の pac package db-sync はデフォルトで Full ですが、依頼が曖昧な場合は、ユーザーに Full、Module、Incremental のいずれかを選択してもらってください。
4. PAC が成功状態で処理を終えるまで、デプロイ成功と判断しないでください。 失敗時は非同期操作 ID を保持し、報告してください。
5. 既存のモデルやソースファイルを上書きしないでください。 スキャフォールディングや編集の前に、.erp/xpp.json、記述子、対象のメタデータパスを確認してください。
6. ERP の検証前に、すべてのランタイム接続先を固定してください。 PAC と Dataverse CLI には別々のアクティブプロファイルがあります。dataverse ... --target erp による確認の前に、dataverse auth who と dataverse org who --json が、確認済みの Dataverse URL とリンクされた ERP URL に一致することを必須としてください。ERP MCP はトランスポートに応じて検証してください。直接 HTTP 接続の場合は <erp-url>/mcp を対象にする必要があります。stdio プロキシの場合はベース URL <erp-url> を受け取り、実際には /mcp にルーティングする必要があります。プロファイルを選択しても、既存の MCP 接続先は変更されません。
7. ランタイム検証はデータを変更する可能性があるものとして扱ってください。 別途、デプロイ後の検証についてオプトインを得た後、X++ の実装を確認し、正確なテスト入力と想定される変更内容を開示して、それらの入力と影響について確認を得てください。冪等でない操作に、汎用的なテストマトリックスを適用しないでください。
8. ERP X++ パッケージのデプロイ後に行う追加検証は、すべてオプトイン制です。 pac package deploy --package-type erp の実行後、PAC の最終結果を記録し、追加検証を希望するか、また、どの確認を実行するかをユーザーに尋ねてください。選択されていない限り、非同期操作を照会したり、X++ 成果物を実行したり、その ERP エンティティを照会したり、セキュリティをテストしたりしないでください。ランタイム検証では、正確な入力、成功条件、失敗条件を確認してください。値をでっち上げたり、承認されていない失敗経路を実行したりしてはいけません。このルールは ERP X++ パッケージのデプロイに適用され、Dataverse ソリューション ALM には適用されません。

PAC CLI は X++ ライフサイクルを管理するためのインターフェイスです。これらのコマンドを、生の Dataverse API、ERP サイドカーへの直接呼び出し、LCS アップロードの自動化、手書きのコンパイラー呼び出しに置き換えないでください。

計画のみを求める X++ の依頼では、スキルの読み込みやローカルの参考資料の参照は許可されますが、環境への問い合わせやローカルファイルへの書き込みは行わないでください。

意図に応じた処理

ユーザーの意図	アクション
ERP パッケージ／モデルを作成する	pac package init --package-type erp
環境向けのコンパイラーメタデータをインストールする	pac tool xpp install
ローカル SDK を確認／削除する	pac tool xpp list / pac tool xpp uninstall
X++ をコンパイルまたはビルドする	pac package compile --package-type erp
ビルド済み ZIP を 1 つデプロイする	pac package deploy --package-type erp --package <zip>
リポジトリ内のすべてのモデルをデプロイする	pac package deploy --package-type erp --solution-root <root>
DB 同期のみを実行する	pac package db-sync
ERP カスタムサービスを作成する	X++ クラス／コントラクトと AxService、AxServiceGroup のメタデータを作成し、コンパイルしてデプロイします
ERP ICustomAPI アクションを作成する	ICustomAPI クラス、アクションメニュー項目、特権／職務／ロールのセキュリティを作成し、コンパイル、デプロイ、必要に応じた DB 同期の後、ERP MCP を通じて検証します
作成、コンパイル、デプロイ、検証を行う	エンドツーエンドのワークフローに従います

pac package build コマンドも、トップレベルの pac xpp コマンドもありません。 ERP の場合、pac package compile --package-type erp はラベルと X++ をコンパイルし、ベストプラクティスチェックを実行して、デプロイ可能なマネージド ZIP をビルドします。

スキルの範囲

必要な操作	代わりに使用
PAC CLI の接続／認証、インストールまたは更新	dv-connect
ERP の業務データの読み取りまたは分析	dv-query
ERP の業務レコードの作成／更新／削除、または DMF データのインポート	dv-data
ERP バッチジョブの一覧表示／キャンセル	dv-admin
Dataverse ソリューションの ALM	dv-solution
ERP UI のパーソナライズ、ワークフローの編集、または環境のライフサイクル管理	Finance and Operations UI ／ Power Platform 管理ツール。対象外です

事前確認

1. Windows であることを確認します。
2. pac を実行してバナーを確認します。pac --version は無効です。これらのコマンドには、PAC CLI .NET ツールのバージョン 2.11.1 以降が必要です。
3. pac package help と pac tool xpp help を実行します。compile、db-sync、または tool xpp が見つからない場合は、続行する前に dv-connect を読み込み、最新の .NET ツールをインストールしてください。
4. 環境を操作する場合は、次を実行します。

pac auth list
pac org who --environment <dataverse-url>

出力には、確認済みの Dataverse 環境と、リンクされた ERP URL／バージョンが示されている必要があります。ERP URL を --environment の代わりに指定しないでください。PAC は Dataverse URL を受け取り、ERP とのリンクを解決します。

5. Dataverse CLI または ERP MCP を通じたランタイム検証の前に、次を実行します。

dataverse auth who
dataverse org who --json \
  --context "app=dataverse-skills/<ver>;skill=erp-xpp;agent=<agent>"

選択中の CLI プロファイルの環境 URL と、返された erpUrl が、上記で確認した PAC のターゲットと一致することを必須とします。一致しない場合は、dataverse auth select --name <profile-name> を実行してから、両方の確認を繰り返します。対応するコマンドでは --environment <dataverse-url> を指定します。ただし、正しいプロファイルを選択する代わりとして、このオプションを使用してはいけません。一部の ERP データコマンドには、環境の上書きオプションがありません。

ERP MCP の検証では、アクティブなサーバー設定を確認します。直接 HTTP を使用する場合は確認済みの <erp-url>/mcp を使用し、dataverse mcp などの stdio プロキシを使用する場合は、確認済みのベース <erp-url> を受け取り、有効な /mcp エンドポイントを使用することを必須とします。一致しない場合は、検出や呼び出しを行う前に停止し、一致する ERP MCP サーバーへ再接続するか、再初期化してください。

MCP のランタイムを呼び出すたびに、トランスポート固有の新しいセッションを確立し、MCP からの ID／現在のセッション確認を通じて呼び出し元を検証してください。dataverse auth who で確認できるのは CLI の ID のみです。MCP で呼び出し元を証明できない場合は、そのセッションを通じて呼び出してはいけません。セキュリティ受け入れテストでは、証明された呼び出し元が、想定される非管理者テストユーザーである必要があります。

6. SDK を初めてインストールする前に、約 4 GB をダウンロードし、%LOCALAPPDATA%\Microsoft\Dynamics365\<version>\PackagesLocalDirectory の下で約 16 GB に展開されることを説明します。

コマンドのクイックリファレンス

# Scaffold one or more models
pac package init --outputDirectory <root> --package-type erp \
  --model <ModelA,ModelB> --publisher <publisher> --layer ISV

# SDK lifecycle
pac tool xpp install --environment <dataverse-url>
pac tool xpp list
pac tool xpp uninstall --version <four-part-version>

# Compile/build all configured models
pac package compile --solution-root <root> --package-type erp \
  --app-version <four-part-version> --language en-US

# Compile one model during the edit loop
pac package compile --solution-root <root> --package-type erp \
  --model <ModelName> --app-version <four-part-version> \
  --language en-US --incremental

# Deploy one compiled package, without DB sync
pac package deploy --environment <dataverse-url> --package-type erp \
  --package <root>/bin/<Model>_<version>_managed.zip \
  --build-type Full --release-type Dev --db-sync None \
  --logConsole --logFile <deployment-log-path>

# Deploy every model in .erp/xpp.json in dependency order
pac package deploy --environment <dataverse-url> --package-type erp \
  --solution-root <root> --build-type Full --release-type Dev \
  --db-sync None --logConsole --logFile <deployment-log-path>

自動化ではデフォルトに頼らず、明示的な値を使用してください。引数の全テーブルと DB 同期のルールについては、references/commands.md を参照してください。

X++ ソースの作成

リポジトリのルートには .erp/xpp.json があります。ソースのデフォルトの場所は src/ です。各モデルには、次の場所に記述子とメタデータがあります。

<root>/
  .erp/xpp.json
  src/<Model>/Descriptor/<Model>.xml
  src/<Model>/<Model>/AxClass/<Class>.xml

記述子／設定を手書きする代わりに、pac package init を実行してください。既存のパスを確認してから、メタデータファイルを必要な分だけ追加します。PAC は作成したメタデータをコンパイルしてパッケージ化しますが、カスタムサービス、ICustomAPI アクション、またはデータエンティティのひな形は生成しません。実行可能なクラス、ラベル、カスタムサービス、ICustomAPI アクション、パブリック OData データエンティティ、および成果物固有の検証については、references/authoring.md を参照してください。

コンパイル／ビルドルール

• 通常のコンパイルでは、ラベル → X++ → ベストプラクティスチェック → デプロイ可能な ZIP の順に実行します。
• 編集ループでのみ --incremental を使用してください。最終デプロイの前には、非増分コンパイルを実行してください。
• ユーザーから明示的に依頼され、検証が簡略化されることを理解している場合を除き、--skip-bp は使用しないでください。
• SDK が複数インストールされている場合は、--app-version を指定してください。指定しないと、PAC が選択の曖昧さを理由に拒否する場合があります。
• Compile summary: ... failed またはゼロ以外の終了コードは、以前の実行で作成された ZIP がすでに存在していても、失敗として扱ってください。
• 出力 ZIP が今回の実行によって <root>/bin/ に生成されたことを確認してください。
• ラベルコンパイルで XPPLC2010 が報告され、LabelC の終了コードが 0 でも PAC が失敗する場合は、有効なラベルリソースを追加してください。ログを削除したり、このステージを回避したりしないでください。

デプロイと DB 同期のルール

• デプロイのみの場合は、--db-sync None を指定します。
• --build-type は、サーバーがパッケージを適用する方法（Full、Incremental、または Delete）を制御します。ローカルのビルドコマンドではありません。
• --release-type Dev は、通常のテスト／開発時に選択します。同期を要求すると、Release はサーバー側で Full DB 同期を強制します。
• Delete は DB 同期の設定を無視します。
• 単一パッケージのデプロイでは --package <zip> を使用します。ソリューションモードのデプロイでは --package を省略し、.erp/xpp.json を読み込み、モデルをトポロジカル順に並べてデプロイした後、要求された DB 同期を 1 回実行します。
• PAC はデプロイ時に fnomoduledefinition.json を ZIP に挿入します。変更不可のチェックサムを保持する必要がある場合は、先に成果物をコピーしてください。
• 単独の DB 同期と同期を伴うデプロイは、それぞれ別のサポート対象ワークフローです。DB 同期のみの要求を満たすためだけに、デプロイを再実行してはいけません。

コンパイルのみ、デプロイのみ、DB 同期のみ、複数モデル、および全ライフサイクルの手順については、references/workflows.md を参照してください。すべてのコンパイル、デプロイ、DB 同期、およびランタイム検証で、references/validation.md の成功判定基準、診断フロー、およびエラーマッピングを適用してください。

エンドツーエンドのワークフロー

「この X++ の変更を行ってデプロイする」場合：

1. リポジトリを調査し、既存の作業を保持します。
2. 新しいモデルを作成する前に、モデル名、クラス名、発行元、レイヤーを確認します。
3. モデルが存在しない場合に限り、pac package init --package-type erp を実行します。
4. クラス、コントラクト、カスタムサービス、サービスグループ、ICustomAPI アクションとセキュリティ、パブリックデータエンティティ、必要なラベルなど、要求された X++ メタデータを追加または編集します。
5. 対象環境を確認して認証し、ERP の連携とバージョンを検証します。
6. 一致する SDK をインストールするか、既存のものを再利用します。
7. 非インクリメンタルにコンパイルし、コンパイルエラーがゼロであることを必須とします。ユーザーが許容しない限り、ベストプラクティスの警告に対処します。
8. ビルド、リリース、DB 同期の各モードを明示してデプロイします。
9. PAC の終了コード、非同期操作 ID、最終状態、DB 同期結果を、デプロイコマンドの一部として取得します。追加の検証を自動で実行してはいけません。
10. デプロイ後の検証を希望するか、またどのチェックを許可するかをユーザーに確認します。対象となるチェックは、非同期操作の再照会、API／アクションの検出、ランタイム動作、データエンティティのクエリ、複数ケースのテスト、セキュリティの受け入れテストです。デプロイの承認や、いずれか1つのチェックの選択によって、別のチェックが許可されるわけではありません。
11. すべての検証が拒否された場合は、PAC によるデプロイ結果を報告し、追加の検証は実施していないことを明記します。ランタイム検証が選択された場合は、デプロイ済みのカスタム成果物とそのコントラクトのみを調査し、必要な入力ごとに、その入力と期待する成功・失敗の条件を確認します。プロンプトにすでに記載されている値や条件は、そのまま繰り返して確認します。決して値や条件を創作したり、範囲を広げたりしてはいけません。
12. 選択されたランタイムチェックでは、Dataverse CLI プロファイルとトランスポート固有の ERP MCP ターゲットを、確認済みの環境に固定して、承認された成果物のみを検証します。

• 実行可能なクラス：https://<erp-host>/?mi=SysClassRunner&cls=<ClassName> を開きます。
• カスタムサービス：呼び出し前に X++ の実装を調査して副作用を確認し、dataverse api invoke --target erp --context "app=dataverse-skills/<ver>;skill=erp-xpp;agent=<agent>" を使って erp:<ServiceGroup>/<Service>/<Operation> を呼び出します。検出には list／describe のみを使用します。
• ICustomAPI アクション：検出が選択された場合は、ERP MCP の api_find_actions を使ってアクションのメニュー項目とコントラクトを検証します。実行が選択された場合は、確認済みのソースコントラクトまたは承認済みの検出結果を使って、承認された入力のみを呼び出し、返されたすべてのプロパティと期待される変更を観測結果と照合します。
• パブリック OData データエンティティ：検出が選択された場合は、dataverse data describe --target erp を使って調査します。クエリの実行が選択された場合は、dataverse data query --target erp を使って確認済みのエンティティセットにクエリを実行します。各コマンドに --context "app=dataverse-skills/<ver>;skill=erp-xpp;agent=<agent>" を追加します。
• セキュリティの受け入れテスト：ランタイム実行とセキュリティの受け入れテストの両方が選択された場合に限り、対象のカスタムロールを割り当てた非管理者のテストユーザーとして、承認されたケースを呼び出します。管理者による実行は診断目的に限られ、権限／職務／ロールの連鎖を検証するものではありません。

13. パッケージのパス、環境、非同期操作 ID、最終ステータス、DB 同期モード、承認または拒否された検証チェック、および実際に実施したチェックの結果のみを報告します。

よくある間違い — 使用しないでください

誤り	正しい
pac xpp install	pac tool xpp install
pac xpp compile	pac package compile --package-type erp
pac package build	pac package compile --package-type erp
pac package deploy --package-type xpp	--package-type erp
ERP URL を --environment に渡す	リンク済みの Dataverse URL を渡す
ZIP が 1 つなのに --package を省略する	--package <zip> を追加する
リポジトリ全体のデプロイに --package を追加する	省略して、--solution-root を使用する
pac package db-sync --db-sync None	None はデプロイ専用です。単独モードは Full、Module、Incremental です
--modules を指定せずにモジュールを同期する	--modules ModelA,ModelB を追加する
--argument-file を指定せずに増分同期する	有効な IncrementalSyncParameters JSON ファイルを追加する