Transformieren von Quellcode- und Konfigurationsdateien

Eine Quellcodetransformation wendet eine unidirektionale Tokenersetzung auf Dateien im content- oder contentFiles-Ordner an (content für Kunden, die packages.config verwenden, und contentFiles für PackageReference), wenn das Paket installiert wird, wobei Token auf Visual Studio-Projekteigenschaften verweisen. Auf diese Weise können Sie eine Datei in den Namespace des Projekts einfügen oder Code anpassen, der normalerweise im global.asax eines ASP.NET-Projekts enthalten wäre.

Mit einer Konfigurationsdateitransformation können Sie Dateien ändern, die bereits in einem Zielprojekt vorhanden sind, wie web.config und app.config. Ihr Paket muss z. B. dem Abschnitt in der modules Konfigurationsdatei möglicherweise ein Element hinzufügen. Diese Transformation erfolgt durch Hinzufügen spezieller Dateien in das Paket, in denen die Abschnitte beschrieben werden, die den Konfigurationsdateien hinzugefügt werden sollen. Wenn ein Paket deinstalliert wird, werden dieselben Änderungen dann rückgängig gemacht, wodurch dies eine bidirektionale Transformation wird.

Angeben von Quellcodetransformationen

Dateien, die Sie aus dem Paket in das Projekt einfügen möchten, müssen sich in den Paket content - und contentFiles Ordnern befinden. Wenn eine Datei ContosoData.cs beispielsweise in einem Models Ordner des Zielprojekts installiert werden soll, muss sie sich innerhalb der content\Models Ordner und contentFiles\{lang}\{tfm}\Models Ordner im Paket befinden.
Um NuGet anzuweisen, zum Installationszeitpunkt die Tokenersetzung durchzuführen, fügen Sie .pp an den Dateinamen des Quellcodes an. Nach der Installation verfügt die Datei nicht über die .pp Erweiterung.

Wenn Sie z. B. Transformationen vornehmen möchten ContosoData.cs, benennen Sie die Datei im Paket ContosoData.cs.pp. Nach der Installation erscheint es als ContosoData.cs.
Verwenden Sie in der Quellcodedatei tokens, die nicht auf Groß-/Kleinschreibung achten, in der Form von $token$ , um Werte anzugeben, die NuGet durch Projekteigenschaften ersetzen soll.
```
namespace $rootnamespace$.Models
{
    public struct CategoryInfo
    {
        public string categoryid;
        public string description;
        public string htmlUrl;
        public string rssUrl;
        public string title;
    }
}
```
Bei der Installation ersetzt NuGet $rootnamespace$ durch Fabrikam, vorausgesetzt, dass das Zielprojekt im Stammnamespace Fabrikam hat.

Das $rootnamespace$ Token ist die am häufigsten verwendete Projekteigenschaft. Alle anderen werden in Projekteigenschaften aufgeführt. Denken Sie natürlich daran, dass einige Eigenschaften für den Projekttyp spezifisch sein können.

Spezifizieren von Transformationen der Konfigurationsdatei

Wie in den folgenden Abschnitten beschrieben, können Konfigurationsdateitransformationen auf zwei Arten ausgeführt werden:

Schließen Sie app.config.transform und web.config.transform Dateien in den Ordner content Ihres Pakets ein, wobei die .transform Erweiterung NuGet angibt, dass diese Dateien den XML-Inhalt enthalten, der mit vorhandenen Konfigurationsdateien zusammengeführt wird, wenn das Paket installiert wird. Wenn ein Paket deinstalliert wird, wird derselbe XML-Code entfernt.
Schließen Sie app.config.install.xdt und web.config.install.xdt Dateien im content Ordner Ihres Pakets ein, verwenden Sie die XDT-Syntax, um die gewünschten Änderungen zu beschreiben. Mit dieser Option können Sie auch eine .uninstall.xdt Datei einfügen, um Änderungen rückgängig zu machen, wenn das Paket aus einem Projekt entfernt wird.

Hinweis

Transformationen werden nicht auf Dateien angewendet, die in Visual Studio als Verknüpfung referenziert werden.

Der Vorteil der Verwendung von XDT besteht darin, dass sie anstelle der einfache Zusammenführung von zwei statischen Dateien eine Syntax zum Bearbeiten der Struktur eines XML-DOM mithilfe von Element- und Attributabgleich mithilfe vollständiger XPath-Unterstützung bereitstellt. XDT kann dann Elemente hinzufügen, aktualisieren oder entfernen, neue Elemente an einer bestimmten Position platzieren oder Elemente ersetzen/entfernen (einschließlich untergeordneter Knoten). Dies erleichtert das Erstellen von Deinstallationstransformationen, die alle während der Paketinstallation durchgeführten Transformationen rückgängig machen.

XML-Transformationen

Der app.config.transform Ordner und web.config.transform im Ordner eines Pakets content enthalten nur die Elemente, die mit den vorhandenen app.config und web.config dateien des Projekts zusammengeführt werden sollen.

Angenommen, das Projekt enthält zunächst den folgenden Inhalt in web.config:

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

Um ein MyNuModule Element dem modules Abschnitt während der Paketinstallation hinzuzufügen, erstellen Sie eine Datei im content Ordner des Pakets, die wie folgt aussieht:web.config.transform

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

Nachdem NuGet das Paket installiert hat, web.config wird wie folgt angezeigt:

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

Beachten Sie, dass NuGet den modules Abschnitt nicht ersetzt hat, sondern den neuen Eintrag in diesen integriert hat, indem es nur neue Elemente und Attribute hinzufügte. NuGet ändert keine vorhandenen Elemente oder Attribute.

Wenn das Paket deinstalliert wird, überprüft NuGet die .transform Dateien erneut und entfernt die darin enthaltenen Elemente aus den entsprechenden .config Dateien. Beachten Sie, dass sich dieser Vorgang nicht auf Zeilen in der Datei auswirkt, die Sie nach der .config Paketinstallation ändern.

Im umfangreicheren Beispiel fügt das Paket mit den Fehlerprotokollierungsmodule und -handlern für ASP.NET (ELMAH) viele Einträge in web.config hinzu, die beim Deinstallieren eines Pakets entfernt werden.

Um die web.config.transform-Datei zu untersuchen, laden Sie das ELMAH-Paket über den obigen Link herunter, ändern Sie die Paketerweiterung von .nupkg zu .zip, und öffnen Sie dann content\web.config.transform in dieser ZIP-Datei.

Um die Auswirkungen der Installation und Deinstallation des Pakets anzuzeigen, erstellen Sie ein neues ASP.NET Projekt in Visual Studio (die Vorlage befindet sich im Dialogfeld "Neues Projekt" unter Visual C# > -Web ), und wählen Sie eine leere ASP.NET Anwendung aus. Öffnen web.config , um den Anfangszustand anzuzeigen. Klicken Sie dann mit der rechten Maustaste auf das Projekt, wählen Sie "NuGet-Pakete verwalten", suchen Sie auf nuget.org nach ELMAH, und installieren Sie die neueste Version. Beachten Sie alle Änderungen an web.config. Deinstallieren Sie nun das Paket, und Sie werden sehen, dass sich web.config zu seinem vorherigen Zustand zurückkehrt.

XDT-Transformationen

Hinweis

Wie im Abschnitt "Paketkompatibilitätsprobleme" der Dokumente für die Migration von packages.config zu PackageReference beschrieben, werden XDT-Transformationen wie unten erläutert nur von packages.config unterstützt. Wenn Sie die folgenden Dateien zu Ihrem Paket hinzufügen, werden bei Verbrauchern, die Ihr Paket mit PackageReference verwenden, die Transformationen nicht angewendet (siehe dieses Beispiel, damit XDT-Transformationen mit PackageReference funktionieren).

Sie können Konfigurationsdateien mithilfe der XDT-Syntax ändern. Sie können auch NuGet-Token durch Projekteigenschaften ersetzen, indem Sie den Eigenschaftsnamen in $ Trennzeichen einschließen (Groß-/Kleinschreibung wird nicht beachtet).

Die folgende app.config.install.xdt Datei wird ein appSettings Element in app.config einfügen, das die FullPath, FileName und ActiveConfigurationSettings Werte aus dem Projekt enthält.

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

Angenommen, das Projekt enthält zunächst den folgenden Inhalt in web.config:

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

Um ein MyNuModule Element dem modules Abschnitt während der Paketinstallation hinzuzufügen, würde das web.config.install.xdt des Pakets Folgendes enthalten:

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

Nach der Installation des Pakets web.config sieht es wie folgt aus:

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

Um nur das MyNuModule-Element während der Deinstallation des Pakets zu entfernen, sollte die web.config.uninstall.xdt-Datei Folgendes enthalten:

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

War diese Seite hilfreich?

Last updated on 2025-10-31