Transformieren von Quellcode und KonfigurationsdateienTransforming source code and configuration files

Bei Projekten, die die Datei packages.config verwenden, unterstützt NuGet die Fähigkeit, bei Installationen und Deinstallationen von Paketen, Transformationen an dem Quellcode und den Konfigurationsdateien vorzunehmen.For projects using packages.config, NuGet supports the ability to make transformations to source code and configuration files at package install and uninstall times. Es werden ausschließlich Quellcodetransformationen angewendet, wenn ein Paket in einem Projekt installiert wird, das PackageReference verwendet.Only Source code transformations are applied when a package is installed in a project using PackageReference.

Bei einer Quellcodetransformation wird während der Installation des Pakets eine unidirektionale Tokenersetzung auf Dateien Ordner content oder contentFiles des Pakets angewendet (content für Kunden, die packages.config und contentFiles für PackageReference verwenden). Dabei beziehen sich die Token auf die Projekteigenschaften von Visual Studio.A source code transformation applies one-way token replacement to files in the package's content or contentFiles folder (content for customers using packages.config and contentFiles for PackageReference) when the package is installed, where tokens refer to Visual Studio project properties. Dies bietet Ihnen die Möglichkeit, eine Datei in den Namespace des Projekts einzufügen oder Code anzupassen, der normalerweise in global.asax in einem ASP.NET-Projekt eingefügt werden würde.This allows you to insert a file into the project's namespace, or to customize code that would typically go into global.asax in an ASP.NET project.

Bei einer Konfigurationsdateitransformation können Sie Dateien ändern, die bereits in einem Zielprojekt vorhanden sind, wie z.B. web.config und app.config.A config file transformation allows you to modify files that already exist in a target project, such as web.config and app.config. In Ihrem Paket müsste beispielsweise ein Element zu Abschnitt modules in der Konfigurationsdatei hinzugefügt werden.For example, your package might need to add an item to the modules section in the config file. Diese Transformation erfolgt durch das Einschließen spezieller Dateien in das Paket, in denen die zu den Konfigurationsdateien hinzuzufügenden Abschnitte beschrieben werden.This transformation is done by including special files in the package that describe the sections to add to the configuration files. Bei der Deinstallation eines Pakets werden diese Änderungen wieder zurückgesetzt, wodurch diese Transformation zu einer bidirektionalen Transformation wird.When a package is uninstalled, those same changes are then reversed, making this a two-way transformation.

Angeben von QuellcodetransformationenSpecifying source code transformations

  1. Dateien, die Sie aus dem Paket in das Projekt einfügen möchten, müssen in den Ordnern content und contentFiles des Pakets enthalten sein.Files that you want to insert from the package into the project must be located within the package's content and contentFiles folders. Wenn Sie beispielsweise möchten, dass eine Datei mit dem Namen ContosoData.cs in dem Ordner Models des Zielprojekts installiert wird, muss diese in den Ordnern content\Models und contentFiles\{lang}\{tfm}\Models des Pakets enthalten sein.For example, if you want a file called ContosoData.cs to be installed in a Models folder of the target project, it must be inside the content\Models and contentFiles\{lang}\{tfm}\Models folders in the package.

  2. Hängen Sie .pp an den Namen der Quellcodedatei an, um NuGet die Anweisung zu geben, die Tokenersetzung während der Installation anzuwenden.To instruct NuGet to apply token replacement at install time, append .pp to the source code file name. Nach der Installation weist die Datei nicht die Erweiterung .pp auf.After installation, the file will not have the .pp extension.

    Wenn Sie beispielsweise Transformationen in ContosoData.cs vornehmen möchten, nennen Sie die Datei in dem Paket ContosoData.cs.pp.For example, to make transformations in ContosoData.cs, name the file in the package ContosoData.cs.pp. Nach der Installation wird sie als ContosoData.cs angezeigt.After installation it will appear as ContosoData.cs.

  3. Verwenden Sie für die Angabe von Werten, die NuGet durch Projekteigenschaften ersetzen sollte, in der Quellcodedatei Token im Format $token$ ohne Beachtung der Groß-/Kleinschreibung:In the source code file, use case-insensitive tokens of the form $token$ to indicate values that NuGet should replace with project properties:

    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$, wobei es davon ausgeht, dass Fabrikam das Zielprojekt ist, dessen Stammnamespace Fabrikam lautet.Upon installation, NuGet replaces $rootnamespace$ with Fabrikam assuming the target project's whose root namespace is Fabrikam.

