ファイル変換と変数置換リファレンス

[アーティクル]
04/05/2024

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Azure App Service デプロイタスクバージョン 3 以降や IIS Web アプリデプロイタスクなどの一部のタスクでは、ユーザーは指定された環境に基づいてパッケージを構成できます。これらのタスクでは msdeploy.exe を使用します。これは、parameters.xml ファイルの値による web.config ファイルの値のオーバーライドをサポートします。ただし、ファイル変換と変数置換は、Web アプリファイルに限定されません。これらの手法を XML または JSON ファイルで使用できます。

注意

また、Azure Pipelines で使用する個別のファイル変換タスクでは、ファイル変換と変数の置換もサポートされています。ファイル変換タスクを使用することで、任意の構成とパラメーターの各ファイルにファイル変換と変数の置換を適用できます。

構成の置換は、タスクの設定の [ファイル変換と変数置換オプション] セクションで指定します。変換と置換のオプションは次のとおりです。

XML 変換
XML 変数置換
JSON 変数置換

タスクが実行されると、まず、構成ファイルとパラメーターファイルで XML 変換、XML 変数置換、JSON 変数置換が実行されます。次に、msdeploy.exe が呼び出され、parameters.xml ファイルを使用して web.confi ファイルの値が置換されます。

XML 変換

XML 変換は、Web.config 変換構文に従うことによって構成ファイル (*.config ファイル) の変換をサポートし、Web パッケージがデプロイされる環境に基づきます。このオプションは、さまざまな環境の構成を追加、削除、または変更する場合に便利です。変換は、コンソールや Windows サービスアプリケーションの構成ファイル (例: FabrikamService.exe.config) などの他のファイルに適用されます。

構成変換ファイルの名前付け規則

XML 変換は、*.Release.config または *.<stage>.config という名前の変換構成用の *.config ファイルで実行され、実行順序は次のとおりです。

*.Release.config (fabrikam.Release.config など)
*.<stage>.config (fabrikam.Production.config など)

たとえば、ソースファイルに次のファイルが含まれていて、

web.config
Web.Debug.Config
Web.Release.Config
Web.Production.config

ステージ名が Production の場合、変換は Web.Release.config 続いて Web.Production.config を使用して Web.config に適用されます。

XML 変換の例

必要な構成と変換ファイルを含む Web アプリケーションパッケージを作成します。たとえば、次の構成ファイルを使用します。

構成ファイル

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <connectionStrings>
    <add name="DefaultConnection"
         connectionString="Data Source=(LocalDb)\\MSDB;DbFilename=aspcore-local.mdf;" />
  </connectionStrings>
  <appSettings>
    <add key="webpages:Version" value="3.0.0.0" />
    <add key="webpages:Enabled" value="false" />
  </appSettings>
  <system.web>
    <authentication mode="None" />
    <compilation targetFramework="4.5" debug="true" />
  </system.web>
</configuration>

[変換ファイル]

<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
    <connectionStrings>
      <add name="MyDB"
           connectionString="Data Source=ReleaseSQLServer;Initial Catalog=MyReleaseDB;Integrated Security=True"
           xdt:Transform="Insert" />
    </connectionStrings>
  <appSettings>
    <add xdt:Transform="Replace" xdt:Locator="Match(key)" key="webpages:Enabled" value="true" />
  </appSettings>
  <system.web>
    <compilation xdt:Transform="RemoveAttributes(debug)" />
  </system.web>
</configuration>

この変換構成ファイルの例では、次の 3 つの処理を行います。

ConnectionStrings 要素内に新しいデータベース接続文字列を追加します。
appSettings 要素内の Webpages:Enabled の値を変更します。
System.Web 要素内の compilation 要素から debug 属性を削除します。

詳細については、Visual Studio を使用する Web プロジェクトデプロイの Web.config 変換構文に関するページを参照してください

Release という名前のステージを使用してリリースパイプラインを作成します。
Azure App Service デプロイ タスクを追加し、[XML 変換] オプションを設定します (チェックを付けます)。
リリースパイプラインを保存し、新しいリリースを起動します。

Web.config ファイルを開き、Web.Release.config からの変換を確認します。

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <connectionStrings>
    <add name="DefaultConnection"
         connectionString="Data Source=(LocalDb)\\MSDB;DbFilename=aspcore-local.mdf;" />
  <add name="MyDB"
       connectionString="Data Source=ReleaseSQLServer;Initial Catalog=MyReleaseDB;Integrated Security=True" />
  </connectionStrings>
  <appSettings>
    <add key="webpages:Version" value="3.0.0.0" />
    <add key="webpages:Enabled" value="true" />
  </appSettings>
  <system.web>
    <authentication mode="None" />
    <compilation targetFramework="4.5" />
  </system.web>
</configuration>

XML 変換に関する注意事項

