Trasformazioni di codice sorgente e file di configurazioneTransforming source code and configuration files

Per i progetti che usano packages.config, NuGet supporta la capacità di eseguire trasformazioni del codice sorgente e dei file di configurazione in fase di installazione e disinstallazione dei pacchetti.For projects using packages.config, NuGet supports the ability to make transformations to source code and configuration files at package install and uninstall times. Vengono applicate solo le trasformazioni del codice sorgente quando viene installato un pacchetto in un progetto tramite PackageReference.Only Source code transformations are applied when a package is installed in a project using PackageReference.

Una trasformazione di codice sorgente applica una sostituzione dei token unidirezionale ai file nella cartella content o contentFiles del pacchetto (content per i clienti che usano packages.config e contentFiles per PackageReference) quando il pacchetto viene installato, dove i token fanno riferimento alle proprietà di progetto di 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. Ciò consente di inserire un file nello spazio dei nomi del progetto o di personalizzare il codice inserito in genere in global.asax in un progetto ASP.NET.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.

Una trasformazione di file di configurazione consente di modificare i file già esistenti in un progetto di destinazione, come web.config e 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. Ad esempio, potrebbe essere necessario aggiungere un elemento per il pacchetto alla sezione modules del file di configurazione.For example, your package might need to add an item to the modules section in the config file. Questa trasformazione viene eseguita includendo nel pacchetto file speciali che descrivono le sezioni da aggiungere ai file di configurazione.This transformation is done by including special files in the package that describe the sections to add to the configuration files. Quando si disinstalla un pacchetto, queste stesse modifiche vengono invertite, rendendola una trasformazione bidirezionale.When a package is uninstalled, those same changes are then reversed, making this a two-way transformation.

Specifica di trasformazioni di codice sorgenteSpecifying source code transformations

  1. I file da inserire dal pacchetto nel progetto devono trovarsi all'interno delle cartelle content e contentFiles del pacchetto.Files that you want to insert from the package into the project must be located within the package's content and contentFiles folders. Ad esempio, se si vuole che un file denominato ContosoData.cs venga installato in una cartella Models del progetto di destinazione, deve trovarsi all'interno delle cartelle content\Models e contentFiles\{lang}\{tfm}\Models nel pacchetto.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. Per indicare a NuGet di applicare la sostituzione dei token in fase di installazione, aggiungere .pp al nome file del codice sorgente.To instruct NuGet to apply token replacement at install time, append .pp to the source code file name. Dopo l'installazione, il file non avrà l'estensione .pp.After installation, the file will not have the .pp extension.

    Ad esempio, per eseguire trasformazioni in ContosoData.cs, denominare il file nel pacchetto ContosoData.cs.pp.For example, to make transformations in ContosoData.cs, name the file in the package ContosoData.cs.pp. Dopo l'installazione verrà visualizzato come ContosoData.cs.After installation it will appear as ContosoData.cs.

  3. Nel file del codice sorgente usare i token senza distinzione tra maiuscole e minuscole nel formato $token$ per indicare i valori che NuGet deve sostituire con le proprietà del progetto: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;
        }
    }
    

    Al momento dell'installazione, NuGet sostituisce $rootnamespace$ con Fabrikam supponendo il progetto di destinazione il cui spazio dei nomi radice è Fabrikam.Upon installation, NuGet replaces $rootnamespace$ with Fabrikam assuming the target project's whose root namespace is Fabrikam.

Il token $rootnamespace$ è la proprietà del progetto usata più di frequente. Tutte le altre sono elencate nelle proprietà del progetto.The $rootnamespace$ token is the most commonly used project property; all others are listed in project properties. Tenere in considerazione, naturalmente, che alcune proprietà potrebbero essere specifiche del tipo di progetto.Be mindful, of course, that some properties might be specific to the project type.

Specifica di trasformazioni di file di configurazioneSpecifying config file transformations

Come descritto nelle sezioni successive, le trasformazioni di file di configurazione possono essere eseguite in due modi:As described in the sections that follow, config file transformations can be done in two ways:

  • Includere i file app.config.transform e web.config.transform nella cartella content del pacchetto, dove l'estensione .transform indica a NuGet che questi file contengono il codice XML da unire con i file di configurazione esistenti quando il pacchetto viene installato.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. Quando si disinstalla un pacchetto, lo stesso codice XML viene rimosso.When a package is uninstalled, that same XML is removed.
  • Includere i file app.config.install.xdt e web.config.install.xdt nella cartella content del pacchetto usando la sintassi XDT per descrivere le modifiche desiderate.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. Con questa opzione è anche possibile includere un file .uninstall.xdt per ripristinare le modifiche quando il pacchetto viene rimosso da un progetto.With this option you can also include a .uninstall.xdt file to reverse changes when the package is removed from a project.

