Transformera källkods- och konfigurationsfiler

En källkodstransformering tillämpar envägstokenersättning på filer i paketets content eller contentFiles mappen (content för kunder som använder packages.config och contentFiles för PackageReference) när paketet installeras, där token refererar till Visual Studio-projektegenskaper. På så sätt kan du infoga en fil i projektets namnområde eller anpassa kod som vanligtvis skulle gå in global.asax i ett ASP.NET projekt.

Med en konfigurationsfiltransformering kan du ändra filer som redan finns i ett målprojekt, till exempel web.config och app.config. Ditt paket kan till exempel behöva lägga till ett objekt i modules avsnittet i konfigurationsfilen. Den här omvandlingen görs genom att inkludera särskilda filer i paketet som beskriver de avsnitt som ska läggas till i konfigurationsfilerna. När ett paket avinstalleras återställs samma ändringar, vilket gör detta till en tvåvägsomvandling.

Ange källkodstransformeringar

Filer som du vill infoga från paketet i projektet måste finnas i paketets content och contentFiles mapparna. Om du till exempel vill att en fil som heter ContosoData.cs ska installeras i en Models mapp i målprojektet måste den finnas i mapparna content\Models och contentFiles\{lang}\{tfm}\Models i paketet.
Om du vill instruera NuGet att tillämpa tokenbyte vid installationen lägger du till i källkodsfilens .pp namn. Efter installationen kommer filen inte att ha .pp tillägget.

Om du till exempel vill göra transformeringar i ContosoData.csnamnger du filen i paketet ContosoData.cs.pp. Efter installationen visas den som ContosoData.cs.
I källkodsfilen använder du skiftlägesokänsliga token i formuläret $token$ för att ange värden som NuGet ska ersätta med projektegenskaper:
```
namespace $rootnamespace$.Models
{
    public struct CategoryInfo
    {
        public string categoryid;
        public string description;
        public string htmlUrl;
        public string rssUrl;
        public string title;
    }
}
```
Vid installation ersätter NuGet $rootnamespace$ med Fabrikam förutsatt att det målprojekt vars rotnamnområde är Fabrikam.

Token $rootnamespace$ är den vanligaste projektegenskapen. Alla andra visas i projektegenskaper. Tänk naturligtvis på att vissa egenskaper kan vara specifika för projekttypen.

Specificera konfigurationsfilstransformeringar

Som beskrivs i avsnitten som följer kan konfigurationsfiltransformeringar göras på två sätt:

Inkludera app.config.transform och web.config.transform filer i paketets mapp, där content tillägget meddelar NuGet att dessa filer innehåller XML för sammanslagning med befintliga konfigurationsfiler .transform när paketet installeras. När ett paket avinstalleras tas samma XML bort.
Inkludera app.config.install.xdt och web.config.install.xdt filer i paketets content mapp med XDT-syntax för att beskriva önskade ändringar. Med det här alternativet kan du även inkludera en .uninstall.xdt fil för att ångra ändringar när paketet tas bort från ett projekt.

Anmärkning

Transformeringar tillämpas inte på filer som refereras till .config som en länk i Visual Studio.

Fördelen med att använda XDT är att i stället för att bara sammanfoga två statiska filer, ger det en syntax för att ändra strukturen för en XML DOM med element- och attributmatchning med hjälp av fullständigt XPath-stöd. XDT kan sedan lägga till, uppdatera eller ta bort element, placera nya element på en specifik plats eller ersätta/ta bort element (inklusive underordnade noder). Det gör det enkelt att skapa avinstallationstransformeringar som säkerhetskopierar alla transformeringar som görs under paketinstallationen.

XML-transformeringar

Mappen app.config.transform och web.config.transform i ett paket content innehåller endast de element som ska sammanfogas till projektets befintliga app.config filer och web.config filer.

Anta till exempel att projektet ursprungligen innehåller följande innehåll i web.config:

<configuration>
    <system.webServer>
        <modules>
            <add name="ContosoUtilities" type="Contoso.Utilities" />
        </modules>
    </system.webServer>
</configuration>

Om du vill lägga till ett MyNuModule element i modules avsnittet under paketinstallationen skapar du en web.config.transform fil i paketets content mapp som ser ut så här:

