Broncode en configuratiebestanden transformeren

Met een broncodetransformatie wordt eenrichting-tokenvervanging toegepast op bestanden in de content- of contentFiles-map van het pakket (content voor klanten die packages.config gebruiken en contentFiles voor PackageReference) wanneer het pakket wordt geïnstalleerd, waarbij tokens verwijzen naar de projecteigenschappen van Visual Studio. Hiermee kunt u een bestand invoegen in de naamruimte van het project of de code aanpassen die normaal gesproken in global.asax in een ASP.NET-project zou worden geplaatst.

Met een configuratiebestandstransformatie kunt u bestanden wijzigen die al bestaan in een doelproject, zoals web.config en app.config. Het pakket moet bijvoorbeeld mogelijk een item toevoegen aan de modules sectie in het configuratiebestand. Deze transformatie wordt uitgevoerd door speciale bestanden op te geven in het pakket waarin de secties worden beschreven die moeten worden toegevoegd aan de configuratiebestanden. Wanneer een pakket wordt verwijderd, worden dezelfde wijzigingen vervolgens omgekeerd, waardoor dit een tweerichtingstransformatie wordt.

Broncodetransformaties opgeven

Bestanden die u vanuit het pakket in het project wilt invoegen, moeten zich in de pakketten content en contentFiles mappen bevinden. Als u bijvoorbeeld wilt dat een bestand dat wordt aangeroepen ContosoData.cs , wordt geïnstalleerd in een Models map van het doelproject, moet het zich in de content\Models map en contentFiles\{lang}\{tfm}\Models de mappen in het pakket bevinden.
Als u NuGet wilt instrueren om tokenvervanging toe te passen tijdens de installatie, voegt u deze toe aan .pp de bestandsnaam van de broncode. Na de installatie heeft het bestand niet de .pp extensie.

Als u bijvoorbeeld transformaties ContosoData.cswilt maken, noemt u het bestand in het pakket ContosoData.cs.pp. Na de installatie wordt deze weergegeven als ContosoData.cs.
Gebruik in het broncodebestand hoofdletterongevoelige tokens van het formulier $token$ om waarden aan te geven die NuGet moet vervangen door projecteigenschappen.
```
namespace $rootnamespace$.Models
{
    public struct CategoryInfo
    {
        public string categoryid;
        public string description;
        public string htmlUrl;
        public string rssUrl;
        public string title;
    }
}
```
Bij installatie vervangt NuGet $rootnamespace$ door Fabrikam, op basis van de veronderstelling dat het doelproject waarvan de hoofdnaamruimte Fabrikam is.

Het $rootnamespace$ token is de meest gebruikte projecteigenschap; alle andere worden vermeld in projecteigenschappen. Houd er natuurlijk rekening mee dat sommige eigenschappen mogelijk specifiek zijn voor het projecttype.

Configuratiebestandtransformaties opgeven

Zoals beschreven in de volgende secties, kunnen configuratiebestandstransformaties op twee manieren worden uitgevoerd:

Neem app.config.transform en web.config.transform bestanden op in de content map van uw pakket. De .transform extensie vertelt NuGet dat deze bestanden de XML bevatten om samen te voegen met bestaande configuratiebestanden wanneer het pakket wordt geïnstalleerd. Wanneer een pakket wordt verwijderd, wordt dezelfde XML verwijderd.
Neem app.config.install.xdt en web.config.install.xdt bestanden op in de map van content uw pakket, met behulp van de XDT-syntaxis om de gewenste wijzigingen te beschrijven. Met deze optie kunt u ook een .uninstall.xdt bestand opnemen om wijzigingen om te keren wanneer het pakket uit een project wordt verwijderd.

Opmerking

Transformaties worden niet toegepast op .config bestanden waarnaar wordt verwezen als een koppeling in Visual Studio.

Het voordeel van het gebruik van XDT is dat in plaats van simpelweg twee statische bestanden samen te voegen, het een syntaxis biedt voor het bewerken van de structuur van een XML DOM met behulp van elementen en kenmerken die overeenkomen met behulp van volledige XPath-ondersteuning. XDT kan vervolgens elementen toevoegen, bijwerken of verwijderen, nieuwe elementen op een specifieke locatie plaatsen of elementen vervangen/verwijderen (inclusief onderliggende knooppunten). Dit maakt het eenvoudig om de-installatietransformaties te maken die alle transformaties ongedaan maken die tijdens de installatie van het pakket zijn uitgevoerd.

XML-transformaties

De app.config.transform en web.config.transform in de map van content een pakket bevatten alleen die elementen die moeten worden samengevoegd in de bestaande app.config en web.config bestanden van het project.

Stel dat het project in eerste instantie de volgende inhoud bevat:web.config

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

Als u een MyNuModule element wilt toevoegen aan de sectie tijdens de installatie van het modules pakket, maakt u een web.config.transform bestand in de map van content het pakket dat er als volgt uitziet:

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

Nadat NuGet het pakket heeft geïnstalleerd, wordt web.config als volgt weergegeven:

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

U ziet dat NuGet de modules sectie niet heeft vervangen, maar de nieuwe vermelding is samengevoegd door alleen nieuwe elementen en kenmerken toe te voegen. NuGet wijzigt geen bestaande elementen of kenmerken.

Wanneer het pakket wordt verwijderd, onderzoekt NuGet de .transform bestanden opnieuw en verwijdert u de elementen die het bevat uit de juiste .config bestanden. Houd er rekening mee dat dit proces geen invloed heeft op regels in het bestand dat u wijzigt na de installatie van het .config pakket.

Als een uitgebreider voorbeeld voegt het pakket Foutlogboekregistratiemodules en handlers voor ASP.NET (ELMAH) veel vermeldingen toe aan web.config, die worden verwijderd wanneer een pakket wordt verwijderd.

Als u het web.config.transform-bestand wilt bekijken, download dan het ELMAH-pakket via de bovenstaande link, wijzig de pakketextensie van .nupkg naar .zip, en open vervolgens content\web.config.transform in het ZIP-bestand.

Als u het effect van het installeren en verwijderen van het pakket wilt zien, maakt u een nieuw ASP.NET project in Visual Studio (de sjabloon bevindt zich onder Visual C# > Web in het dialoogvenster Nieuw project) en selecteert u een lege ASP.NET toepassing. Open web.config om de oorspronkelijke status te zien. Klik vervolgens met de rechtermuisknop op het project, selecteer NuGet-pakketten beheren, blader naar ELMAH op nuget.org en installeer de nieuwste versie. Let op alle wijzigingen in web.config. Verwijder nu het pakket en u ziet web.config terugkeren naar zijn vorige status.

XDT-transformaties

Opmerking

Zoals vermeld in de sectie met pakketcompatibiliteitsproblemen van de documenten voor migratie van packages.config naar PackageReference, worden XDT-transformaties zoals hieronder beschreven alleen ondersteund door packages.config. Als u de onderstaande bestanden aan uw pakket toevoegt, worden de transformaties niet toegepast door consumenten die uw pakket gebruiken in combinatie met PackageReference (raadpleeg dit voorbeeld om te leren hoe u XDT-transformaties kunt toepassen met PackageReference).

U kunt configuratiebestanden wijzigen met behulp van XDT-syntaxis. U kunt ook NuGet-tokens laten vervangen door projecteigenschappen door de naam van de eigenschap op te geven binnen $ scheidingstekens (niet-hoofdlettergevoelig).

In het volgende app.config.install.xdt bestand wordt bijvoorbeeld een appSettings element ingevoegd waarin app.config de FullPath, FileNameen ActiveConfigurationSettings waarden van het project worden opgenomen:

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

Stel dat het project in eerste instantie de volgende inhoud bevat:web.config

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

Als u een MyNuModule element wilt toevoegen aan de modules sectie tijdens de installatie van het pakket, bevat de web.config.install.xdt van het pakket het volgende:

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

Na de installatie van het pakket web.config ziet dit er als volgt uit:

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

Als u alleen het MyNuModule element wilt verwijderen tijdens het verwijderen van het pakket, moet het web.config.uninstall.xdt bestand het volgende bevatten:

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

Is deze pagina nuttig?

Last updated on 2025-10-31