Das Token $rootnamespace$ stellt die am häufigsten verwendete Projekteigenschaft dar. Alle weiteren Token werden unter Projekteigenschaften aufgelistet.The $rootnamespace$ token is the most commonly used project property; all others are listed in project properties. Bedenken Sie jedoch, dass einige Eigenschaften möglicherweise für den Projekttyp spezifisch sind.Be mindful, of course, that some properties might be specific to the project type.

Angeben von KonfigurationsdateitransformationenSpecifying config file transformations

Wie in den nachfolgenden Abschnitten beschrieben, können Konfigurationsdateitransformationen auf zwei Arten erfolgen:As described in the sections that follow, config file transformations can be done in two ways:

  • Schließen Sie die Dateien app.config.transform und web.config.transform in den Ordner content Ihres Pakets ein. Dabei erkennt NuGet an der .transform-Erweiterung, dass diese Dateien den XML-Code enthalten, der bei der Installation des Pakets mit vorhandenen Konfigurationsdateien zusammengeführt werden soll.Include app.config.transform and web.config.transform files in your package's content folder, where the .transform extension tells NuGet that these files contain the XML to merge with existing config files when the package is installed. Bei der Deinstallation eines Pakets wird derselbe XML-Code entfernt.When a package is uninstalled, that same XML is removed.
  • Schließen Sie die Dateien app.config.install.xdt und web.config.install.xdt in den Ordner content Ihres Pakets ein, und verwenden Sie dabei XDT-Syntax zur Beschreibung der gewünschten Änderungen.Include app.config.install.xdt and web.config.install.xdt files in your package's content folder, using XDT syntax to describe the desired changes. Mit dieser Option können Sie auch eine Datei vom Typ .uninstall.xdt einschließen, um Änderungen zurückzusetzen, wenn das Paket aus dem Projekt entfernt wird.With this option you can also include a .uninstall.xdt file to reverse changes when the package is removed from a project.

Hinweis

Transformationen gelten nicht für .config-Dateien, auf die ein Link in Visual Studio verweist.Transformations are not applied to .config files referenced as a link in Visual Studio.

Der Vorteil bei der Verwendung von XDT besteht darin, dass zwei statische Dateien nicht einfach zusammengeführt werden, sondern eine Syntax für die Bearbeitung der Struktur eines Using-Elements in XML DOM sowie eines zugehörigen Attributs mit voller XPath-Unterstützung bereitgestellt wird.The advantage of using XDT is that instead of simply merging two static files, it provides a syntax for manipulating the structure of an XML DOM using element and attribute matching using full XPath support. XDT kann anschließend Elemente hinzufügen, aktualisieren oder entfernen, Elemente an einer bestimmten Stelle anordnen oder Elemente ersetzen/entfernen (einschließlich untergeordneter Knoten).XDT can then add, update, or remove elements, place new elements at a specific location, or replace/remove elements (including child nodes). Dadurch wird die Erstellung von Transformationen zur Deinstallation erleichtert, bei denen sämtliche Transformationen zurückgesetzt werden, die während der Paketinstallation erfolgt sind.This makes it straightforward to create uninstall transforms that back out all transformations done during package installation.

XML-TransformationenXML transforms

Die Dateien app.config.transform und web.config.transform in dem Ordner content eines Pakets enthalten nur die Elemente, die in den vorhandenen Dateien app.config und web.config des Projekts zusammengeführt werden sollen.The app.config.transform and web.config.transform in a package's content folder contain only those elements to merge into the project's existing app.config and web.config files.

Angenommen, das Projekt weist zu Beginn folgende Inhalte in der Datei web.config auf:As an example, suppose the project initially contains the following content in web.config:

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

Wenn Sie ein MyNuModule-Element während der Paketinstallation zum Abschnitt modules hinzufügen möchten, erstellen Sie im Ordner content des Pakets eine Datei vom Typ web.config.transform, die wie folgt aussieht:To add a MyNuModule element to the modules section during package install, create a web.config.transform file in the package's content folder that looks like this:

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

Nach der Installation des Pakets durch NuGet wird die Datei web.config wie folgt angezeigt:After NuGet installs the package, web.config will appear as follows:

<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 Abschnitt modules nicht ersetzt hat. Der neue Eintrag wurde lediglich durch das Hinzufügen neuer Elemente und Attribute zusammengeführt.Notice that NuGet didn't replace the modules section, it just merged the new entry into it by adding only new elements and attributes. NuGet ändert keine vorhandenen Elemente oder Attribute.NuGet will not change any existing elements or attributes.

