Przekształcenia plików i odwołanie do podstawień zmiennych

Artykuł
04/04/2024

Azure DevOps Services | Azure DevOps Server 2022 — Azure DevOps Server 2019

Niektóre zadania, takie jak zadanie wdrażania usługi aplikacja systemu Azure w wersji 3 lub nowszej oraz zadanie Wdrażanie aplikacji internetowej usług IIS, umożliwiają użytkownikom konfigurowanie pakietu na podstawie określonego środowiska. Te zadania używają msdeploy.exe, która obsługuje zastępowanie wartości w pliku web.config z wartościami z pliku parameters.xml . Jednak przekształcenia plików i podstawianie zmiennych nie są ograniczone do plików aplikacji internetowej. Można użyć tych technik z dowolnymi plikami XML lub JSON.

Uwaga

Przekształcenia plików i podstawienie zmiennych są również obsługiwane przez oddzielne zadanie Przekształcanie plików do użycia w usłudze Azure Pipelines. Za pomocą zadania Przekształcanie plików można zastosować przekształcenia plików i podstawienia zmiennych w dowolnych plikach konfiguracji i parametrów.

Podstawianie konfiguracji jest określone w sekcji Opcje przekształcania plików i podstawiania zmiennych ustawień dla zadań podrzędnych. Opcje przekształcania i podstawiania to:

Przekształcanie XML
Podstawianie zmiennych XML
Podstawianie zmiennych JSON

Po uruchomieniu zadania najpierw wykonuje transformację XML, podstawienie zmiennych XML i podstawienie zmiennych JSON w plikach konfiguracji i parametrów. Następnie wywołuje msdeploy.exe, który używa pliku parameters.xml do zastępowania wartości w pliku web.config .

Przekształcanie XML

Transformacja XML obsługuje przekształcanie plików konfiguracji (*.config plików) przez następujące składnię przekształcenia Web.config i opiera się na środowisku, w którym pakiet internetowy zostanie wdrożony. Ta opcja jest przydatna, gdy chcesz dodać, usunąć lub zmodyfikować konfiguracje dla różnych środowisk. Przekształcenie zostanie zastosowane do innych plików konfiguracji, w tym plików konfiguracji konsoli lub aplikacji usługi systemu Windows (na przykład FabrikamService.exe.config).

Konwencje nazewnictwa plików przekształcania konfiguracji

Przekształcenie XML zostanie uruchomione w *.config pliku dla plików konfiguracji przekształcenia o nazwie *.Release.config lub *.<stage>.config i zostanie wykonane w następującej kolejności:

*.Release.config (na przykład fabrikam. Release.config)
*.<stage>.config (na przykład fabrikam. Production.config)

Jeśli na przykład pakiet zawiera następujące pliki:

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

a nazwa etapu to Produkcja, transformacja jest stosowana dla Web.config elementu z ciągiem Web.Production.configWeb.Release.config .

Przykład przekształcenia XML

Utwórz pakiet aplikacji internetowej z wymaganymi plikami konfiguracji i przekształcania. Na przykład użyj następujących plików konfiguracji:

Plik konfiguracji

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

Przekształć plik

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

W tym przykładzie plik konfiguracji przekształcania wykonuje trzy czynności:

Dodaje nową bazę danych parametry połączenia wewnątrz ConnectionStrings elementu.
Modyfikuje wartość Webpages:Enabled wewnątrz appSettings elementu.
Usuwa atrybut debug z compilation elementu wewnątrz System.Web elementu.

Aby uzyskać więcej informacji, zobacz Web.config Transformation Syntax for Web Project Deployment Using Visual Studio (Składnia przekształcenia Web.config dla wdrażania projektu internetowego przy użyciu programu Visual Studio)

Utwórz potok wydania z etapem o nazwie Release (Wydanie).
Dodaj zadanie aplikacja systemu Azure Service Deploy i ustaw (zaznacz) opcję przekształcania XML.
Zapisz potok wydania i uruchom nową wersję.

