Fájlátalakítások és változóhelyettesítési referencia

Cikk
04/04/2024

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

Egyes feladatok, például a Azure-alkalmazás Szolgáltatás üzembe helyezése 3. és újabb verzió, valamint az IIS Web App Deploy feladat lehetővé teszik, hogy a felhasználók a megadott környezet alapján konfigurálják a csomagot. Ezek a feladatok msdeploy.exe használnak, amely támogatja a web.config fájl értékeinek felülírását a parameters.xml fájl értékeivel. A fájlátalakítások és a változók helyettesítése azonban nem korlátozódik webalkalmazás-fájlokra. Ezeket a technikákat bármilyen XML- vagy JSON-fájllal használhatja.

Feljegyzés

A fájlátalakításokat és a változók helyettesítését a különálló Fájlátalakítási feladat is támogatja az Azure Pipelinesban való használatra. A Fájlátalakítás feladat használatával fájlátalakításokat és változóhelyettesítéseket alkalmazhat bármilyen konfigurációs és paraméterfájlra.

A konfigurációs helyettesítés a feladatok beállításainak Fájlátalakítás és változóhelyettesítési beállításai szakaszában van megadva. Az átalakítás és a helyettesítési lehetőségek a következők:

XML-átalakítás
XML-változó helyettesítése
JSON-változó helyettesítése

A feladat futtatásakor először XML-átalakítást, XML-változó-helyettesítést és JSON-változó-helyettesítést végez a konfigurációs és paraméterfájlokon. Ezután meghívja a msdeploy.exe, amely a parameters.xml fájlt használja a web.config fájl értékeinek helyettesítésére.

XML-átalakítás

Az XML-átalakítás támogatja a konfigurációs fájlok (*.configfájlok) átalakítását a Web.config Átalakítási szintaxis követésével, és a webcsomag üzembe helyezésének környezetén alapul. Ez a beállítás akkor hasznos, ha különböző környezetek konfigurációit szeretné hozzáadni, eltávolítani vagy módosítani. Az átalakítás más konfigurációs fájlokra is vonatkozik, beleértve a konzol- vagy Windows-szolgáltatásalkalmazás konfigurációs fájljait (például FabrikamService.exe.config).

Konfigurációátalakítási fájlelnevezési konvenciók

Az XML-átalakítás a fájlon lesz futtatva a *.config névvel ellátott *.Release.config átalakítási konfigurációs fájlokhoz, vagy *.<stage>.config a következő sorrendben lesz végrehajtva:

*.Release.config (például fabrikam. Release.config)
*.<stage>.config (például fabrikam. Production.config)

Ha például a csomag a következő fájlokat tartalmazza:

Web.config
Web.Debug.config
Web.Release.config
Web.Production.config

és a szakasz neve Production, a transzformációt a program a következővel Web.Production.configWeb.Release.config alkalmazzaWeb.config: .

PÉLDA XML-átalakításra

Hozzon létre egy webalkalmazás-csomagot a szükséges konfigurációval és fájlok átalakításával. Használja például a következő konfigurációs fájlokat:

Konfigurációs fájl

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

Fájl átalakítása

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

Ez a példa átalakító konfigurációs fájl három dolgot tesz:

Hozzáad egy új adatbázist kapcsolati sztring az ConnectionStrings elemen belül.
Módosítja az elemen Webpages:Enabled belüli appSettings értéket.
Eltávolítja az debug attribútumot az compilation elemen belüli System.Web elemből.

További információ: Web.config Átalakítási szintaxis webes projekt üzembe helyezéséhez a Visual Studióval

Hozzon létre egy Kiadás nevű szakaszt tartalmazó kiadási folyamatot.
Adjon hozzá egy Azure-alkalmazás Service Deploy feladatot, és állítsa be (jelölje be) az XML-átalakítási beállítást.
Mentse a kiadási folyamatot, és indítsa el az új kiadást.

Nyissa meg a fájlt az Web.config átalakítások Web.Release.configmegtekintéséhez.

