Trasformazione del codice sorgente e dei file di configurazione

Una trasformazione del codice sorgente applica la sostituzione unidirezionale dei token ai file nelle cartelle 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à del progetto di Visual Studio . In questo modo è possibile inserire un file nello spazio dei nomi del progetto o personalizzare il codice che verrebbe solitamente inserito in global.asax in un progetto ASP.NET.

Una trasformazione del file di configurazione consente di modificare i file già esistenti in un progetto di destinazione, ad esempio web.config e app.config. Ad esempio, il pacchetto potrebbe dover aggiungere un elemento alla modules sezione nel file di configurazione. Questa trasformazione viene eseguita includendo file speciali nel pacchetto che descrivono le sezioni da aggiungere ai file di configurazione. Quando un pacchetto viene disinstallato, le stesse modifiche vengono quindi invertite, rendendo questa trasformazione bidirezionale.

Specifica delle trasformazioni del codice sorgente

I file che si desidera inserire dal pacchetto nel progetto devono trovarsi all'interno delle cartelle content e contentFiles del pacchetto. Ad esempio, se si vuole che un file denominato ContosoData.cs sia installato in una Models cartella del progetto di destinazione, deve trovarsi all'interno delle content\Models cartelle e contentFiles\{lang}\{tfm}\Models nel pacchetto.
Per indicare a NuGet di applicare la sostituzione dei token in fase di installazione, aggiungere .pp al nome del file del codice sorgente. Dopo l'installazione, il file non avrà l'estensione .pp .

Ad esempio, per eseguire trasformazioni in ContosoData.cs, denominare il file nel pacchetto ContosoData.cs.pp. Dopo l'installazione verrà visualizzato come ContosoData.cs.
Nel file del codice sorgente usare token senza distinzione tra maiuscole e minuscole del modulo $token$ per indicare i valori che NuGet deve sostituire con le proprietà del progetto:
```
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 presupponendo che lo spazio dei nomi radice del progetto di destinazione sia Fabrikam.

Il $rootnamespace$ token è la proprietà del progetto più comunemente usata. Tutte le altre sono elencate nelle proprietà del progetto. Tenere presente, naturalmente, che alcune proprietà potrebbero essere specifiche del tipo di progetto.

Specificare le trasformazioni nei file di configurazione

Come descritto nelle sezioni seguenti, le trasformazioni dei file di configurazione possono essere eseguite in due modi:

Includere app.config.transform e web.config.transform file nella cartella del content pacchetto, in cui l'estensione .transform indica a NuGet che questi file contengono il codice XML da unire con i file di configurazione esistenti quando il pacchetto è installato. Quando un pacchetto viene disinstallato, lo stesso codice XML viene rimosso.
Includere app.config.install.xdt e web.config.install.xdt file nella cartella del content pacchetto, usando la sintassi XDT per descrivere le modifiche desiderate. Con questa opzione è anche possibile includere un .uninstall.xdt file per annullare le modifiche quando il pacchetto viene rimosso da un progetto.

Annotazioni

Le trasformazioni non vengono applicate ai .config file a cui viene fatto riferimento come collegamento in Visual Studio.

Il vantaggio dell'uso di XDT è che invece di unire semplicemente due file statici, fornisce una sintassi per modificare la struttura di un DOM XML usando l'elemento e la corrispondenza degli attributi usando il supporto XPath completo. XDT può quindi aggiungere, aggiornare o rimuovere elementi, posizionare nuovi elementi in una posizione specifica o sostituire/rimuovere elementi (inclusi i nodi figlio). In questo modo è semplice creare trasformazioni di disinstallazione che eseprima tutte le trasformazioni eseguite durante l'installazione del pacchetto.

Trasformazioni XML

I app.config.transform e web.config.transform nella cartella di content di un pacchetto contengono solo quegli elementi da integrare ai file esistenti di app.config e web.config del progetto.

Si supponga, ad esempio, che il progetto contenga inizialmente il contenuto seguente 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, crea un file web.config.transform nella cartella content del pacchetto che appare come segue:

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

Dopo che NuGet ha installato il pacchetto, web.config verrà visualizzato come segue:

<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 modules sezione, ma ha appena unito la nuova voce aggiungendo solo nuovi elementi e attributi. NuGet non modificherà elementi o attributi esistenti.

Quando il pacchetto viene disinstallato, NuGet esaminerà nuovamente i .transform file e rimuoverà gli elementi contenuti dai file appropriati .config . Si noti che questo processo non influirà sulle righe nel .config file modificato dopo l'installazione del pacchetto.

Come esempio più completo, i moduli di registrazione degli errori e i gestori per il pacchetto ASP.NET (ELMAH) aggiungono molte voci in web.config, che vengono nuovamente rimosse quando un pacchetto viene disinstallato.

Per esaminare il 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.

Per visualizzare l'effetto dell'installazione e della disinstallazione del pacchetto, creare un nuovo progetto di ASP.NET in Visual Studio (il modello si trova in Visual C# > Web nella finestra di dialogo Nuovo progetto) e selezionare un'applicazione ASP.NET vuota. Aprire web.config per visualizzare lo stato iniziale. Fare quindi clic con il pulsante destro del mouse sul progetto, scegliere Gestisci pacchetti NuGet, cercare ELMAH in nuget.org e installare la versione più recente. Si notino tutte le modifiche apportate a web.config. Ora disinstalla il pacchetto e vedrai web.config ritornare allo stato precedente.

Trasformazioni XDT

Annotazioni

Come indicato nella sezione relativa ai problemi di compatibilità dei pacchetti della documentazione per la migrazione da packages.config a PackageReference, le trasformazioni XDT come descritto di seguito sono supportate solo da packages.config. Se si aggiungono i file seguenti al pacchetto, i consumer che usano il pacchetto con PackageReference non avranno le trasformazioni applicate (fare riferimento a questo esempio per rendere le trasformazioni XDT funzionanti conPackageReference).

È possibile modificare i file di configurazione usando la sintassi XDT. È anche possibile fare in modo che NuGet sostituisca i token con le proprietà del progetto includendo il nome della proprietà all'interno $ dei delimitatori (senza distinzione tra maiuscole e minuscole).

Ad esempio, il file seguente app.config.install.xdt inserisce un appSettings elemento in app.config contenente i FullPathvalori , FileNamee ActiveConfigurationSettings del progetto:

<?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 un altro esempio, si supponga che il progetto contenga inizialmente il contenuto seguente 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 web.config.install.xdt del pacchetto conterrà quanto segue:

<?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 aver installato il pacchetto, web.config avrà un aspetto simile al seguente:

<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 deve contenere quanto segue:

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

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-10-31