SFDC：Salesforce CLI コマンドを試してみました - Part 11

Part 11です。『project Commands』から続きです。デプロイコマンドなど開発者にとって重要なコマンドがここに含まれているのかなと思います。

Salesforce Developers

project Commands

メタデータの展開や取得など、プロジェクトを操作するコマンドです。

project convert mdapi

Metadata API 経由で取得したメタデータを Salesforce DX プロジェクトで使用されるソース形式に変換します。メタデータからプロジェクト作成する必要はあまりないと思うのと使い方もよくわからないのでスキップ。

// 指定されたディレクトリ内のメタデータ形式のファイルをソース形式のファイルに変換します。変換されたファイルをデフォルトのパッケージ ディレクトリに書き込みます。
sf project convert mdapi --root-dir path/to/metadata

// 変換されたファイルは指定された出力ディレクトリに書き込まれます。
sf project convert mdapi --root-dir path/to/metadata --output-dir path/to/outputdir

project convert source

ソース形式のファイルをメタデータ API を使用してデプロイできるメタデータに変換します。

// 指定されたディレクトリ内のソース形式のファイルをメタデータ形式のファイルに変換します。変換されたファイルを新しいディレクトリに書き込みます。
sf project convert source --root-dir path/to/source

// 変換されたファイルを指定された出力ディレクトリに書き込み、そのファイルを指定されたパッケージに関連付けます。
sf project convert source --root-dir path/to/source --output-dir path/to/outputdir --package-name 'My Package'

実行可能そうでしたので試してみました。

sf project convert source --root-dir force-app

metadataPackage_xxxというフォルダが作られてforce-appの中身がコピーされる感じになっていました。

中身は普通のファイルとなっていました。このコマンドの使い道は良くわかりませんが、コマンドの処理内容はこんな感じです。

project delete source

プロジェクトおよびソース追跡されていない組織からソースを削除します。
ソース追跡が有効になっている組織から削除済みアイテムを削除するには、「sf projectdeploy start」を実行します。
このコマンドを実行すると、組織内のローカル ソース ファイルとメタデータ コンポーネントの両方が削除されます。

// エイリアス「my-scratch」を持つすべてのローカル Apex ソースファイルとすべての Apex クラスを組織から削除します。
sf project delete source --metadata ApexClass --target-org my-scratch

// 特定の Apex クラスと、スペースが含まれるプロファイルをデフォルト組織から削除します。確認を求めないでください:
sf project delete source --metadata ApexClass:MyFabulousApexClass --metadata "Profile: My Profile" --no-prompt

// 削除の一環として、どの管理パッケージにも含まれていないテストを実行します。削除が成功し、組織でソース追跡が有効になっている場合は、ソース追跡情報を更新します。
sf project delete source --metadata ApexClass --test-level RunLocalTests --track-source

// ディレクトリ内の Apex ソースファイルと、デフォルト組織から対応するコンポーネントを削除します。
sf project delete source --source-dir force-app/main/default/classes

コマンドを試して見るため、SampleControllerクラスを作成。(Salesforce組織に存在する状態。)

特定のクラスを削除する的なイメージでしたが、その用途ではないみたいです。

sf project delete source --source-dir force-app/main/default/classes/SampleController.cls

次のように「File or folder not found」とエラーになりました。

サンプルコード的にclassesフォルダ内を全部削除するという意味かもしれない？もしそうだとすると利用場面はなさそうだけど。現状は理解不足ですがひとまずはわからないとして今は気にせず次を試します。

project delete tracking

すべてのローカル ソース追跡情報を削除します。リファレンスサイトにはサンプルコマンドの記載はありませんでした。

project deploy cancel

デプロイ操作をキャンセルします。とのことです。変更セットでリリース開始したあとにキャンセルボタンをクリックするのと同じ意味だと思います。

// ジョブ ID を使用してデプロイ操作をキャンセルします。
sf project deploy cancel --job-id 0Af0x000017yLUFCA2