<?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-átalakítási megjegyzések

Ezzel a technikával létrehozhat egy alapértelmezett csomagot, és több fázisban is üzembe helyezheti.
Az XML-átalakítás csak akkor lép érvénybe, ha a konfigurációs fájl és az átalakító fájl ugyanabban a mappában található a megadott csomagban.
Alapértelmezés szerint az MSBuild alkalmazza az átalakítást a webes csomag létrehozásakor, ha az <DependentUpon> elem már megtalálható a *.csproj fájl átalakító fájljában. Ilyen esetekben a Azure-alkalmazás szolgáltatás üzembe helyezése feladat meghiúsul, mert nincs további átalakítás a Web.config fájlon. Ezért javasoljuk, hogy az elemet eltávolítsa az <DependentUpon> összes átalakító fájlból, hogy az XML-átalakítás használatakor letiltsa a buildelési idő konfigurálását.

Állítsa az egyes átalakítási fájlok (Web.config) Build Action tulajdonságát Tartalom értékre, hogy a fájlok át legyenek másolva a gyökérmappába.

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

XML-változó helyettesítése

Ez a funkció lehetővé teszi a konfigurációs fájlok (*.config fájlok) konfigurációs beállításainak módosítását a webes csomagokban és az XML-paraméterek fájljaiban (parameters.xml). Ily módon ugyanaz a csomag konfigurálható azon környezet alapján, amelyre az üzembe lesz helyezve.

A változó-helyettesítés csak a applicationSettingskonfigurációs fájlokra appSettingsconnectionStringsés configSections elemekre lép érvénybe. Ha ezen elemeken kívül szeretne értékeket helyettesíteni, használhat egy (parameters.xml) fájlt, de a változó helyettesítésének kezeléséhez külső folyamatfeladatot kell használnia.

XML-változó helyettesítési példája

Példaként fontolja meg a következő értékek módosításának feladatát a következőben 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>

Hozzon létre egy Kiadás nevű szakaszt tartalmazó kiadási folyamatot.
Adjon hozzá egy Azure-alkalmazás Service Deploy feladatot, és állítsa be (jelölje be) az XML-változó helyettesítési beállítását.

Adja meg a kiadási folyamat változóiban a szükséges értékeket:

Név szerint	Érték	Biztonságossá tétel	Hatókör
Alapértelmezett Csatlakozás ion	Adatforrás=(ProdDB)\MSSQLProdDB; AttachFileName=Local.mdf	Nem	Felszabadítás
AdminUserName	Prod Rendszergazda Name	Nem	Felszabadítás
AdminPassword	[az Ön jelszava]	Igen	Felszabadítás
invariantName	System.Data.SqlClientExtension	Nem	Felszabadítás

Mentse a kiadási folyamatot, és indítsa el az új kiadást.

Nyissa meg a fájlt a Web.config változóhelyettesítések megtekintéséhez.

<?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-változó helyettesítési megjegyzései

Alapértelmezés szerint ASP.NET alkalmazások alapértelmezett paraméteres kapcsolatattribútummal rendelkeznek. Ezeket az értékeket csak a parameters.xml webes csomagban lévő fájl bírálja felül.
Mivel a helyettesítés az üzembe helyezés előtt történik, a felhasználó felülbírálhatja a használatban parameters.xml lévő értékeket (a webcsomagon belül) vagy egy fájlban.Web.config setparameters

JSON-változó helyettesítése

Ez a funkció a JSON-konfigurációs fájlok értékeit helyettesíti. Felülbírálja a megadott JSON-konfigurációs fájlok értékeit (például appsettings.json) a kiadási folyamat és a fázisváltozók nevének megfelelő értékekkel.

Az egyes JSON-fájlok változóinak helyettesítéséhez adja meg a JSON-fájlok új vonallal tagolt listáját. A fájlneveket a gyökérmappához viszonyítva kell megadni. Ha például a csomag struktúrája a következő:

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