Otwórz plik, Web.config aby wyświetlić przekształcenia z pliku 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>

Uwagi dotyczące przekształcania XML

Ta technika umożliwia utworzenie domyślnego pakietu i wdrożenie go na wielu etapach.
Przekształcenie XML ma zastosowanie tylko wtedy, gdy plik konfiguracji i plik przekształcenia znajdują się w tym samym folderze w określonym pakiecie.
Domyślnie program MSBuild stosuje przekształcenie, ponieważ generuje pakiet internetowy, jeśli <DependentUpon> element jest już obecny w pliku transform w *.csproj pliku. W takich przypadkach zadanie wdrażania usługi aplikacja systemu Azure zakończy się niepowodzeniem, ponieważ w pliku nie zastosowano dalszych przekształceńWeb.config. W związku z tym zaleca się, aby <DependentUpon> element został usunięty ze wszystkich plików przekształcania, aby wyłączyć dowolną konfigurację czasu kompilacji podczas korzystania z przekształcenia XML.

Ustaw właściwość Akcja kompilacji dla każdego z plików przekształcania (Web.config) na Zawartość, aby pliki zostały skopiowane do folderu głównego.

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

Podstawianie zmiennych XML

Ta funkcja umożliwia modyfikowanie ustawień konfiguracji w plikach konfiguracji (*.config plikach) wewnątrz pakietów internetowych i plików parametrów XML (parameters.xml). W ten sposób można skonfigurować ten sam pakiet na podstawie środowiska, w którym zostanie wdrożony.

Podstawianie zmiennych ma wpływ tylko na applicationSettingselementy plików konfiguracji , appSettings, connectionStringsi configSections . Jeśli chcesz zastąpić wartości poza tymi elementami, możesz użyć pliku (parameters.xml), jednak należy użyć zadania potoku innej firmy do obsługi podstawienia zmiennej.

Przykład podstawianie zmiennej XML

Rozważmy na przykład zadanie zmiany następujących wartości w pliku 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>

Utwórz potok wydania z etapem o nazwie Release (Wydanie).
Dodaj zadanie aplikacja systemu Azure Service Deploy i ustaw (znacznik) opcję podstawienia zmiennej XML.

Zdefiniuj wymagane wartości w zmiennych potoku wydania:

Nazwa/nazwisko	Wartość	Zabezpieczanie	Scope
Domyślna Połączenie ion	Źródło danych=(ProdDB)\MSSQLProdDB; AttachFileName=Local.mdf	Nie.	Zwolnij
AdminUserName	Prod Administracja Name	Nie.	Zwolnij
AdminPassword	[twoje hasło]	Tak	Zwolnij
invariantName	System.Data.SqlClientExtension	Nie.	Zwolnij

Zapisz potok wydania i uruchom nową wersję.

Otwórz plik, Web.config aby zobaczyć podstawienia zmiennych.

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

Uwagi dotyczące zastępowania zmiennych XML

Domyślnie ASP.NET aplikacje mają domyślny atrybut połączenia sparametryzowanego. Te wartości są zastępowane tylko w parameters.xml pliku wewnątrz pakietu internetowego.
Ponieważ podstawianie występuje przed wdrożeniem, użytkownik może zastąpić wartości przy Web.config użyciu parameters.xml (wewnątrz pakietu internetowego setparameters ) lub pliku.

Podstawianie zmiennych JSON

Ta funkcja zastępuje wartości w plikach konfiguracji JSON. Zastępuje ona wartości w określonych plikach konfiguracji JSON (na przykład appsettings.json) z wartościami pasującymi do nazw potoku wydania i zmiennych etapu.

Aby zastąpić zmienne w określonych plikach JSON, podaj listę plików JSON rozdzielonych nowym wierszem. Nazwy plików muszą być określone względem folderu głównego. Jeśli na przykład pakiet ma następującą strukturę:

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