// 最新のデプロイ操作をキャンセルします。
sf project deploy cancel --use-most-recent

project deploy preview

デプロイメントをプレビューして、組織にデプロイされる内容、潜在的な競合、および無視されるファイルを確認します。利用シーンはちょっとわからないかも。

// Force-app などのディレクトリ内のソース ファイルのデフォルト組織へのデプロイをプレビューします。
sf project deploy preview  --source-dir force-app

// エイリアス「my-scratch」を使用して、すべての Apex クラスの組織へのデプロイをプレビューします。
sf project deploy preview --metadata ApexClass --target-org my-scratch

// 特定の Apex クラスのデプロイをプレビューします。
sf project deploy preview --metadata ApexClass:MyApexClass

// マニフェストにリストされているすべてのコンポーネントの展開をプレビューします。
sf project deploy preview --manifest path/to/package.xml

試してみてわかったのは、このコマンドはSandboxまたはスクラッチ組織で利用するためのコマンドのようです。

project deploy quick

検証されたデプロイメントを組織に迅速にデプロイします。変更セットリリースのクリックリリースと同じと思われます。

// ジョブ ID を使用してデフォルト組織へのクイックデプロイを実行します。
sf project deploy quick --job-id 0Af0x000017yLUFCA2

// エイリアス「my-prod-org」を使用して、組織への最近検証されたデプロイメントのクイック デプロイを非同期的に実行します。
sf project deploy quick --async --use-most-recent --target-org my-prod-org

project deploy report

デプロイ操作のステータスを確認します。「report」のついたコマンドは非同期処理の実行状況確認用で共通の命名のようです。

// ジョブ ID を使用してステータスを確認します。
sf project deploy report --job-id 0Af0x000017yLUFCA2

// 最新のデプロイ操作のステータスを確認します。
sf project deploy report --use-most-recent

project deploy resume

デプロイ操作の監視を再開します。resumeのついたコマンドは非同期処理でタイムアウトしたときなどに処理を再開するためのコマンドの共通の命名のようです。

// ジョブ ID を使用してデプロイ操作の監視を再開します。
sf project deploy resume --job-id 0Af0x000017yLUFCA2

// 最新のデプロイ操作の監視を再開します。
sf project deploy resume --use-most-recent

project deploy start

メタデータをローカル プロジェクトから組織にデプロイします。generate classなどで作成したファイルはローカル上のものでSalesforce組織には反映されていません。これをSalesforce組織に反映するときのコマンドだと思います。

// 組織内ではないローカルの変更をデプロイします。デフォルトの組織を使用します。
sf project deploy start

// ディレクトリ内のソース ファイルを、エイリアス「my-scratch」を使用して組織にデプロイします。
sf project deploy start  --source-dir path/to/source --target-org my-scratch

// 特定の Apex クラスと、ソースがディレクトリにあるオブジェクトをデプロイします (両方の例は同等です)。
sf project deploy start --source-dir path/to/apex/classes/MyClass.cls path/to/source/objects
sf project deploy start --source-dir path/to/apex/classes/MyClass.cls --source-dir path/to/source/objects

// すべての Apex クラスをデプロイします。
sf project deploy start --metadata ApexClass

// 特定の Apex クラスをデプロイします。
sf project deploy start --metadata ApexClass:MyApexClass

// すべてのカスタムオブジェクトと Apex クラスをデプロイします (両方の例は同等です)。
sf project deploy start --metadata CustomObject ApexClass
sf project deploy start --metadata CustomObject --metadata ApexClass

// すべての Apex クラスと、名前にスペースが含まれるプロファイルをデプロイします。
sf project deploy start --metadata ApexClass --metadata "Profile:My Profile"

// マニフェストにリストされているすべてのコンポーネントをデプロイします。
sf project deploy start --manifest path/to/package.xml