この手法を使用して、既定のパッケージを作成し、複数のステージにデプロイできます。
XML 変換は、構成ファイルと変換ファイルが指定されたパッケージ内の同じフォルダーにある場合にのみ有効になります。
既定では、MSBuild は、<DependentUpon> 要素が *.csproj ファイル内の変換ファイルに既に存在する場合、Web パッケージを生成するときに変換を適用します。このような場合、Web.config ファイルで適用される変換はなくなるため、Azure App Service デプロイ タスクは失敗します。したがって、XML 変換を使用する場合は、<DependentUpon> 要素をすべての変換ファイルから削除してビルド時の構成を無効にすることをお勧めします。
各変換ファイル (Web.config) の [ビルドアクション] プロパティを [コンテンツ] に設定して、ファイルがルートフォルダーにコピーされるようにします。
```
...
<Content Include="Web.Debug.config">
   <DependentUpon>Web.config</DependentUpon>
</Content>
<Content Include="Web.Release.config">
   <DependentUpon>Web.config</DependentUpon>
</Content>
...
```

XML 変数置換

この機能を使用すると、Web パッケージと XML パラメーターファイル (parameters.xml) 内の構成ファイル (*.config ファイル) の構成設定を変更できます。この方法により、デプロイ先の環境に基づいて同じパッケージを構成できます。

変数置換は、構成ファイルの applicationSettings、appSettings、connectionStrings、および configSections 要素でのみ有効です。これらの要素の外部で値を置き換える場合は、(parameters.xml) ファイルを使用できますが、変数置換を処理するにはサードパーティのパイプラインタスクを使用する必要があります。

XML 変数置換の例

例として、Web.config で次の値を変更するタスクを考えてみましょう。

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <configSection>
        <section name="entityFramework" />
    </configSection>
    <connectionStrings>
        <!-- Change connectionString in this line: --> 
        <add name="DefaultConnection"
             connectionString="Data Source=(LocalDB)\LocalDB;FileName=Local.mdf" />
    </connectionStrings>
    <appSettings>
        <add key="ClientValidationEnabled" value="true" />
        <add key="UnobstructiveJavascriptEnabled" value="true" />
        <!-- Change AdminUserName in this line: --> 
        <add key="AdminUserName" value="__AdminUserName__" />
        <!-- Change AdminPassword in this line: --> 
        <add key="AdminPassword" value="__AdminPassword__" />
    </appSettings>
    <entityFramework>
        <defaultConnectionFactory type="System.Data.Entity.LocalDbConnectionFactory">
            <parameters></parameters>
        </defaultConnectionFactory>
        <providers>
            <!-- Change invariantName in this line: --> 
            <provider invariantName="System.Data.SqlClient" type="System.Data.Entity.SqlServer" />
        </providers>
    </entityFramework>
</configuration>

Release という名前のステージを使用してリリースパイプラインを作成します。
Azure App Service デプロイ タスクを追加し、[XML 変数置換] オプションを設定します (チェックを付けます)。

リリースパイプライン変数で必要な値を定義します。

Name	値	セキュリティで保護	Scope
DefaultConnection	Data Source=(ProdDB)\MSSQLProdDB;AttachFileName=Local.mdf	No	リリース
AdminUserName	ProdAdminName	No	リリース
AdminPassword	[自分のパスワード]	はい	リリース
invariantName	System.Data.SqlClientExtension	No	リリース

リリースパイプラインを保存し、新しいリリースを起動します。

Web.config ファイルを開き、変数置換を確認します。

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <configSection>
        <section name="entityFramework" />
    </configSection>
    <connectionStrings>
        <add name="DefaultConnection"
             connectionString="Data Source=(ProdDB)\MSSQLProdDB;AttachFileName=Local.mdf" />
    </connectionStrings>
    <appSettings>
        <add key="ClientValidationEnabled" value="true" />
        <add key="UnobstructiveJavascriptEnabled" value="true" />
        <add key="AdminUserName" value="ProdAdminName" />
        <add key="AdminPassword" value="*password_masked_for_display*" />
    </appSettings>
    <entityFramework>
        <defaultConnectionFactory type="System.Data.Entity.LocalDbConnectionFactory">
            <parameters></parameters>
        </defaultConnectionFactory>
        <providers>
            <provider invariantName="System.Data.SqlClientExtension"
                      type="System.Data.Entity.SqlServer" />
        </providers>
    </entityFramework>
</configuration>

XML 変数置換に関する注意事項

既定では、ASP.NET アプリケーションには既定のパラメーター化された接続属性があります。これらの値は、Web パッケージ内の parameters.xml ファイルでのみオーバーライドされます。
置換はデプロイ前に行われるため、ユーザーは parameters.xml (Web パッケージ内) または setparameters ファイルを使用して Web.config 内の値をオーバーライドできます。

JSON 変数置換

この機能は、JSON 構成ファイルの値を置き換えます。指定した JSON 構成ファイル (appsettings.json など) の値をリリースパイプラインおよびステージ変数の名前が一致する値でオーバーライドします。

特定の JSON ファイル内の変数を置き換えるには、JSON ファイルの改行で区切られたリストを指定します。ファイル名は、ルートフォルダーを基準にして指定する必要があります。たとえば、パッケージに次の構造が含まれていて、

/WebPackage(.zip)
  /---- content
    /----- website
      /---- appsettings.json
      /---- web.config
      /---- [other folders] 
  /--- archive.xml
  /--- systeminfo.xml