és a appsettings.json értékeket szeretné helyettesíteni, írja be a relatív elérési utat a gyökérmappából, példáulcontent/website/appsettings.json. Helyettesítő karaktereket is használhat adott JSON-fájlok kereséséhez. Visszaadja például **/appsettings.json a appsettings.json nevű fájlok relatív elérési útját és nevét.

JSON-változó helyettesítési példája

Vegyük példaként a JSON-fájl értékeinek felülírásának feladatát:

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

A feladat felülbírálja a Csatlakozás ionString, a DebugMode, a Felhasználók első értékei és a NewWelcomeMessage értékeit a JSON-fájlhierarchiában lévő megfelelő helyeken.

Klasszikus
YAML

Hozzon létre egy Kiadás nevű szakaszt tartalmazó kiadási folyamatot.
Adjon hozzá egy Azure-alkalmazás Service Deploy feladatot, és adja meg a JSON-fájlok új vonallal elválasztott listáját a JSON változóhelyettesítési szövegmező változóértékeinek helyettesítéséhez. A fájlneveknek a gyökérmappához viszonyítva kell lenniük. A JSON-fájlok kereséséhez helyettesítő karaktereket használhat. Például: **/*.json a csomagban lévő összes JSON-fájlban helyettesítő értékeket jelent.

Adja meg a szükséges helyettesítési értékeket a kiadási folyamatban vagy a fázisváltozókban.

Név szerint	Érték	Biztonságossá tétel	Hatókör
Data.DebugMode	letiltva	Nem	Felszabadítás
Data.Default Csatlakozás ion.CsatlakozásionString	Adatforrás=(prodDB)\MSDB; AttachDbFilename=prod.mdf;	Nem	Felszabadítás
Data.DBAccess.Users.0	Rendszergazda-3	Igen	Felszabadítás
Data.FeatureFlags.Preview.1.NewWelcomeMessage	AllAccounts	Nem	Felszabadítás

Mentse a kiadási folyamatot, és indítsa el az új kiadást.

Az átalakítás után a JSON a következőket fogja tartalmazni:

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

A KÖVETKEZŐ YAML-kódrészlet bemutatja a JSON-változó helyettesítését.

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-változó helyettesítési megjegyzései

A fájl beágyazott szintjeiben lévő értékek helyettesítéséhez fűzze össze a neveket egy ponttal (.) hierarchikus sorrendben.
A JSON-objektumok tartalmazhatnak olyan tömböt, amelynek értékeire az indexük hivatkozhat. Ha például a Fent látható Felhasználók tömb első értékét szeretné lecserélni, használja a változó nevétDBAccess.Users.0. A NewWelcomeMessage értékének frissítéséhez használja a változó nevétFeatureFlags.Preview.1.NewWelcomeMessage. A fájlátalakítási feladat azonban képes teljes tömbök átalakítására JSON-fájlokban. A parancsot is használhatja DBAccess.Users = ["NewUser1","NewUser2","NewUser3"].
A JSON-változó helyettesítéséhez csak a sztring-helyettesítés támogatott.
A helyettesítés csak UTF-8 és UTF-16 LE kódolású fájlok esetében támogatott.
Ha a megadott fájlspecifikáció egyetlen fájlnak sem felel meg, a feladat sikertelen lesz.
A változónevek egyeztetése megkülönbözteti a kis- és nagybetűk megkülönböztetettségét.
A változó-helyettesítés csak az objektumhierarchiában előre definiált JSON-kulcsokra vonatkozik. Nem hoz létre új kulcsokat.
Ha egy változó neve tartalmaz pontokat ("."), az átalakítás megkísérli megkeresni az elemet a hierarchiában. Ha például a változó neve, first.second.thirdaz átalakítási folyamat a következőt fogja keresni:
```
"first" : {
  "second": {
    "third" : "value"
  }
}
```
valamint "first.second.third" : "value".

Megosztás a következőn keresztül: