Impostazioni di configurazione del runtime .NET

  • Articolo

.NET 5+ (incluse le versioni di .NET Core) supporta l'uso di file di configurazione e variabili di ambiente per configurare il comportamento delle applicazioni .NET.

Nota

Gli articoli di questa sezione riguardano la configurazione del runtime .NET stesso. Se si esegue la migrazione a .NET Core 3.1 o versione successiva e si sta cercando una sostituzione del file app.config oppure se si vuole semplicemente usare i valori di configurazione personalizzati nell'app .NET, vedere la classe Microsoft.Extensions.Configuration.ConfigurationBuilder e Configurazione in .NET.

L'uso di queste impostazioni è un'opzione interessante se:

  • Non si è proprietari o non si controlla il codice sorgente per un'applicazione e pertanto non è possibile configurarlo a livello di codice.
  • Più istanze dell'applicazione vengono eseguite contemporaneamente in un singolo sistema e si vuole configurare ogni istanza per ottenere prestazioni ottimali.

.NET offre i meccanismi seguenti per la configurazione del comportamento del runtime .NET:

Suggerimento

La configurazione di un'opzione tramite una variabile di ambiente applica l'impostazione a tutte le app .NET. La configurazione di un'opzione nel file runtimeconfig.json o nel file di progetto applica l'impostazione solo a tale applicazione.

Alcuni valori di configurazione possono essere impostati anche a livello di codice chiamando il metodo AppContext.SetSwitch.

Gli articoli in questa sezione della documentazione sono organizzati per categoria, ad esempio debug e Garbage Collection. Se applicabile, vengono visualizzate le opzioni di configurazione per i file runtimeconfig.json, le proprietà di MSBuild, le variabili di ambiente e, per riferimento incrociato, i file app.config per i progetti .NET Framework.

runtimeconfig.json

Quando un progetto viene compilato, viene generato un file [nomeapp].runtimeconfig.json nella directory di output. Se esiste un file runtimeconfig.template.json nella stessa cartella del file di progetto, tutte le opzioni di configurazione contenute vengono inserite nel file [nomeapp].runtimeconfig.json. Se si compila l'app manualmente, inserire eventuali opzioni di configurazione nel file runtimeconfig.template.json. Se si esegue semplicemente l'app, inserirle direttamente nel file [nomeapp].runtimeconfig.json.

Nota

  • Il file [nomeapp].runtimeconfig.json verrà sovrascritto nelle build successive.
  • Se OutputType dell'app non è Exe e si vuole che le opzioni di configurazione vengano copiate da runtimeconfig.template.json a [nomeapp].runtimeconfig.json, è necessario impostare in modo esplicito GenerateRuntimeConfigurationFiles su true nel file di progetto. Per le app che richiedono un file runtimeconfig.json, per impostazione predefinita questa proprietà è true.

Specificare le opzioni di configurazione del runtime nella sezione configProperties del file runtimeconfig.json o runtimeconfig.template.json. Questa sezione presenta il formato seguente:

"configProperties": {
  "config-property-name1": "config-value1",
  "config-property-name2": "config-value2"
}

File [nomeapp].runtimeconfig.json di esempio

Se si inseriscono le opzioni nel file JSON di output, annidarle nella proprietà runtimeOptions.

{
  "runtimeOptions": {
    "tfm": "netcoreapp3.1",
    "framework": {
      "name": "Microsoft.NETCore.App",
      "version": "3.1.0"
    },
    "configProperties": {
      "System.Globalization.UseNls": true,
      "System.Net.DisableIPv6": true,
      "System.GC.Concurrent": false,
      "System.Threading.ThreadPool.MinThreads": 4,
      "System.Threading.ThreadPool.MaxThreads": 25
    }
  }
}

File runtimeconfig.template.json di esempio

Se si inseriscono le opzioni nel file JSON del modello, omettere la proprietà runtimeOptions.

{
  "configProperties": {
    "System.Globalization.UseNls": true,
    "System.Net.DisableIPv6": true,
    "System.GC.Concurrent": false,
    "System.Threading.ThreadPool.MinThreads": "4",
    "System.Threading.ThreadPool.MaxThreads": "25"
  }
}

proprietà di MSBuild

È possibile impostare alcune opzioni di configurazione del runtime usando le proprietà di MSBuild nel file con estensione csproj o vbproj di progetti .NET di tipo SDK. Le proprietà di MSBuild hanno la precedenza sulle opzioni impostate nel file runtimeconfig.template.json.

Per le impostazioni di configurazione del runtime che non hannouna proprietà di MSBuild specifica, è possibile usare invece l'elemento RuntimeHostConfigurationOption di MSBuild. Usare il nome dell'impostazione runtimeconfig.json come valore dell'attributo Include.

Di seguito è riportato un file di progetto di tipo SDK di esempio con proprietà di MSBuild per la configurazione del comportamento del runtime .NET:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.1</TargetFramework>
  </PropertyGroup>

  <PropertyGroup>
    <ConcurrentGarbageCollection>false</ConcurrentGarbageCollection>
    <ThreadPoolMinThreads>4</ThreadPoolMinThreads>
    <ThreadPoolMaxThreads>25</ThreadPoolMaxThreads>
  </PropertyGroup>

  <ItemGroup>
    <RuntimeHostConfigurationOption Include="System.Globalization.UseNls" Value="true" />
    <RuntimeHostConfigurationOption Include="System.Net.DisableIPv6" Value="true" />
  </ItemGroup>

</Project>

Le proprietà di MSBuild per la configurazione del comportamento del runtime sono indicate nei singoli articoli per ogni area, ad esempio Garbage Collection. Sono elencate anche nella sezione Configurazione del runtime delle informazioni di riferimento sulle proprietà di MSBuild per i progetti in stile SDK.

Variabili di ambiente

Le variabili di ambiente possono essere usate per fornire alcune informazioni di configurazione del runtime. Le manopole di configurazione specificate come variabili di ambiente hanno in genere il prefisso DOTNET_.

Nota

.NET 6 standardizza il prefisso DOTNET_ anziché COMPlus_ per le variabili di ambiente che configurano il comportamento di runtime di .NET. Tuttavia, il prefisso COMPlus_ continuerà a funzionare. Se si usa una versione precedente del runtime .NET, è comunque consigliabile usare il prefisso COMPlus_ per le variabili di ambiente.

È possibile definire le variabili di ambiente dal Pannello di controllo di Windows, dalla riga di comando o a livello di codice chiamando il metodo Environment.SetEnvironmentVariable(String, String) nei sistemi basati su Windows e Unix.

Gli esempi seguenti illustrano come impostare una variabile di ambiente dalla riga di comando:

# Windows
set DOTNET_GCRetainVM=1

# Powershell
$env:DOTNET_GCRetainVM="1"

# Unix
export DOTNET_GCRetainVM=1

Vedi anche