appsettings.json の値を置き換える場合、ルートフォルダーからの相対パスを入力します (content/website/appsettings.json など)。または、ワイルドカードパターンを使用して特定の JSON ファイルを検索します。たとえば、**/appsettings.json は appsettings.json という名前のファイルの相対パスと名前を返します。

JSON 変数置換の例

例として、この JSON ファイルの値をオーバーライドするタスクを考えてみましょう。

{
  "Data": {
    "DefaultConnection": {
      "ConnectionString": "Data Source=(LocalDb)\\MSDB;AttachDbFilename=aspcore-local.mdf;"
    },
    "DebugMode": "enabled",
    "DBAccess": {
      "Administrators": ["Admin-1", "Admin-2"],
      "Users": ["Vendor-1", "vendor-3"]
    },
    "FeatureFlags": {
      "Preview": [
        {
          "newUI": "AllAccounts"
        },
        {
          "NewWelcomeMessage": "Newusers"
        }
      ]
    }
  }
}

タスクは、ConnectionString、DebugMode の値、Users の値の 1 番目、および NewWelcomeMessage の値を JSON ファイル階層内のそれぞれの場所でオーバーライドします。

クラシック
YAML

Release という名前のステージを使用してリリースパイプラインを作成します。
Azure App Service デプロイ タスクを追加し、[JSON 変数置換] テキストボックスに変数値を置き換える JSON ファイルの改行で区切られたリストを入力します。ファイル名は、ルートフォルダーを基準にする必要があります。ワイルドカードを使用して JSON ファイルを検索できます。例: **/*.json は、パッケージ内のすべての JSON ファイルの値を置き換えることを意味します。

リリースパイプラインまたはステージ変数で必要な置換値を定義します。

Name	値	セキュリティで保護	Scope
Data.DebugMode	disabled	No	リリース
Data.DefaultConnection.ConnectionString	Data Source=(prodDB)\MSDB;AttachDbFilename=prod.mdf;	No	リリース
Data.DBAccess.Users.0	Admin-3	はい	リリース
Data.FeatureFlags.Preview.1.NewWelcomeMessage	AllAccounts	No	リリース

リリースパイプラインを保存し、新しいリリースを起動します。

変換後、JSON の内容は次のようになります。

{
  "Data": {
    "DefaultConnection": {
      "ConnectionString": "Data Source=(prodDB)\MSDB;AttachDbFilename=prod.mdf;"
    },
    "DebugMode": "disabled",
    "DBAccess": {
      "Administrators": ["Admin-1", "Admin-2"],
      "Users": ["Admin-3", "vendor-3"]
    },
    "FeatureFlags": {
      "Preview": [
        {
          "newUI": "AllAccounts"
        },
        {
          "NewWelcomeMessage": "AllAccounts"
        }
      ]
    }
  }
}
'''

次の YAML スニペットは、JSON 変数置換を示しています。

variables:
  Data.DebugMode: disabled
  Data.DefaultConnection.ConnectionString: 'Data Source=(prodDB)\MSDB;AttachDbFilename=prod.mdf;'
  Data.DBAccess.Users.0: Admin-3
  Data.FeatureFlags.Preview.1.NewWelcomeMessage: AllAccounts

# Update appsettings.json via FileTransform task.
- task: FileTransform@1
  displayName: 'File transformation: appsettings.json'
  inputs:
    folderPath: '$(Build.ArtifactStagingDirectory)/$(Build.BuildId).zip'
    targetFiles: '**/appsettings.json'
    fileType: json
  
# Deploy web app
- task: AzureWebApp@1
  inputs:
    azureSubscription: <Name of the Azure subscription>
    appName: <Name of the Azure WebApp>
    package: $(Build.ArtifactStagingDirectory)/$(Build.BuildId).zip

JSON 変数置換に関する注意事項

ファイルの入れ子レベルにある値を置き換えるには、名前を階層順にピリオド (.) で連結します。
JSON オブジェクトには、値をインデックスによって参照できる配列が含まれる場合があります。たとえば、上に示した Users 配列の最初の値を置き換えるには、変数名 DBAccess.Users.0 を使用します。 NewWelcomeMessage の値を更新するには、変数名 FeatureFlags.Preview.1.NewWelcomeMessage を使用します。ただし、ファイル変換タスクには、JSON ファイル内の配列全体を変換する機能があります。 DBAccess.Users = ["NewUser1","NewUser2","NewUser3"] を使用することもできます。
JSON 変数置換では、文字列置換のみがサポートされています。
置換は、UTF-8 および UTF-16 LE でエンコードされたファイルでのみサポートされます。
入力したファイル仕様がファイルと一致しない場合、タスクは失敗します。
変数名の一致では大文字と小文字が区別されます。
変数の置換は、オブジェクト階層で定義済みの JSON キーにのみ適用されます。新しいキーは作成されません。
変数名にピリオド (".") が含まれている場合、変換によって階層内で項目の検索が試みられます。たとえば、変数名が first.second.third の場合、変換プロセスは次を検索し、
```
"first" : {
  "second": {
    "third" : "value"
  }
}
```
"first.second.third" : "value" も検索します。