リリース前のコードの文字列の置換

文字列置換の設定

文字列置換を設定するには、sfdx-project.json ファイルに replacements プロパティを追加します。このプロパティは、次を定義するキーから構成された複数のエントリを受け入れます。

• 置換される文字列を含む 1 つ以上のソースファイル。
• 置換される文字列。
• 置換する値。

1{
2  "packageDirectories": [
3     {
4       "path": "force-app",
5       "default": true
6     }
7  ],
8  "name": "myproj",
9  "replacements": [
10    {
11      "filename": "force-app/main/default/classes/myClass.cls",
12      "stringToReplace": "replaceMe",
13      "replaceWithEnv": "THE_REPLACEMENT"  
14    }
15  ]
16}

replacements プロパティでは、次のキーを指定できます。

ファイルの場所

次のプロパティのいずれかが必要です。

• filename: 置換される文字列を含む単一のファイル。
• glob: 置換される文字列を含むファイルのコレクション。例: **/classes/*.cls。

置換される文字列

次のプロパティのいずれかが必要です。

• stringToReplace: 置換される文字列。
• regexToReplace: 置換される文字列パターンを指定する正規表現 (regex)。

置換する値

次のプロパティのいずれかが必要です。

• replaceWithEnv: 文字列を特定の環境変数の値に置換するように指定します。
• replaceWithFile: 文字列をファイルの内容に置換するように指定します。

条件付き処理

これらのプロパティは省略可能です。

• replaceWhenEnv: 特定の環境変数��特定の値に設定された場合にのみ文字列を置換することを指定します。環境変数を指定するには env プロパティ、文字列の置換をトリガする値を指定するには value プロパティを使用します。
• allowUnsetEnvVariable: replaceWithEnv プロパティとともに使用する Boolean プロパティ。true に設定することで、replaceWithEnv 環境変数が設定されていない場合に、リリース前にファイルから置換文字列が削除されます。言い換えると、置換では何も置き換えられません。false (デフォルト値) に設定した場合、replaceWithEnv 環境変数が設定されていないときにエラーが発生します。

次の構文規則に従います。

• Windows の場合でも、ディレクトリには必ずスラッシュ (/) を使用します。
• バックスラッシュ (\) は、JSON と正規表現の両方でエスケープ文字として使用されます。このため、エスケープが必要なドットを正規表現を使用して突き合わせるには、regexToReplace の値に 2 つのバックスラッシュを使用する必要があります。
  1"regexToReplace" : "\\."

  同様に、単一のバックスラッシュを突き合わせるには、3 つのバックスラッシュを指定する必要があります。

  1"regexToReplace" : "\\\"

例

1"replacements": [
2  {
3    "filename": "force-app/main/default/classes/FirstApexClass.cls",
4    "stringToReplace": "replaceMe",
5    "replaceWithEnv": "THE_REPLACEMENT"
6  },
7  {
8    "filename": "force-app/main/default/classes/SecondApexClass.cls",
9    "stringToReplace": "replaceMe",
10    "replaceWithEnv": "THE_REPLACEMENT"
11  }
12]

次の例は、環境変数 DEPLOY_DESTINATION が存在し、その値が PROD である場合にのみ文字列を置換するように指定する方法を示しています。

1"replacements": [
2  {
3    "filename": "force-app/main/default/classes/myClass.cls",
4    "stringToReplace": "replaceMe",
5    "replaceWithEnv": "THE_REPLACEMENT",
6    "replaceWhenEnv": [{
7      "env": "DEPLOY_DESTINATION",
8      "value": "PROD"
9    }]  
10  }
11]

この例では、環境変数 SOME_ENV_THAT_CAN_BE_BLANK が設定されていない場合、ファイルのリリース時に myClass.cls ファイル内の文字列 myNS__ が削除されます。環境変数に値が設定されている場合は、その値が myNS__ の文字列に置き換えられます。

1"replacements": [
2    {
3      "filename": "/force-app/main/default/classes/myClass.cls",
4      "stringToReplace": "myNS__",
5      "replaceWithEnv": "SOME_ENV_THAT_CAN_BE_BLANK",
6      "allowUnsetEnvVariable": true
7    }
8  ]

次の例では、force-app/main/default ディレクトリ内の Apex クラスファイルのリリース時に、出現する replaceMe という文字列をすべて replacementFiles/copyright.txt ファイルの内容に置き換えることが指定されています。

1"replacements": [
2  {
3    "glob": "force-app/main/default/classes/*.cls",
4    "stringToReplace": "replaceMe",
5    "replaceWithFile": "replacementFiles/copyright.txt"
6  }
7]

1<?xml version="1.0" encoding="UTF-8" ?>
2<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
3    <apiVersion>55.0</apiVersion>
4    <status>Active</status>
5</ApexClass>

1"replacements": [
2  {
3    "glob": "force-app/main/default/classes/*.xml",
4    "regexToReplace": "<apiVersion>\\d+\\.0</apiVersion>",
5    "replaceWithFile": "replacementFiles/latest-api-version.txt"
6  }
7]

文字列置換のテスト

ファイルを実際に組織にリリースせずに文字列置換をテストするには、次の手順を実行します。

1. SF_APPLY_REPLACEMENTS_ON_CONVERT 環境変数を true に設定します。
2. project convert source コマンドを実行します。ソースファイルがメタデータ API 形式に変換されます。次に例を示します。
   1sf project convert source --output-dir mdapiOut --source-dir force-app

3. 出力ディレクトリ (この例では mdapiOut) のファイルを検査し、文字列置換と組織にリリースされる正確な内容を確認します。

ヒントとコツ

• (macOS または Linux のみ) replaceWithEnv または replaceWhenEnv プロパティを使用するときは、コマンドを実行する前に環境変数を先頭に追加して、その環境変数を単一のコマンドに適用することを指定できます。次に例を示します。
  1THE_REPLACEMENT="some text" DEPLOY_DESTINATION=PROD sf project deploy start

  パスワードや秘密は、ターミナルの履歴に表示されるため、このような方法で設定するときは注意してください。

  警告

• 設定した文字列置換が多く、その管理が難しい場合は、1 つ以上のファイルの内容を環境に読み込むオープンソースツール (dotenv-cli など) を調べてください。この例の場合、2 つのローカル .env ファイルで設定されている環境変数は、project deploy start コマンドの実行前に読み込まれます。
  1dotenv -e .env1 -e .env2 sf project deploy start

  パスワードや秘密は、.env ファイルでコミットしないでください。

  警告

• project deploy start に --json を指定した場合は、影響を受けたファイルと置換された文字列を示す replacements プロパティが JSON 出力に含まれます。--json と --concise を指定すると、JSON 出力には replacements プロパティが含まれません。

  人間が読み取り可能な出力である project deploy start に文字列置換情報を表示するには、--verbose を指定してください。

考慮事項と制限

• 複数の文字列置換を複数のファイルで行うように設定すると、リリースのパフォーマンスが低下することがあります。可能であれば、filename キーを使用して、開くファイルを 1 つだけにすることを検討してください。glob を使用する必要がある場合は、単一のディレクトリまたはメタデータ型を指定して、開くファイルの数を制限することを試みてください。

  たとえば、"glob": "force-app/main/default/classes/*.cls" のように指定すると、特定のディレクトリ内の Apex クラスファイルが検索対象となります。すべてのパッケージディレクトリですべての Apex メタデータファイルを検索する "glob": "**/classes/**” よりも効率的です。

• 静的リソースで文字列置換を使用するときは注意してください。文字列置換を実行しない場合、Salesforce CLI は、最初にディレクトリを検出したときにすべての静的リソースを単純に zip して、そのままリリースします。大規模な静的リソースディレクトリに対して文字列置換を設定した場合、CLI は、通常より多くのファイルを検査する必要があり、パフォーマンス低下の原因になります。
• project deploy start --metadata-dir コマンドのように、メタデータ形式でリリースする場合、文字列置換は使用できません。
• リリースがタイムアウトになった後、または project deploy start で --async フラグを指定した後に、project deploy resume または project deploy report を実行して状況を確認すると、リリースされたファイルには、文字列置換が通常どおり含まれています。ただし、project deploy resume および project deploy report の出力には、project deploy start --verbose の場合と同じ文字列置換情報は表示されません。