i chcesz zastąpić wartości w appsettings.json, wprowadź ścieżkę względną z folderu głównego, na przykład content/website/appsettings.json. Alternatywnie użyj wzorców wieloznacznych, aby wyszukać określone pliki JSON. Na przykład **/appsettings.json zwraca ścieżkę względną i nazwę plików o nazwie appsettings.json.

Przykład podstawiania zmiennych JSON

Rozważmy na przykład zadanie zastępowania wartości w tym pliku 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"
        }
      ]
    }
  }
}

Zadanie polega na zastąpieniu wartości Połączenie ionString, DebugMode, pierwszej wartości Users i NewWelcomeMessage w odpowiednich miejscach w hierarchii plików JSON.

Klasyczny
YAML

Utwórz potok wydania z etapem o nazwie Release (Wydanie).
Dodaj zadanie aplikacja systemu Azure Service Deploy i wprowadź listę plików JSON rozdzielonych nową linią, aby zastąpić wartości zmiennych w polu tekstowym podstawienia zmiennej JSON. Nazwy plików muszą być względne względem folderu głównego. Do wyszukiwania plików JSON można użyć symboli wieloznacznych. Na przykład: **/*.json oznacza zastępowanie wartości we wszystkich plikach JSON w pakiecie.

Zdefiniuj wymagane wartości podstawienia w potoku wydania lub zmiennych etapu.

Nazwa/nazwisko	Wartość	Zabezpieczanie	Scope
Data.DebugMode	wyłączone	Nie.	Zwolnij
Data.Default Połączenie ion.PołączenieionString	Źródło danych=(prodDB)\MSDB; AttachDbFilename=prod.mdf;	Nie.	Zwolnij
Data.DBAccess.Users.0	Administracja-3	Tak	Zwolnij
Data.FeatureFlags.Preview.1.NewWelcomeMessage	Wszystkie konta	Nie.	Zwolnij

Zapisz potok wydania i uruchom nową wersję.

Po przekształceniu kod JSON będzie zawierać następujące elementy:

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

Poniższy fragment kodu YAML przedstawia podstawianie zmiennych 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

Uwagi dotyczące podstawiania zmiennych JSON

Aby zastąpić wartości na poziomach zagnieżdżonych pliku, połącz nazwy z kropką (.) w kolejności hierarchicznej.
Obiekt JSON może zawierać tablicę, do której można odwoływać się do ich indeksu. Aby na przykład zastąpić pierwszą wartość w tablicy Users pokazanej powyżej, użyj nazwy DBAccess.Users.0zmiennej . Aby zaktualizować wartość w newWelcomeMessage, użyj nazwy FeatureFlags.Preview.1.NewWelcomeMessagezmiennej . Jednak zadanie przekształcania plików ma możliwość przekształcania całych tablic w plikach JSON. Możesz również użyć polecenia DBAccess.Users = ["NewUser1","NewUser2","NewUser3"].
Tylko podstawienie ciągu jest obsługiwane w przypadku podstawienia zmiennych JSON.
Podstawianie jest obsługiwane tylko dla plików zakodowanych w formacie UTF-8 i UTF-16 LE.
Jeśli wprowadzona specyfikacja pliku nie jest zgodna z żadnym plikiem, zadanie zakończy się niepowodzeniem.
Dopasowanie nazwy zmiennej jest uwzględniane w wielkości liter.
Podstawianie zmiennych jest stosowane tylko dla kluczy JSON wstępnie zdefiniowanych w hierarchii obiektów. Nie tworzy nowych kluczy.
Jeśli nazwa zmiennej zawiera kropki ("."), przekształcenie podejmie próbę zlokalizowania elementu w hierarchii. Jeśli na przykład nazwa zmiennej to first.second.third, proces przekształcania wyszuka następujące elementy:
```
"first" : {
  "second": {
    "third" : "value"
  }
}
```
oraz "first.second.third" : "value".

Udostępnij za pośrednictwem