Configurazioni comuni di NuGet

  • Articolo

Il comportamento di NuGet è basato sulle impostazioni accumulate in uno o più NuGet.Config file (XML) che possono esistere a livello di soluzione (progetto se non viene usata alcuna soluzione), utente e livello di computer. Un file NuGetDefaults.Config globale configura anche in particolare le origini dei pacchetti. Le impostazioni si applicano a tutti i comandi eseguiti nell'interfaccia della riga di comando, nella console di Gestione pacchetti e nell'interfaccia utente di Gestione pacchetti.

Percorsi e usi dei file di configurazione

Ambito Posizione del file NuGet.Config Descrizione
Soluzione Cartella corrente (ovvero la cartella della soluzione) o qualsiasi cartella fino alla radice dell'unità. Nella cartella di una soluzione le impostazioni si applicano a tutti i progetti presenti nelle sottocartelle. Si noti che se un file di configurazione viene inserito in una cartella di progetto, non ha alcun effetto su tale progetto. Quando si ripristina un progetto nella riga di comando, la directory del progetto viene considerata come la directory della soluzione, che può causare differenze nel comportamento durante il ripristino del progetto e della soluzione.
User Windows:%appdata%\NuGet\NuGet.Config
Mac/Linux:~/.config/NuGet/NuGet.Config o ~/.nuget/NuGet/NuGet.Config (varia in base agli strumenti)
Le configurazioni aggiuntive sono supportate in tutte le piattaforme. Queste configurazioni non possono essere modificate dagli strumenti.
Windows:%appdata%\NuGet\config\*.Config
Mac/Linux:~/.config/NuGet/config/*.config o ~/.nuget/config/*.config		 Impostazioni si applicano a tutte le operazioni, ma vengono sottoposte a override da qualsiasi impostazione a livello di soluzione.
Computer Windows:%ProgramFiles(x86)%\NuGet\Config
Mac/Linux:/etc/opt/NuGet/Config (Linux) o /Library/Application Support (Mac) per impostazione predefinita. Se $NUGET_COMMON_APPLICATION_DATA non è né null né vuoto, invece $NUGET_COMMON_APPLICATION_DATA/NuGet/Config		 Impostazioni si applicano a tutte le operazioni nel computer, ma vengono sottoposte a override da qualsiasi impostazione a livello di utente o soluzione.

Nota

In Mac/Linux il percorso del file di configurazione utente varia in base agli strumenti. L'interfaccia della riga di comando di .NET usa la ~/.nuget/NuGet cartella , mentre Mono usa la ~/.config/NuGet cartella .

In Mac/Linux il percorso del file di configurazione a livello di utente varia in base agli strumenti

In Mac/Linux il percorso del file di configurazione utente varia in base agli strumenti. La maggior parte degli utenti usa strumenti che cercano il file di configurazione utente nella ~/.nuget/NuGet cartella . Questi altri strumenti cercano il file di configurazione utente nella ~/.config/NuGet cartella :

  • Mono
  • NuGet.exe
  • Visual Studio 2019 per Mac (e versioni precedenti)
  • Visual Studio 2022 per Mac (e versioni successive), solo quando si lavora su progetti Mono classici.

Se gli strumenti usati includono entrambe le posizioni, è consigliabile consolidarli seguendo questa procedura per consentire l'uso di un solo file di configurazione a livello di utente:

  1. Controllare il contenuto dei due file di configurazione a livello di utente e mantenere quello desiderato nella ~/.nuget/NuGet cartella.
  2. Impostare il collegamento simbolico da ~/.nuget/NuGet a ~/.config/NuGet. Ad esempio, eseguire il comando bash: ln -s ~/.nuget/NuGet ~/.config/NuGet.

Note per versioni precedenti di NuGet:

  • NuGet 3.3 e versioni precedenti usavano una cartella .nuget per le impostazioni a livello di soluzione. Questa cartella non viene usata in NuGet 3.4+.
  • Per NuGet da 2.6 a 3.x, il file di configurazione a livello di computer in Windows si trovava in %ProgramData%\NuGet\Config[\{IDE}[\{Version}[\{SKU}]]]\NuGet.Config, dove {IDE} può essere VisualStudio, {Version} era la versione di Visual Studio, 14.0ad esempio e {SKU} è Community, Proo Enterprise. Per eseguire la migrazione delle impostazioni a NuGet 4.0+, copiare semplicemente il file di configurazione in %ProgramFiles(x86)%\NuGet\Config. In Linux, questo percorso precedente era /etc/opte in Mac, /Library/Application Support.

Modifica delle impostazioni di configurazione

Un file NuGet.Config è un semplice file di testo XML contenente coppie chiave/valore, come illustrato nell'argomento Impostazioni di configurazione NuGet.

Le impostazioni vengono gestite usando il comando config dell'interfaccia della riga di comando di NuGet:

  • Per impostazione predefinita, le modifiche vengono apportate al file di configurazione a livello di utente. (In Mac/Linux, il percorso del file di configurazione a livello di utente varia in base agli strumenti)
  • Per modificare le impostazioni in un file diverso, usare l'opzione -configFile. In questo caso i file possono usare qualsiasi nome.
  • Per le chiavi la distinzione tra maiuscole e minuscole si applica sempre.
  • L'elevazione è necessaria per modificare le impostazioni nel file delle impostazioni a livello di computer.

Avviso

Anche se è possibile modificare il file in qualsiasi editor di testo, NuGet (versioni 3.4.3 e successive) ignora senza avvisare l'intero file di configurazione se contiene XML non valido (tag non corrispondenti, virgolette non valide e così via). Per questo motivo è preferibile gestire le impostazioni usando nuget config.

Impostazione di un valore

Windows:

# Set repositoryPath in the user-level config file
nuget config -set repositoryPath=c:\packages 

# Set repositoryPath in solution-level files
nuget config -set repositoryPath=c:\packages -configfile c:\my.Config
nuget config -set repositoryPath=c:\packages -configfile .\myApp\NuGet.Config

# Set repositoryPath in the computer-level file (requires elevation)
nuget config -set repositoryPath=c:\packages -configfile %ProgramFiles(x86)%\NuGet\Config\NuGet.Config

Mac/Linux:

# Set repositoryPath in the user-level config file
nuget config -set repositoryPath=/home/packages 

# Set repositoryPath in solution-level files
nuget config -set repositoryPath=/home/projects/packages -configfile /home/my.Config
nuget config -set repositoryPath=/home/packages -configfile home/myApp/NuGet.Config

# Set repositoryPath in the computer-level file (requires elevation)
nuget config -set repositoryPath=/home/packages -configfile $XDG_DATA_HOME/NuGet.Config

Nota

In NuGet 3.4 e versioni successive è possibile usare le variabili di ambiente in qualsiasi valore, come in repositoryPath=%PACKAGEHOME% (Windows) e repositoryPath=$PACKAGEHOME (Mac/Linux).

Rimozione di un valore

Per rimuovere un valore, specificare una chiave con un valore vuoto.

# Windows
nuget config -set repositoryPath= -configfile c:\my.Config

# Mac/Linux
nuget config -set repositoryPath= -configfile /home/my.Config

Creazione di un nuovo file di configurazione

Copiare il modello seguente nel nuovo file e quindi usare nuget config -configFile <filename> per impostare i valori:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
</configuration>

Come vengono applicate le impostazioni

Più NuGet.Config file consentono di archiviare le impostazioni in posizioni diverse in modo che si applichino a una singola soluzione o a un gruppo di soluzioni. Queste impostazioni si applicano collettivamente a qualsiasi operazione NuGet richiamata dalla riga di comando o da Visual Studio, con le impostazioni "più vicine" a una soluzione o alla cartella corrente che ha la precedenza. Se uno strumento da riga di comando viene usato in un file di progetto, anziché in un file di soluzione, la directory del progetto viene usata come "directory della soluzione", che può causare comportamenti incoerenti quando è presente un NuGet.Config file in una sottodirectory del file di soluzione.

In particolare, NuGet carica le impostazioni dai diversi file di configurazione nell'ordine seguente:

  1. Il NuGetDefaults.Config file, che contiene le impostazioni correlate solo alle origini del pacchetto.
  2. Il file a livello di computer.
  3. Il file a livello di utente.
  4. Il file specificato con -configFile.
  5. I file trovati in ogni cartella nel percorso dalla radice dell'unità alla cartella corrente (dove nuget.exe viene richiamata o la cartella contenente la soluzione di Visual Studio). Ad esempio, se viene richiamato un comando in c:\A\B\C, NuGet cerca e carica i file di configurazione in c:\, quindi c:\Ac:\A\B, e infine c:\A\B\C.

Quando NuGet trova le impostazioni in questi file, le applica come segue:

  1. Per gli elementi singoli, NuGet sostituisce i valori trovati in precedenza per la stessa chiave. Ciò significa che le impostazioni "più vicine" alla cartella corrente o alla soluzione sostituiscono qualsiasi altro elemento trovato in precedenza. L'impostazione defaultPushSource in NuGetDefaults.Config, ad esempio, viene sostituita se esiste in un altro file di configurazione.
  2. Per gli elementi delle raccolte (ad esempio, <packageSources>), NuGet combina i valori di tutti i file di configurazione in una singola raccolta.
  3. Quando <clear /> è presente per un determinato nodo, NuGet ignora i valori di configurazione definiti in precedenza per tale nodo.

Suggerimento

Aggiungere un nuget.config file nella radice del repository della soluzione. Questa procedura è considerata una procedura consigliata perché promuove la ripetibilità e garantisce che diversi utenti abbiano la stessa configurazione NuGet.

Procedura dettagliata per le impostazioni

Si supponga di avere la struttura di cartelle seguente in due unità separate:

disk_drive_1
    User
disk_drive_2
    Project1
        Source
    Project2
        Source
    tmp

Si hanno poi quattro file NuGet.Config nelle posizioni seguenti con il contenuto indicato. Il file a livello di computer non è incluso in questo esempio, ma il comportamento sarà simile a quello del file a livello di utente.

File A. File a livello di utente, (%appdata%\NuGet\NuGet.Config in Windows, ~/.config/NuGet/NuGet.Config in Mac/Linux):

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <activePackageSource>
        <add key="NuGet official package source" value="https://api.nuget.org/v3/index.json" />
    </activePackageSource>
</configuration>

File B. disk_drive_2/NuGet.Config:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <config>
        <add key="repositoryPath" value="disk_drive_2/tmp" />
    </config>
    <packageRestore>
        <add key="enabled" value="True" />
    </packageRestore>
</configuration>

File C. disk_drive_2/Project1/NuGet.Config:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <config>
        <add key="repositoryPath" value="External/Packages" />
        <add key="defaultPushSource" value="https://MyPrivateRepo/ES/api/v2/package" />
    </config>
    <packageSources>
        <clear /> <!-- ensure only the sources defined below are used -->
        <add key="MyPrivateRepo - ES" value="https://MyPrivateRepo/ES/nuget" />
    </packageSources>
</configuration>

File D. disk_drive_2/Project2/NuGet.Config:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <packageSources>
        <!-- Add this repository to the list of available repositories -->
        <add key="MyPrivateRepo - DQ" value="https://MyPrivateRepo/DQ/nuget" />
    </packageSources>
</configuration>

NuGet quindi carica e applica le impostazioni come segue, a seconda della posizione da dove viene eseguita la chiamata:

  • Richiamato da disk_drive_1/users: viene usato solo il repository predefinito elencato nel file di configurazione a livello di utente (A), perché questo è l'unico file trovato in disk_drive_1.

  • Richiamato da disk_drive_2/ o disk_drive_/tmp: il file a livello di utente (A) viene caricato per primo, quindi NuGet passa alla radice di disk_drive_2 e trova il file (B). NuGet cerca anche un file di configurazione in /tmp ma non ne trova uno. Di conseguenza, viene usato il repository predefinito in nuget.org , il ripristino del pacchetto è abilitato e i pacchetti vengono espansi in disk_drive_2/tmp.

  • Richiamato da disk_drive_2/Project1 o disk_drive_2/Project1/Source: il file a livello di utente (A) viene caricato per primo, quindi NuGet carica il file (B) dalla radice di disk_drive_2, seguito dal file (C). Impostazioni in (C) eseguono l'override di quelli in (B) e (A), quindi il percorso in cui vengono installati i repositoryPath pacchetti è disk_drive_2/Project1/External/Packages anziché disk_drive_2/tmp. Inoltre, poiché (C) cancella <packageSources>, nuget.org non è più disponibile come origine e rimane solo https://MyPrivateRepo/ES/nuget.

  • Richiamato da disk_drive_2/Project2 o disk_drive_2/Project2/Source: il file a livello di utente (A) viene caricato prima seguito da file (B) e file (D). Poiché packageSources non viene cancellato, sia nuget.org che https://MyPrivateRepo/DQ/nuget sono disponibili come origini. I pacchetti vengono espansi in disk_drive_2/tmp come specificato in (B).

Configurazione aggiuntiva a livello di utente

A partire dalla versione 5.7, NuGet ha aggiunto il supporto per altri file di configurazione a livello di utente. In questo modo i fornitori di terze parti possono aggiungere altri file di configurazione utente senza elevazione dei privilegi. Questi file di configurazione si trovano nella cartella di configurazione standard a livello di utente all'interno di una config sottocartella. Tutti i file che terminano con .config o .Config verranno considerati. Questi file non possono essere modificati dagli strumenti standard.

Piattaforma del sistema operativo Configurazioni aggiuntive
Windows %appdata%\NuGet\config\*.Config
Mac/Linux ~/.config/NuGet/config/*.config oppure ~/.nuget/config/*.config

File delle impostazioni predefinite di NuGet

Lo scopo del file NuGetDefaults.Config è quello di specificare le origini da cui i pacchetti vengono installati e aggiornati e di controllare la destinazione predefinita per la pubblicazione dei pacchetti con nuget push. Poiché gli amministratori possono distribuire facilmente file NuGetDefaults.Config coerenti agli sviluppatori e ai computer di compilazione (ad esempio usando Criteri di gruppo), possono assicurarsi che tutti nell'organizzazione usino le origini dei pacchetti corrette invece di nuget.org.

Importante

Il file NuGetDefaults.Config non causa mai la rimozione di un pacchetto dalla configurazione NuGet di uno sviluppatore. Se dunque lo sviluppatore ha già usato NuGet e quindi l'origine del pacchetto nuget.org è già registrata, non verrà rimossa dopo la creazione di un file NuGetDefaults.Config.

Inoltre, né NuGetDefaults.Config altri meccanismi in NuGet possono impedire l'accesso a origini di pacchetti come nuget.org. Se un'organizzazione vuole bloccare tale accesso, deve usare altri mezzi, ad esempio i firewall per farlo.

NuGetDefaults.Config Posizione

La tabella seguente descrive la posizione di archiviazione prevista per il file NuGetDefaults.Config, a seconda del sistema operativo di destinazione:

Piattaforma del sistema operativo NuGetDefaults.Config Percorso
Windows Visual Studio 2017 o NuGet 4.x+:%ProgramFiles(x86)%\NuGet
Visual Studio 2015 e versioni precedenti o NuGet 3.x e versioni precedenti:%PROGRAMDATA%\NuGet
Mac/Linux $XDG_DATA_HOME (in genere ~/.local/share o /usr/local/share, a seconda della distribuzione del sistema operativo)

Impostazioni di NuGetDefaults.Config

  • packageSources: questa raccolta ha lo stesso significato di packageSources nei normali file di configurazione e specifica le origini predefinite. NuGet usa le origini in ordine durante l'installazione o l'aggiornamento di pacchetti nei progetti usando il formato di gestione packages.config. Per i progetti che usano il formato PackageReference, NuGet usa prima di tutto le origini locali, quindi le origini in condivisioni di rete, poi le origini HTTP, indipendentemente dall'ordine nei file di configurazione. NuGet Ignora sempre l'ordine delle origini con le operazioni di ripristino.

  • disabledPackageSources: questa raccolta ha anche lo stesso significato dei NuGet.Config file, in cui ogni origine interessata è elencata in base al nome e un true/false valore che indica se è disabilitato. In questo modo il nome e l'URL dell'origine possono rimanere in packageSources senza che debba essere attivata per impostazione predefinita. I singoli sviluppatori possono quindi riabilitare l'origine impostando il valore dell'origine su false in altri NuGet.Config file senza dover trovare di nuovo l'URL corretto. Questo è utile anche per fornire agli sviluppatori un elenco completo di URL delle origini interne per un'organizzazione, abilitando al contempo solo l'origine di un singolo team per impostazione predefinita.

  • defaultPushSource: specifica la destinazione predefinita per nuget push le operazioni, sostituendo l'impostazione predefinita predefinita di nuget.org. Amministrazione istrator può distribuire questa impostazione per evitare la pubblicazione di pacchetti interni nel pubblico nuget.org per errore, in quanto gli sviluppatori devono usare nuget push -Source specificamente per pubblicare in nuget.org.

Applicazione e NuGetDefaults.Config di esempio

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <!-- defaultPushSource key works like the 'defaultPushSource' key of NuGet.Config files. -->
    <!-- This can be used by administrators to prevent accidental publishing of packages to nuget.org. -->
    <config>
        <add key="defaultPushSource" value="https://contoso.com/packages/" />
    </config>

    <!-- Default Package Sources; works like the 'packageSources' section of NuGet.Config files. -->
    <!-- This collection cannot be deleted or modified but can be disabled/enabled by users. -->
    <packageSources>
        <add key="Contoso Package Source" value="https://contoso.com/packages/" />
        <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    </packageSources>

    <!-- Default Package Sources that are disabled by default. -->
    <!-- Works like the 'disabledPackageSources' section of NuGet.Config files. -->
    <!-- Sources cannot be modified or deleted either but can be enabled/disabled by users. -->
    <disabledPackageSources>
        <add key="nuget.org" value="true" />
    </disabledPackageSources>
</configuration>