// デプロイメントの一部として管理パッケージに含まれていないテストを実行します。
sf project deploy start --metadata ApexClass --test-level RunLocalTests

試してみました。クラス名まで指定する場合は拡張子まで設定が必要となります。

sf apex generate class --name SampleController --output-dir force-app/main/default/classes
sf project deploy start  --source-dir force-app/main/default/classes/SampleController.cls --target-org sfdc-my-playground

今回は1クラスをデプロイする感じで使用しましたが、「すべてのApexクラスをデプロイ」のようなコマンドをスクラッチ組織作成後にまとめてデプロイするために使用するのが主な使い方かもしれません。

project deploy validate

実際に実行せずにメタデータのデプロイメントを検証します。変更セットリリースの検証にあたる操作じゃないかと思います。

// ディレクトリ内のすべてのソース ファイルのデフォルト組織へのデプロイを検証します。
sf project deploy validate --source-dir path/to/source

// デプロイメントを非同期的に検証し、エイリアス「my-prod-org」を使用して組織内のすべてのテストを実行します。コマンドはすぐにジョブ ID を返します。
sf project deploy validate --source-dir path/to/source --async --test-level RunAllTestsInOrg --target-org my-prod-org

// マニフェストにリストされているすべてのコンポーネントのデプロイメントを検証します。
sf project deploy validate --manifest path/to/package.xml

試してみました。

sf project deploy validate --manifest manifest/package.xml

実行結果はこんな感じです。Passing/Failingとあるのでエラーチェックも動いていると思います。変更セットを用意しなくてもデプロイ前のチェックができるのは便利そうです。

project generate

Salesforce DX プロジェクトを生成します。これはワークスペースで最初に実行するコマンド。VSCodeのマニフェストファイルから〜の操作と同じだと思います。

// 「mywork」という名前のプロジェクトを生成します。
sf project generate --name mywork

// 「myapp」というディレクトリにファイルを生成します。
sf project generate --name mywork --default-package-dir myapp

// デフォルトの package.xml マニフェスト ファイルも生成します。
sf project generate --name mywork --default-package-dir myapp --manifest

// 最小限のファイルとディレクトリを含むプロジェクトを生成します。
sf project generate --name mywork --template empty

実行結果です。

もしこのコマンドでプロジェクト作成するときは「--manifest」を忘れずにつけてpackage.xmlは生成するべきだと思いました。

project generate manifest

デプロイまたは取得するメタデータ コンポーネントをリストしたプロジェクト マニフェストを作成します。

// すべての Apex クラスとカスタムオブジェクトを展開または取得するためのマニフェストを作成します。
sf project generate manifest --metadata ApexClass --metadata CustomObject -d manifest

// 指定された Apex クラスを削除するためのマニフェストを作成します。
sf project generate manifest --metadata ApexClass:MyApexClass --type destroy -d manifest

// 指定されたローカル ディレクトリにすべてのメタデータ コンポーネントを展開または取得するためのマニフェストを作成します。ファイルに myNewManifest.xml という名前を付けます。
sf project generate manifest --source-dir force-app --name myNewManifest

// 指定した組織内のメタデータ コンポーネントからマニフェストを作成し、ロックされていないパッケージにメタデータを含めます。
sf project generate manifest --from-org test@myorg.com --include-packages unlocked

試してみました。-d で出力先は指定した方が良いです。

sf project generate manifest --metadata ApexClass --metadata CustomObject -d manifest

指定したApexクラスとCustomObjectがpackage.xmlにセットできました。

もう一つ、削除用のmanifest作成が気になったので試してみました。

sf project generate manifest --metadata ApexClass:MyApexClass --type destroy -d manifest

実行すると「destructiveChanges.xml」が作成できます。

project list ignored

ローカル プロジェクト パッケージ ディレクトリに対象外のファイルを表示する。

// すべてのパッケージ ディレクトリ内の無視されるすべてのファイルをリストします。
sf project list ignored

