Salesforce DX 開発者ガイド
jリリース前のコードの文字列の置換
- NamedCredential には、テストに使用するエンドポイントが含まれています。ただし、ソースを本番組織にリリースするときに、別のエンドポイントを指定したいと考えています。
- ExternalDataSource にはリポジトリに保存したくないパスワードが含まれていますが、そのパスワードをメタデータと共にリリースする必要があります。
- ほぼ同じコードを複数の組織にリリースします。リリース先の組織に応じて、一部の値を条件付きで置き換えたいと考えています。
ソース形式のファイルは force:source:deploy および force:source:push コマンドで組織にリリースされる直前に ZIP ファイルに変換されますが、このときに文字列が実際に置換されます。文字列置換によって生じた変更は、プロジェクトには書き込まれず、リリースされるファイルにのみ適用されます。
文字列置換の設定
- 置換される文字列を含む 1 つ以上のソースファイル。
- 置換される文字列。
- 置換する値。
replacements プロパティでは、次のキーを指定できます。
- ファイルの場所
- 次のプロパティのいずれかが必要です。
- filename: 置換される文字列を含む単一のファイル。
- glob: 置換される文字列を含むファイルのコレクション。例: **/classes/*.cls。
- 置換される文字列
- 次のプロパティのいずれかが必要です。
- stringToReplace: 置換される文字列。
- regexToReplace: 置換される文字列パターンを指定する正規表現 (regex)。
- 置換する値
- 次のプロパティのいずれかが必要です。
- replaceWithEnv: 文字列が環境変数の値に置換されることを指定します。
- replaceWithFile: 文字列がファイルの内容に置換されることを指定します。
- 条件付き処理
- 次のプロパティは省略可能です。
- replaceWhenEnv: 特定の環境変数が特定の値に設定された場合にのみ文字列を置換することを指定します。環境変数を指定するには env プロパティ、文字列の置換をトリガする値を指定するには value プロパティを使用します。
次の構文規則に従います。
- Windows の場合でも、ディレクトリには必ずスラッシュ (/) を使用します。
- バックスラッシュ (\) は、JSON と正規表現の両方でエスケープ文字として使用されます。このため、エスケープが必要なドットを正規表現を使用して突き合わせるには、regexToReplace の値に 2 つのバックスラッシュを使用する必要があります。同様に、単一のバックスラッシュを突き合わせるには、3 つのバックスラッシュを指定する必要があります。
例
次の例は、環境変数 DEPLOY_DESTINATION が存在し、その値が PROD である場合にのみ文字列を置換するように指定する方法を示しています。
次の例では、force-app/main/default ディレクトリ内の Apex クラスファイルのリリース時に、出現する replaceMe という文字列をすべて replacementFiles/copyright.txt ファイルの内容に置き換えることが指定されています。
文字列置換のテスト
ファイルを実際に組織にリリースせずに文字列置換をテストするには、次の手順を実行します。
- SF_APPLY_REPLACEMENTS_ON_CONVERT 環境変数を true に設定します。
-
force:source:convert コマンドを実行します。ソースファイルがメタデータ API 形式に変換されます。次に例を示します。
- 出力ディレクトリ (この例では mdapiOut) のファイルを検査し、文字列置換と組織にリリースされる正確な内容を確認します。
ヒントとコツ
- (macOS または Linux のみ) replaceWithEnv または replaceWhenEnv プロパティを使用するときは、コマンドを実行する前に環境変数を先頭に追加して、その環境変数を単一のコマンドに適用することを指定できます。次に例を示します。
- 設定した文字列置換が多く、その管理が難しい場合は、1 つ以上のファイルの内容を環境に読み込むオープンソースツール (dotenv-cli など) を調べてください。この例の場合、2 つのローカル .env ファイルで設定されている環境変数は、force:source:push コマンドの実行前に読み込まれます。
-
force:source:deploy または force:source:push に --json を指定した場合は、影響を受けたファイルと置換された文字列を示す replacements プロパティが JSON 出力に含まれます。
人間が読み取り可能な出力である force:source:push には、文字列置換情報がデフォルトで表示されます。この情報を削除するには、--quiet を使用してください。これにより、JSON 出力からもこの情報が削除されます。
人間が読み取り可能な出力である force:source:deploy に文字列置換情報を表示するには、--verbose を指定してください。
考慮事項と制限
- 複数の文字列置換を複数のファイルで行うように設定すると、リリースのパフォーマンスが低下することがあります。可能であれば、filename キーを使用して、開くファイルを 1 つだけにすることを検討してください。glob を使用する必要がある場合は、単一のディレクトリまたはメタデータ型を指定して、開くファイルの数を制限することを試みてください。
たとえば、"glob": "force-app/main/default/classes/*.cls" のように指定すると、特定のディレクトリ内の Apex クラスファイルが検索対象となります。すべてのパッケージディレクトリですべての Apex メタデータファイルを検索する "glob": "**/classes/**” よりも効率的です。
- 静的リソースで文字列置換を使用するときは注意してください。文字列置換を実行しない場合、Salesforce CLI は、最初にディレクトリを検出したときにすべての静的リソースを単純に zip して、そのままリリースします。大規模な静的リソースディレクトリに対して文字列置換を設定した場合、CLI は、通常より多くのファイルを検査する必要があり、パフォーマンス低下の原因になります。
- force:mdapi:deploy コマンドは、文字列置換をサポートしていません。
- リリースがタイムアウトになった後、または force:source:deploy で --wait 0 フラグを指定した後、force:source:deploy:report を実行して状況を確認すると、リリースされたファイルには、文字列置換が通常どおり含まれています。ただし、force:source:deploy:report の出力には、force:source:deploy --verbose の場合と同じ文字列置換情報は表示されません。