Odkazy na transformace souborů a nahrazení proměnných

Článek
04/04/2024

Azure DevOps Services | Azure DevOps Server 2022 – Azure DevOps Server 2019

Některé úlohy, jako je úloha nasazení služby Aplikace Azure service verze 3 a novější a úloha nasazení webové aplikace IIS, umožňují uživatelům konfigurovat balíček na základě zadaného prostředí. Tyto úlohy používají msdeploy.exe, které podporují přepsání hodnot v souboru web.config hodnotami ze souboru parameters.xml . Transformace souborů a nahrazení proměnných se ale neomezuje na soubory webové aplikace. Tyto techniky můžete použít s libovolnými soubory XML nebo JSON.

Poznámka:

Transformace souborů a nahrazení proměnných jsou podporovány také samostatnou úlohou Transformace souborů pro použití v Azure Pipelines. Úlohu Transformace souborů můžete použít k použití transformací souborů a nahrazení proměnných u všech souborů konfigurace a parametrů.

Náhrada konfigurace je zadána v části Možnosti transformace souboru a proměnné nastavení pro úlohy. Možnosti transformace a nahrazení jsou:

Transformace XML
Nahrazení proměnných XML
Nahrazení proměnných JSON

Při spuštění úlohy nejprve provede transformaci XML, nahrazení proměnných XML a nahrazení proměnných JSON v konfiguračních souborech a souborech parametrů. Dále vyvolá msdeploy.exe, který používá soubor parameters.xml k nahrazení hodnot v souboru web.config .

Transformace XML

Transformace XML podporuje transformaci konfiguračních souborů (*.configsouborů) pomocí syntaxe transformace Web.config a je založená na prostředí, do kterého se webový balíček nasadí. Tato možnost je užitečná, když chcete přidat, odebrat nebo upravit konfigurace pro různá prostředí. Transformace se použije pro jiné konfigurační soubory, včetně konfiguračních souborů konzoly nebo aplikace služby systému Windows (například FabrikamService.exe.config).

Zásady vytváření názvů souborů transformace konfigurace

Transformace XML se spustí v *.config souboru pro konfigurační soubory transformace pojmenované *.Release.config nebo *.<stage>.config se spustí v následujícím pořadí:

*.Release.config (například fabrikam. Release.config)
*.<stage>.config (například fabrikam. Production.config)

Pokud například balíček obsahuje následující soubory:

Soubor web.config
Web.debug.config
Web.Release.config
Web.Production.config

a název vaší fáze je Production, transformace se použije s Web.configWeb.Release.config následnou Web.Production.config.

Příklad transformace XML

Vytvořte balíček webové aplikace s potřebnou konfigurací a transformací souborů. Použijte například následující konfigurační soubory:

Konfigurační soubor

<?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>

Transformovat soubor

<?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>

Tento příklad transformační konfigurační soubor dělá tři věci:

Přidá do elementu ConnectionStrings novou databázi připojovací řetězec.
Upraví hodnotu Webpages:Enabled uvnitř appSettings prvku.
Odebere debug atribut z elementu compilation uvnitř elementu System.Web .

Další informace naleznete v tématu Syntaxe transformace Web.config pro nasazení webového projektu pomocí sady Visual Studio.

Vytvořte kanál verze s fází s názvem Release.
Přidejte úlohu nasazení služby Aplikace Azure a nastavte (zaškrtněte) možnost transformace XML.
Uložte kanál verze a spusťte novou verzi.

Web.config Otevřete soubor, abyste viděli transformace z 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>

Poznámky k transformaci XML

Pomocí této techniky můžete vytvořit výchozí balíček a nasadit ho do několika fází.
Transformace XML se projeví pouze v případech, kdy konfigurační soubor a transformační soubor jsou ve stejné složce v rámci zadaného balíčku.
Ve výchozím nastavení nástroj MSBuild použije transformaci, protože vygeneruje webový balíček, pokud <DependentUpon> prvek již existuje v transformačním souboru v *.csproj souboru. V takových případech úloha nasazení služby Aplikace Azure selže, protože v Web.config souboru se nepoužije žádná další transformace. Proto se doporučuje, aby <DependentUpon> byl prvek odebrán ze všech transformačních souborů, aby při použití transformace XML zakázal jakoukoli konfiguraci sestavení.

Nastavte vlastnost Akce sestavení pro každý z transformačních souborů (Web.config) na Obsah tak, aby se soubory zkopírovaly do kořenové složky.

...
<Content Include="Web.Debug.config">
   <DependentUpon>Web.config</DependentUpon>
</Content>
<Content Include="Web.Release.config">
   <DependentUpon>Web.config</DependentUpon>
</Content>
...

Nahrazení proměnných XML

Tato funkce umožňuje upravit nastavení konfigurace v konfiguračních souborech (*.config souborech) uvnitř webových balíčků a souborů parametrů XML (parameters.xml). Tímto způsobem lze stejný balíček nakonfigurovat na základě prostředí, do kterého se nasadí.

Nahrazení proměnných se projeví pouze na applicationSettings, appSettings, connectionStringsa configSections prvky konfiguračních souborů. Pokud chcete nahradit hodnoty mimo tyto prvky, můžete použít soubor (parameters.xml), ale k zpracování nahrazení proměnné budete muset použít úlohu kanálu třetí strany.

Příklad nahrazení proměnných XML

Jako příklad zvažte úlohu změny následujících hodnot v 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>

Vytvořte kanál verze s fází s názvem Release.
Přidejte úlohu nasazení služby Aplikace Azure a nastavte (zaškrtněte) možnost nahrazení proměnné XML.

Definujte požadované hodnoty v proměnných kanálu verze:

Jméno	Hodnota	Zabezpečení	Obor
Výchozí Připojení ion	Zdroj dat=(ProdDB)\MSSQLProdDB; AttachFileName=Local.mdf	No	Verze
AdminUserName	Prod Správa Name	No	Verze
AdminPassword	[vaše heslo]	Ano	Verze
invariantName	System.Data.SqlClientExtension	No	Verze

Uložte kanál verze a spusťte novou verzi.

Web.config Otevřete soubor a prohlédněte si nahrazení proměnných.

<?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>

Poznámky k nahrazení proměnných XML

Ve výchozím nastavení mají aplikace ASP.NET výchozí parametrizovaný atribut připojení. Tyto hodnoty jsou přepsány pouze v parameters.xml souboru uvnitř webového balíčku.
Vzhledem k tomu, že nahrazení nastane před nasazením, může uživatel přepsat hodnoty v Web.config použití parameters.xml (uvnitř webového setparameters balíčku) nebo souboru.

Nahrazení proměnných JSON

Tato funkce nahrazuje hodnoty v konfiguračních souborech JSON. Přepíše hodnoty v zadaných konfiguračních souborech JSON (například appsettings.json) hodnotami odpovídajícími názvy kanálů verze a proměnných fáze.

Pokud chcete nahradit proměnné v konkrétních souborech JSON, zadejte seznam souborů JSON oddělených novým řádekem. Názvy souborů musí být zadány vzhledem ke kořenové složce. Pokud má váš balíček například tuto strukturu:

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

a chcete nahradit hodnoty v appsettings.json, zadejte relativní cestu z kořenové složky, například content/website/appsettings.json. Alternativně můžete k vyhledání konkrétních souborů JSON použít vzory se zástupnými znaky. Vrátí například **/appsettings.json relativní cestu a název souborů s názvem appsettings.json.

Příklad nahrazení proměnných JSON

Jako příklad zvažte úlohu přepsání hodnot v tomto souboru 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"
        }
      ]
    }
  }
}

Úkolem je přepsat hodnoty Připojení ionString, DebugMode, první z hodnot Users a NewWelcomeMessage na příslušných místech v hierarchii souborů JSON.

Klasické
YAML

Vytvořte kanál verze s fází s názvem Release.
Přidejte úlohu nasazení služby Aplikace Azure a zadejte seznam souborů JSON oddělených novým řádekem a nahraďte hodnoty proměnných v textovém poli nahrazení proměnné JSON. Názvy souborů musí být relativní vzhledem ke kořenové složce. Pomocí zástupných znaků můžete hledat soubory JSON. Příklad: **/*.json Znamená nahrazení hodnot ve všech souborech JSON v balíčku.

Definujte požadované hodnoty nahrazení v kanálech verze nebo proměnných fáze.

Jméno	Hodnota	Zabezpečení	Obor
Data.DebugMode	deaktivováno	No	Verze
Data.Default Připojení ion.PřipojeníionString	Zdroj dat=(prodDB)\MSDB; AttachDbFilename=prod.mdf;	No	Verze
Data.DBAccess.Users.0	Správa-3	Ano	Verze
Data.FeatureFlags.Preview.1.NewWelcomeMessage	AllAccounts	No	Verze

Uložte kanál verze a spusťte novou verzi.

Po transformaci bude JSON obsahovat následující:

{
  "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"
        }
      ]
    }
  }
}
'''

Následující fragment kódu YAML předvádí nahrazení proměnných 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

Poznámky k nahrazení proměnných JSON

Pokud chcete nahradit hodnoty ve vnořených úrovních souboru, zřetězte názvy tečkou (.) v hierarchickém pořadí.
Objekt JSON může obsahovat pole, jehož hodnoty mohou být odkazovány jejich indexem. Pokud chcete například nahradit první hodnotu v poli Users uvedeném výše, použijte název DBAccess.Users.0proměnné . Chcete-li aktualizovat hodnotu v NewWelcomeMessage, použijte název FeatureFlags.Preview.1.NewWelcomeMessageproměnné . Úloha transformace souborů ale má možnost transformovat celá pole v souborech JSON. Můžete také použít DBAccess.Users = ["NewUser1","NewUser2","NewUser3"].
Pro nahrazení proměnných JSON se podporuje pouze náhrada řetězce .
Náhrada je podporována pouze u souborů s kódováním UTF-8 a UTF-16 LE.
Pokud zadaná specifikace souboru neodpovídá žádnému souboru, úloha selže.
Porovnávání názvů proměnných se rozlišují malá a velká písmena.
Nahrazení proměnných se použije pouze pro klíče JSON předdefinované v hierarchii objektů. Nevytvoří nové klíče.
Pokud název proměnné obsahuje tečky ("."), transformace se pokusí vyhledat položku v hierarchii. Pokud je first.second.thirdnapříklad název proměnné, proces transformace vyhledá:
```
"first" : {
  "second": {
    "third" : "value"
  }
}
```
a také "first.second.third" : "value".

Share via