// 特定のディレクトリ内の無視されるすべてのファイルをリストします。
sf project list ignored --source-dir force-app

// 特定のファイルが無視されているかどうかを確認します。
sf project list ignored --source-dir package.xml

project reset tracking

ローカルおよびリモートのソース追跡をリセットします。で、既存のソース トラッキング ファイルをすべて削除または上書きします。細心の注意を払って使用してください。との注意文がありました。よくわからないので今は触らない。

// --revision パラメータを使用して、ソース追跡を組織ソースメンバーの特定のリビジョン番号にリセットします。リビジョン番号を取得するには、「data soql」コマンドを使用して SourceMember Tooling API オブジェクトをクエリします。
sf data query --query "SELECT MemberName, MemberType, RevisionCounter FROM SourceMember" --use-tooling-api

project retrieve preview

プロジェクトのプレビューの取得ができるコマンドです。

// デフォルト組織からのすべての変更の取得をプレビューします。
sf project retrieve preview

// エイリアス「my-scratch」を持つ組織からの競合を無視する場合の取得をプレビューします。
sf project retrieve preview --ignore-conflicts --target-org my-scratch

試したところ次のエラーメッセージとなりました。Sandbox やスクラッチ組織など、ソース追跡が有効になっている組織でのみ使用できるとのことです。

This command can only be used on orgs that have source tracking enabled, such as sandboxes and scratch orgs.

project retrieve start

組織からローカル プロジェクトにメタデータを取得します。

// デフォルト組織からリモート変更を取得します。
sf project retrieve start

// エイリアス「my-scratch」を使用して組織からディレクトリ内のソース ファイルを取得します。
sf project retrieve start --source-dir path/to/source --target-org my-scratch

// 特定の Apex クラスと、ソースがディレクトリ内にあるオブジェクトを取得します (両方の例は同等です)。
sf project retrieve start --source-dir path/to/apex/classes/MyClass.cls path/to/source/objects
sf project retrieve start --source-dir path/to/apex/classes/MyClass.cls --source-dir path/to/source/objects

// すべての Apex クラスを取得します。
sf project retrieve start --metadata ApexClass

// 特定の Apex クラスを取得します。
sf project retrieve start --metadata ApexClass:MyApexClass

// すべてのカスタムオブジェクトと Apex クラスを取得します (両方の例は同等です)。
sf project retrieve start --metadata CustomObject ApexClass
sf project retrieve start --metadata CustomObject --metadata ApexClass

// マニフェストにリストされているすべてのメタデータ コンポーネントを取得します。
sf project retrieve start --manifest path/to/package.xml

// パッケージからメタデータを取得します。
sf project retrieve start --package-name MyPackageName

// 複数のパッケージからメタデータを取得します。そのうちの 1 つは名前にスペースが含まれています (両方の例は同等です)。
sf project retrieve start --package-name Package1 "PackageName With Spaces" Package3
sf project retrieve start --package-name Package1 --package-name "PackageName With Spaces" --package-name Package3

// Force-app ディレクトリにリストされているメタデータ コンポーネントを取得しますが、それらはメタデータ形式で「output」ディレクトリの ZIP ファイルに取得されます。
sf project retrieve start --source-dir force-app --target-metadata-dir output

// メタデータ形式で取得し、内容を「出力」ディレクトリに自動的に抽出します。
sf project retrieve start --source-dir force-app --target-metadata-dir output --unzip

サンプルコードの数がかなり多かったです。とりあえず一つ適当に試してみました。

sf project retrieve start --source-dir force-app --target-org sfdc-my-playground

実行結果はこんな感じ。VSCodeのソースを組織から取得と同じかと思うのですが、挙動を見たら同じではありませんでした。ソースを取得を使ったほうが間違いなさそう。

Part 11 のまとめ

『project Commands』をざっくりチェックしてみました。ひとまずはこういうコマンドが使えるというところで次に行きます。