Wenn das Paket deinstalliert wird, überprüft NuGet die .transform-Dateien erneut und entfernt die enthaltenen Elemente aus den entsprechenden .config-Dateien.When the package is uninstalled, NuGet will examine the .transform files again and remove the elements it contains from the appropriate .config files. Beachten Sie, dass dieser Prozess keine Auswirkungen auf die Zeilen in der Datei .config hat, die Sie nach der Paketinstallation ändern.Note that this process will not affect any lines in the .config file that you modify after package installation.

In einem umfangreicheren Beispiel fügt das Paket Error Logging Modules and Handlers for ASP.NET (ELMAH) (Module für die Fehlerprotokollierung und Handlers für ASP.NET) viele Einträge zu web.config hinzu, die bei der Deinstallation eines Pakets wieder entfernt werden.As a more extensive example, the Error Logging Modules and Handlers for ASP.NET (ELMAH) package adds many entries into web.config, which are again removed when a package is uninstalled.

Wenn Sie die zugehörige Datei web.config.transform überprüfen möchten, laden Sie das ELMAH-Paket über den oben stehenden Link herunter, ändern Sie die Paketerweiterung von .nupkg in .zip, und öffnen Sie anschließend content\web.config.transform in dieser ZIP-Datei.To examine its web.config.transform file, download the ELMAH package from the link above, change the package extension from .nupkg to .zip, and then open content\web.config.transform in that ZIP file.

Erstellen Sie ein neues ASP.NET-Projekt in Visual Studio (die Vorlage ist unter Visual C# > Web im Dialogfeld „Neues Projekt“ zu finden), und wählen Sie eine leere ASP.NET-App aus, um die Auswirkungen der Installation und Deinstallation des Pakets sehen zu können.To see the effect of installing and uninstalling the package, create a new ASP.NET project in Visual Studio (the template is under Visual C# > Web in the New Project dialog), and select an empty ASP.NET application. Öffnen Sie web.config, um den zugehörigen ursprünglichen Status anzuzeigen.Open web.config to see its initial state. Klicken Sie anschließend mit der rechten Maustaste auf das Projekt, wählen Sie NuGet-Pakete verwalten aus, suchen Sie auf der Website nuget.org nach ELMAH, und installieren Sie die neueste Version.Then right-click the project, select Manage NuGet Packages, browse for ELMAH on nuget.org, and install the latest version. Beachten Sie alle an web.config vorgenommenen Änderungen.Notice all the changes to web.config. Wenn Sie das Paket jetzt deinstallieren, können Sie sehen, wie web.config in den zugehörigen ursprünglichen Status zurückversetzt wird.Now uninstall the package and you see web.config revert to its prior state.

XDT-TransformationenXDT transforms

Sie können Konfigurationsdateien über die XDT-Syntax ändern.You can modify config files using XDT syntax. Sie können auch veranlassen, dass NuGet Token über Projekteigenschaften ersetzt, indem der Eigenschaftenname innerhalb der Trennzeichen $ (ohne Berücksichtigung der Groß-/Kleinschreibung) eingeschlossen wird.You can also have NuGet replace tokens with project properties by including the property name within $ delimiters (case-insensitive).

In der folgenden Datei app.config.install.xdt wird beispielsweise ein appSettings-Element mit den Werten FullPath, FileName, und ActiveConfigurationSettings des Projekts in app.config eingefügt:For example, the following app.config.install.xdt file will insert an appSettings element into app.config containing the FullPath, FileName, and ActiveConfigurationSettings values from the project:

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

In einem weiteren Beispiel wird davon ausgegangen, dass das Projekt zu Beginn folgende Inhalte in der Datei web.config aufweist:For another example, suppose the project initially contains the following content in web.config:

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

Wenn Sie während der Paketinstallation ein MyNuModule-Element zum Abschnitt modules hinzufügen möchten, würde die Datei web.config.install.xdt des Pakets Folgendes enthalten:To add a MyNuModule element to the modules section during package install, the package's web.config.install.xdt would contain the following:

<?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 sieht web.config wie folgt aus:After installing the package, web.config will look like this:

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

Damit während der Deinstallation des Pakets nur das Element MyNuModule entfernt wird, sollte die Datei web.config.uninstall.xdt Folgendes enthalten:To remove only the MyNuModule element during package uninstall, the web.config.uninstall.xdt file should contain the following:

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