Nota

Le trasformazioni non vengono applicate ai file .config a cui si fa riferimento come collegamento in Visual Studio.Transformations are not applied to .config files referenced as a link in Visual Studio.

Il vantaggio dell'uso di XDT è dato dal fatto che, invece di unire semplicemente due file statici, fornisce una sintassi per la modifica della struttura di un DOM XML tramite la corrispondenza tra elementi e attributi basata sul supporto XPath completo.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 può quindi aggiungere, aggiornare o rimuovere elementi, inserire nuovi elementi in una posizione specifica oppure sostituire o rimuovere elementi (inclusi i nodi figlio).XDT can then add, update, or remove elements, place new elements at a specific location, or replace/remove elements (including child nodes). Ciò rende molto semplice creare trasformazioni di disinstallazione che annullano tutte le trasformazioni eseguite durante l'installazione del pacchetto.This makes it straightforward to create uninstall transforms that back out all transformations done during package installation.

Trasformazioni XMLXML transforms

app.config.transform e web.config.transform nella cartella content di un pacchetto contengono solo gli elementi da unire nei file app.config e web.config esistenti del progetto.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.

Ad esempio, si supponga che il progetto contenga inizialmente il contenuto seguente in web.config: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>

Per aggiungere un elemento MyNuModule alla sezione modules durante l'installazione del pacchetto, creare un file web.config.transform nella cartella content del pacchetto simile al seguente: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>

Dopo che NuGet ha installato il pacchetto, NuGet web.config avrà l'aspetto seguente: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>

Si noti che NuGet non ha sostituito la sezione modules, ha semplicemente unito la nuova voce al suo interno aggiungendo solo i nuovi elementi e attributi.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 non modificherà elementi o attributi esistenti.NuGet will not change any existing elements or attributes.

Quando il pacchetto viene disinstallato, NuGet esaminerà nuovamente i file .transform e rimuoverà gli elementi in esso contenuti dai file .config appropriati.When the package is uninstalled, NuGet will examine the .transform files again and remove the elements it contains from the appropriate .config files. Si noti che questo processo non avrà effetto sulle righe nel file .config modificate dopo l'installazione del pacchetto.Note that this process will not affect any lines in the .config file that you modify after package installation.

Come esempio più esteso, il pacchetto Error Logging Modules and Handlers (ELMAH) per ASP.NET aggiunge molte voci in web.config, che vengono nuovamente rimosse quando si disinstalla un pacchetto.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.

Per esaminare il relativo file web.config.transform, scaricare il pacchetto ELMAH dal collegamento precedente, modificare l'estensione del pacchetto da .nupkg a .zip e quindi aprire content\web.config.transform in tale file ZIP.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.

Per vedere l'effetto dell'installazione e della disinstallazione del pacchetto, creare un nuovo progetto ASP.NET in Visual Studio (il modello è disponibile in Visual C# > Web nella finestra di dialogo Nuovo progetto) e selezionare un'applicazione ASP.NET vuota.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. Aprire web.config per visualizzarne lo stato iniziale.Open web.config to see its initial state. Quindi fare clic con il pulsante destro del mouse sul progetto, selezionare Gestisci pacchetti NuGet, cercare ELMAH su nuget.org e installare la versione più recente.Then right-click the project, select Manage NuGet Packages, browse for ELMAH on nuget.org, and install the latest version. Notare tutte le modifiche apportate a web.config.Notice all the changes to web.config. Disinstallare quindi il pacchetto. web.config tornerà allo stato precedente.Now uninstall the package and you see web.config revert to its prior state.

Trasformazioni XDTXDT transforms

È possibile modificare i file di configurazione usando la sintassi XDT.You can modify config files using XDT syntax. È anche possibile fare in modo che NuGet sostituisca i token con le proprietà del progetto includendo il nome della proprietà all'interno di delimitatori $ (senza distinzione tra maiuscole e minuscole).You can also have NuGet replace tokens with project properties by including the property name within $ delimiters (case-insensitive).

Ad esempio, il file seguente app.config.install.xdt inserirà un elemento appSettings in app.config contenente i valori FullPath, FileName e ActiveConfigurationSettings dal progetto: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>

Per fare un altro esempio, si supponga che il progetto contenga inizialmente il contenuto seguente in web.config: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>

Per aggiungere un elemento MyNuModule alla sezione modules durante l'installazione del pacchetto, il file web.config.install.xdt del pacchetto dovrebbe contenere il codice seguente: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>

Dopo l'installazione del pacchetto, web.config sarà simile al seguente: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>

Per rimuovere solo l'elemento MyNuModule durante la disinstallazione del pacchetto, il file web.config.uninstall.xdt dovrebbe contenere il codice seguente: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>