Referens för filtransformering och variabel ersättning
Azure DevOps Services | Azure DevOps Server 2022 – Azure DevOps Server 2019
Vissa uppgifter, till exempel Azure App Service Deploy task version 3 och senare och IIS Web App Deploy-uppgiften , gör det möjligt för användare att konfigurera paketet baserat på den angivna miljön. Dessa uppgifter använder msdeploy.exe, som stöder åsidosättande av värden i filen web.config med värden från parameters.xml-filen. Filtransformeringar och variabelersättning är dock inte begränsade till webbappfiler. Du kan använda dessa tekniker med xml- eller JSON-filer.
Kommentar
Filtransformeringar och variabelersättning stöds också av den separata filtransformeringsaktiviteten för användning i Azure Pipelines. Du kan använda filtransformeringsaktiviteten för att tillämpa filtransformeringar och variabelersättningar på alla konfigurations- och parameterfiler.
Konfigurationsersättning anges i avsnittet Alternativ för filtransformering och variabelersättning i inställningarna för aktiviteterna. Alternativen för transformering och ersättning är:
När aktiviteten körs utför den först XML-transformering, XML-variabelersättning och JSON-variabelersättning på konfigurations- och parameterfiler. Därefter anropas msdeploy.exe, som använder filen parameters.xml för att ersätta värden i filen web.config.
XML-transformering
XML-transformering stöder transformering av konfigurationsfilerna (*.config
filer) genom att följa Web.config Transformation Syntax och baseras på miljön som webbpaketet ska distribueras till.
Det här alternativet är användbart när du vill lägga till, ta bort eller ändra konfigurationer för olika miljöer.
Transformering tillämpas för andra konfigurationsfiler, inklusive konfigurationsfiler för konsol- eller Windows-tjänstprogram (till exempel FabrikamService.exe.config).
Namngivningskonventioner för konfigurationstransformeringsfiler
XML-transformering körs på *.config
filen för transformeringskonfigurationsfiler med namnet *.Release.config
eller *.<stage>.config
och körs i följande ordning:
*.Release.config
(till exempel fabrikam. Release.config)*.<stage>.config
(till exempel fabrikam. Production.config)
Om ditt paket till exempel innehåller följande filer:
- Web.config
- Web.Debug.config
- Web.Release.config
- Web.Production.config
och ditt fasnamn är Produktion, transformeringen tillämpas Web.config
med Web.Release.config
följt av Web.Production.config
.
EXEMPEL på XML-transformering
Skapa ett webbprogrampaket med nödvändiga konfigurations- och transformeringsfiler. Använd till exempel följande konfigurationsfiler:
Konfigurationsfil
<?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>
Transformera fil
<?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>
I det här exemplet gör transformeringskonfigurationsfilen tre saker:
- Den lägger till en ny databas anslutningssträng inuti elementet
ConnectionStrings
. - Den ändrar värdet
Webpages:Enabled
för inuti elementetappSettings
. - Det tar
debug
bort attributet från elementetcompilation
inuti elementetSystem.Web
.
Mer information finns i Web.config Transformation Syntax for Web Project Deployment Using Visual Studio
- Den lägger till en ny databas anslutningssträng inuti elementet
Skapa en versionspipeline med en fas med namnet Release.
Lägg till en Azure App Service Deploy-uppgift och ange (tick) xml-transformeringsalternativet .
Spara versionspipelinen och starta en ny version.
Web.config
Öppna filen för att se transformeringarna frånWeb.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>
Anteckningar om XML-transformering
Du kan använda den här tekniken för att skapa ett standardpaket och distribuera det till flera steg.
XML-omvandlingen börjar gälla endast när konfigurationsfilen och transformeringsfilen finns i samma mapp i det angivna paketet.
Som standard tillämpar MSBuild transformeringen eftersom den genererar webbpaketet om elementet
<DependentUpon>
redan finns i transformeringsfilen i*.csproj
filen. I sådana fall misslyckas Azure App Service Deploy-uppgiften eftersom ingen ytterligare transformering tillämpas påWeb.config
filen. Därför rekommenderar vi att elementet<DependentUpon>
tas bort från alla transformeringsfiler för att inaktivera konfiguration av byggtid när XML-transformering används.Ange egenskapen Skapa åtgärd för var och en av transformeringsfilerna (
Web.config
) till Innehåll så att filerna kopieras till rotmappen.... <Content Include="Web.Debug.config"> <DependentUpon>Web.config</DependentUpon> </Content> <Content Include="Web.Release.config"> <DependentUpon>Web.config</DependentUpon> </Content> ...
XML-variabelersättning
Med den här funktionen kan du ändra konfigurationsinställningarna i konfigurationsfiler (*.config
filer) i webbpaket och XML-parameterfiler (parameters.xml
).
På så sätt kan samma paket konfigureras baserat på den miljö som det ska distribueras till.
Variabelersättning börjar gälla endast för elementen applicationSettings
, appSettings
, connectionStrings
och configSections
i konfigurationsfilerna. Om du vill ersätta värden utanför dessa element kan du använda en (parameters.xml
) fil, men du måste använda en pipelineaktivitet från tredje part för att hantera variabelersättningen.
Exempel på XML-variabelersättning
Tänk till exempel på uppgiften att ändra följande värden i 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>
Skapa en versionspipeline med en fas med namnet Release.
Lägg till en Azure App Service Deploy-uppgift och ange (tick) alternativet XML-variabelersättning .
Definiera de värden som krävs i versionspipelinevariabler:
Name Värde Säkra Omfattning Standard Anslut ion Datakälla=(ProdDB)\MSSQLProdDB; AttachFileName=Local.mdf Nej Frisläpp AdminUserName ProdAdminName Nej Frisläpp AdminPassword [ditt lösenord] Ja Frisläpp invariantName System.Data.SqlClientExtension Nej Frisläpp Spara versionspipelinen och starta en ny version.
Web.config
Öppna filen för att se variabelersättningarna.<?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-variabelersättningsanteckningar
Som standard har ASP.NET program ett standardparameteriserat anslutningsattribut. Dessa värden åsidosättas endast i
parameters.xml
filen i webbpaketet.Eftersom ersättning sker före distributionen kan användaren åsidosätta värdena i
Web.config
med hjälp avparameters.xml
(inuti webbpaketet) eller ensetparameters
fil.
JSON-variabelersättning
Den här funktionen ersätter värden i JSON-konfigurationsfilerna.
Den åsidosätter värdena i de angivna JSON-konfigurationsfilerna (till exempel appsettings.json
) med värdena som matchar namnen på versionspipelinen och stegvariablerna.
Om du vill ersätta variabler i specifika JSON-filer anger du en ny radavgränsad lista över JSON-filer. Filnamn måste anges i förhållande till rotmappen. Om ditt paket till exempel har den här strukturen:
/WebPackage(.zip)
/---- content
/----- website
/---- appsettings.json
/---- web.config
/---- [other folders]
/--- archive.xml
/--- systeminfo.xml
och du vill ersätta värden i appsettings.json anger du den relativa sökvägen från rotmappen, till exempel content/website/appsettings.json
.
Du kan också använda jokerteckenmönster för att söka efter specifika JSON-filer.
Returnerar till exempel **/appsettings.json
den relativa sökvägen och namnet på filer med namnet appsettings.json.
Exempel på JSON-variabelersättning
Tänk till exempel på uppgiften att åsidosätta värden i den här JSON-filen:
{
"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"
}
]
}
}
}
Uppgiften är att åsidosätta värdena för Anslut ionString, DebugMode, den första av värdena Användare och NewWelcomeMessage på respektive plats i JSON-filhierarkin.
Skapa en versionspipeline med en fas med namnet Release.
Lägg till en Azure App Service Deploy-uppgift och ange en ny radavgränsad lista över JSON-filer för att ersätta variabelvärdena i textrutan JSON-variabelersättning . Filnamn måste vara relativa till rotmappen. Du kan använda jokertecken för att söka efter JSON-filer. Till exempel:
**/*.json
innebär ersättningsvärden i alla JSON-filer i paketet.Definiera nödvändiga ersättningsvärden i versionspipeline- eller fasvariabler.
Name Värde Säkra Omfattning Data.DebugMode inaktiverat Nej Frisläpp Data.Default Anslut ion.AnslutionString Datakälla=(prodDB)\MSDB; AttachDbFilename=prod.mdf; Nej Frisläpp Data.DBAccess.Users.0 Admin-3 Ja Frisläpp Data.FeatureFlags.Preview.1.NewWelcomeMessage AllAccounts Nej Frisläpp Spara versionspipelinen och starta en ny version.
Efter omvandlingen innehåller JSON följande:
{ "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" } ] } } } '''
JSON-variabelersättningsanteckningar
Om du vill ersätta värden i kapslade nivåer i filen sammanfogar du namnen med en punkt (
.
) i hierarkisk ordning.Ett JSON-objekt kan innehålla en matris vars värden kan refereras till av deras index. Om du till exempel vill ersätta det första värdet i matrisen Användare som visas ovan använder du variabelnamnet
DBAccess.Users.0
. Om du vill uppdatera värdet i NewWelcomeMessage använder du variabelnamnetFeatureFlags.Preview.1.NewWelcomeMessage
. Men filtransformeringsaktiviteten har möjlighet att transformera hela matriser i JSON-filer. Du kan också användaDBAccess.Users = ["NewUser1","NewUser2","NewUser3"]
.Endast strängersättning stöds för JSON-variabelersättning.
Ersättning stöds endast för UTF-8- och UTF-16 LE-kodade filer.
Om filspecifikationen du anger inte matchar någon fil misslyckas uppgiften.
Matchning av variabelnamn är skiftlägeskänsligt.
Variabelersättning används endast för JSON-nycklar som är fördefinierade i objekthierarkin. Den skapar inte nya nycklar.
Om ett variabelnamn innehåller punkter ("."), försöker transformeringen hitta objektet i hierarkin. Om variabelnamnet till exempel är
first.second.third
söker transformeringsprocessen efter:"first" : { "second": { "third" : "value" } }
samt
"first.second.third" : "value"
.
Feedback
https://aka.ms/ContentUserFeedback.
Kommer snart: Under hela 2024 kommer vi att fasa ut GitHub-problem som feedbackmekanism för innehåll och ersätta det med ett nytt feedbacksystem. Mer information finns i:Skicka och visa feedback för