<configuration>
    <system.webServer>
        <modules>
            <add name="MyNuModule" type="Sample.MyNuModule" />
        </modules>
    </system.webServer>
</configuration>

När NuGet har installerat paketet web.config visas följande:

<configuration>
    <system.webServer>
        <modules>
            <add name="ContosoUtilities" type="Contoso.Utilities" />
            <add name="MyNuModule" type="Sample.MyNuModule" />
        </modules>
    </system.webServer>
</configuration>

Observera att NuGet inte ersatte modules avsnittet. Den sammanfogade bara den nya posten genom att bara lägga till nya element och attribut. NuGet ändrar inga befintliga element eller attribut.

När paketet avinstalleras undersöker .transform NuGet filerna igen och tar bort de element som det innehåller från lämpliga .config filer. Observera att den här processen inte påverkar några rader i .config filen som du ändrar efter paketinstallationen.

Som ett mer omfattande exempel, lägger paketet Felloggningsmoduler och hanterare för ASP.NET (ELMAH) till många felposter i web.config, som tas bort igen när ett paket avinstalleras.

Om du vill undersöka filen web.config.transform laddar du ned ELMAH-paketet från länken ovan, ändrar pakettillägget från .nupkg till .zipoch öppnar content\web.config.transform sedan i ZIP-filen.

Om du vill se effekten av att installera och avinstallera paketet skapar du ett nytt ASP.NET projekt i Visual Studio (mallen finns under Visual C# > Web i dialogrutan Nytt projekt) och väljer ett tomt ASP.NET program. Öppna web.config för att se dess ursprungliga tillstånd. Högerklicka sedan på projektet, välj Hantera NuGet-paket, bläddra efter ELMAH på nuget.org och installera den senaste versionen. Observera alla ändringar i web.config. Avinstallera nu paketet och du ser web.config återgå till dess tidigare tillstånd.

XDT-transformationer

Anmärkning

Som vi nämnde i avsnittet om paketkompatibilitetsproblem i dokumenten för migrering från packages.config till PackageReference, stöds XDT-transformeringar enligt beskrivningen nedan endast av packages.config. Om du lägger till filerna nedan i paketet kommer konsumenter som använder ditt paket med PackageReference inte att använda transformeringarna (se det här exemplet för att få XDT-transformeringar att fungera medPackageReference).

Du kan ändra konfigurationsfiler med XDT-syntax. Du kan också låta NuGet ersätta token med projektegenskaper genom att inkludera egenskapsnamnet inom $ avgränsare (skiftlägesokänsligt).

Följande fil infogar till exempel app.config.install.xdt ett appSettings element i app.config som innehåller FullPathvärdena , FileNameoch ActiveConfigurationSettings från projektet:

<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
    <appSettings xdt:Transform="Insert">
        <add key="FullPath" value="$FullPath$" />
        <add key="FileName" value="$filename$" />
        <add key="ActiveConfigurationSettings " value="$ActiveConfigurationSettings$" />
    </appSettings>
</configuration>

Anta till exempel att projektet ursprungligen innehåller följande innehåll i web.config:

<configuration>
    <system.webServer>
        <modules>
            <add name="ContosoUtilities" type="Contoso.Utilities" />
        </modules>
    </system.webServer>
</configuration>

Om du vill lägga till ett MyNuModule element i modules avsnittet under paketinstallationen innehåller paketet följande web.config.install.xdt :

<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
    <system.webServer>
        <modules>
            <add name="MyNuModule" type="Sample.MyNuModule" xdt:Transform="Insert" />
        </modules>
    </system.webServer>
</configuration>

När du har installerat paketet web.config ser det ut så här:

<configuration>
    <system.webServer>
        <modules>
            <add name="ContosoUtilities" type="Contoso.Utilities" />
            <add name="MyNuModule" type="Sample.MyNuModule" />
        </modules>
    </system.webServer>
</configuration>

Om du bara vill ta bort elementet MyNuModule under paketavinstallationen web.config.uninstall.xdt ska filen innehålla följande:

<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
    <system.webServer>
        <modules>
            <add name="MyNuModule" xdt:Transform="Remove" xdt:Locator="Match(name)" />
        </modules>
    </system.webServer>
</configuration>

Feedback

Var den här sidan till hjälp?

Last updated on 2025-10-31