File web.config

  • Articolo

web.config è un file letto da IIS e dal modulo ASP.NET Core per configurare un'app ospitata con IIS.

Posizione del file web.config

Per configurare correttamente il modulo ASP.NET Core, il file web.config deve essere presente nel percorso radice del contenuto (in genere il percorso base dell'app) dell'app distribuita. Corrisponde al percorso fisico del sito Web fornito a IIS. Il file web.config deve essere presente nella radice dell'app per abilitare la pubblicazione di più app mediante Distribuzione Web.

I file sensibili si trovano nel percorso fisico dell'app, ad esempio {ASSEMBLY}.runtimeconfig.json, {ASSEMBLY}.xml (commenti della documentazione XML) e {ASSEMBLY}.deps.json dove il segnaposto {ASSEMBLY} è il nome dell'assembly. Quando il file web.config è presente e il sito viene avviato normalmente, IIS non rende disponibili questi file sensibili se vengono richiesti. Se il file web.config non è presente, ha un nome non corretto o non è in grado di configurare il sito per l'avvio normale, IIS potrebbe rendere disponibili pubblicamente i file sensibili.

Il file web.config deve essere sempre presente nella distribuzione, deve essere denominato correttamente ed essere in grado di configurare il sito per l'avvio normale. Non rimuovere mai il file web.config da una distribuzione in produzione.

Se nel progetto non è presente un file web.config, il file viene creato con processPath e arguments corretti per la configurazione del modulo ASP.NET Core. Il file viene quindi spostato nell'output pubblicato.

Se nel progetto è presente un file web.config, il file viene trasformato con processPath e arguments corretti per la configurazione del modulo ASP.NET Core e spostato nell'output pubblicato. La trasformazione non modifica le impostazioni di configurazione di IIS incluse nel file.

Il file web.config può fornire ulteriori impostazioni di configurazione di IIS che controllano i moduli IIS attivi. Per informazioni sui moduli IIS in grado di elaborare le richieste con le app di ASP.NET Core, vedere l'argomento Moduli IIS.

La creazione, la trasformazione e la pubblicazione del file web.config sono operazioni gestite da una destinazione MSBuild (_TransformWebConfig) quando viene pubblicato il progetto. Questa destinazione si trova tra le destinazioni Web SDK (Microsoft.NET.Sdk.Web). L'SDK è impostato all'inizio del file di progetto:

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

Per impedire che Web SDK trasformi il file web.config, usare la proprietà <IsTransformWebConfigDisabled> nel file di progetto:

<PropertyGroup>
  <IsTransformWebConfigDisabled>true</IsTransformWebConfigDisabled>
</PropertyGroup>

Quando si disabilita la trasformazione del file in Web SDK, processPath e arguments devono essere impostati manualmente dallo sviluppatore. Per altre informazioni, vedere Modulo ASP.NET Core (ANCM) per IIS.

Configurazione del modulo core di ASP.NET con web.config

Il modulo principale ASP.NET è configurato con la aspNetCore sezione del system.webServer nodo nel file del web.config sito.

Il file seguente web.config viene pubblicato per una distribuzione dipendente dal framework e configura il modulo ASP.NET Core per gestire le richieste del sito:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath="dotnet"
                  arguments=".\MyApp.dll"
                  stdoutLogEnabled="false"
                  stdoutLogFile=".\logs\stdout"
                  hostingModel="inprocess" />
    </system.webServer>
  </location>
</configuration>

Di seguito web.config viene pubblicato per una distribuzione autonoma:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath=".\MyApp.exe"
                  stdoutLogEnabled="false"
                  stdoutLogFile=".\logs\stdout"
                  hostingModel="inprocess" />
    </system.webServer>
  </location>
</configuration>

La InheritInChildApplications proprietà è impostata su false per indicare che le impostazioni specificate all'interno dell'elemento <location> non vengono ereditate dalle app che risiedono in una sottodirectory dell'app.

Quando un'app viene distribuita in Servizio app di Azure, il percorso stdoutLogFile è impostato su \\?\%home%\LogFiles\stdout. Il percorso salva i log stdout nella LogFiles cartella , ovvero un percorso creato automaticamente dal servizio.

Per informazioni sulla configurazione della sotto-applicazione IIS, vedere Configurazione avanzata.

Attributi dell'elemento aspNetCore

Attributo Descrizione Predefinito
arguments

Attributo stringa facoltativo.

Argomenti per l'eseguibile specificato in processPath.
disableStartUpErrorPage

Attributo booleano facoltativo.

Se true, la pagina 502.5 - Errore del processo viene eliminata e la tabella codici di stato 502 configurata in ha la web.config precedenza.

 false
forwardWindowsAuthToken

Attributo booleano facoltativo.

Se true, il token viene inoltrato al processo figlio in %ASPNETCORE_PORT% ascolto su come intestazione "MS-ASPNETCORE-WINAUTHTOKEN" per ogni richiesta. È responsabilità del processo chiamare CloseHandle su questo token per ogni richiesta.

 true
hostingModel

Attributo stringa facoltativo.

Specifica il modello di hosting in-process (InProcess/inprocess) o out-of-process (OutOfProcess/outofprocess).

 OutOfProcess/outofprocess quando non è presente
processesPerApplication

Attributo Integer facoltativo.

Specifica il numero di istanze del processo specificato nell'impostazione processPath che possono essere attivate per ogni app.

†For hosting in-process, il valore è limitato a 1.

L'impostazione di processesPerApplication è sconsigliata. Questo attributo sarà rimosso nelle versioni future.

 Impostazione predefinita: 1
Min: 1
Max: 100†
processPath

Attributo stringa obbligatorio.

Percorso del file eseguibile che avvia un processo in ascolto delle richieste HTTP. I percorsi relativi sono supportati. Se il percorso inizia con ., viene considerato relativo alla radice del sito.
rapidFailsPerMinute

Attributo Integer facoltativo.

Specifica il numero di volte in cui il processo specificato in processPath può arrestarsi in modo anomalo al minuto. Se questo limite viene superato, il modulo smette di avviare il processo per la parte restante del minuto.

Non supportato con l'hosting in-process.

 Impostazione predefinita: 10
Min: 0
Max: 100
requestTimeout

Attributo Timespan facoltativo.

Specifica la durata per cui il modulo ASP.NET Core attende una risposta dal processo in ascolto su %ASPNETCORE_PORT%.

Nelle versioni del modulo ASP.NET Core fornito con ASP.NET Core 2.1 o versioni successive, requestTimeout viene specificato in ore, minuti e secondi.

Non è applicabile all'hosting in-process. Per l'hosting in-process, il modulo resta in attesa che l'app elabori la richiesta.

I valori validi per i segmenti della stringa relativi a minuti e secondi sono compresi nell'intervallo tra 0 e 59. L'utilizzo di 60 nel valore per minuti o secondi genera un errore 500 - Interno del server.

 Impostazione predefinita: 00:02:00
Min: 00:00:00
Max: 360:00:00
shutdownTimeLimit

Attributo Integer facoltativo.

Durata in secondi in cui il modulo attende l'arresto normale dell'eseguibile quando viene rilevato il app_offline.htm file.

 Impostazione predefinita: 10
Min: 0
Max: 600
startupTimeLimit

Attributo Integer facoltativo.

Durata in secondi per cui il modulo attende l'avvio di un processo in ascolto sulla porta da parte del file eseguibile. Se questo limite di tempo viene superato, il modulo termina il processo.

Durante l'hosting in-process: il processo non viene riavviato e non usa l'impostazione rapidFailsPerMinute .

Durante l'hosting out-of-process: il modulo tenta di riavviare il processo quando riceve una nuova richiesta e continua a tentare di riavviare il processo nelle richieste in ingresso successive, a meno che l'app non riesca a avviare rapidFailsPerMinute il numero di volte nell'ultimo minuto in sequenza.

Un valore pari a 0 (zero) non è considerato un timeout infinito.

 Impostazione predefinita: 120
Min: 0
Max: 3600
stdoutLogEnabled

Attributo booleano facoltativo.

Se true, stdout e stderr per il processo specificato in processPath vengono reindirizzati al file specificato in stdoutLogFile.

 false
stdoutLogFile

Attributo stringa facoltativo.

Specifica il percorso di file relativo o assoluto per il quale stdout e stderr dal processo specificato in processPath vengono registrati. I percorsi relativi sono relativi alla radice del sito. Qualsiasi percorso che inizia con . è relativo al sito radice e tutti gli altri percorsi vengono trattati come percorsi assoluti. Le eventuali cartelle specificate nel percorso vengono create dal modulo quando viene creato il file di log. Usando delimitatori di sottolineatura, vengono aggiunti un timestamp, un ID processo e un'estensione di file (.log) all'ultimo segmento del stdoutLogFile percorso. Se .\logs\stdout viene specificato come valore, un log stdout di esempio viene salvato come stdout_20180205194132_1934.log nella logs cartella quando salvato il 5 febbraio 2018 alle 19:41:32 con ID processo 1934.

 aspnetcore-stdout

Impostare le variabili di ambiente

È possibile specificare le variabili di ambiente per il processo nell'attributo processPath. Specificare una variabile di ambiente con l'elemento figlio <environmentVariable> di un elemento della raccolta <environmentVariables>. Le variabili di ambiente impostate in questa sezione hanno la precedenza sulle variabili di ambiente di sistema.

Nell'esempio seguente vengono impostate due variabili di ambiente in web.config. ASPNETCORE_ENVIRONMENT configura l'ambiente dell'app su Development. Uno sviluppatore può impostare temporaneamente questo valore nel web.config file per forzare il caricamento della pagina eccezioni per sviluppatori durante il debug di un'eccezione dell'app. CONFIG_DIR è un esempio di variabile di ambiente definita dall'utente, in cui lo sviluppatore ha scritto il codice che legge il valore all'avvio in modo da formare un percorso per il caricamento del file di configurazione dell'app.

<aspNetCore processPath="dotnet"
      arguments=".\MyApp.dll"
      stdoutLogEnabled="false"
      stdoutLogFile=".\logs\stdout"
      hostingModel="inprocess">
  <environmentVariables>
    <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
    <environmentVariable name="CONFIG_DIR" value="f:\application_config" />
  </environmentVariables>
</aspNetCore>

Nota

Un'alternativa all'impostazione diretta dell'ambiente in web.config consiste nell'includere la <EnvironmentName> proprietà nel profilo di pubblicazione (.pubxml) o nel file di progetto. Questo approccio imposta l'ambiente in web.config quando il progetto viene pubblicato:

<PropertyGroup>
  <EnvironmentName>Development</EnvironmentName>
</PropertyGroup>

Avviso

Impostare la variabile di ambiente ASPNETCORE_ENVIRONMENT su Development solo in server di gestione temporanea e test che non sono accessibili da reti non attendibili, ad esempio Internet.

Configurazione di IIS con web.config

La <system.webServer> configurazione iis è influenzata dalla sezione di web.config per gli scenari IIS funzionali per le app ASP.NET Core con il modulo ASP.NET Core. Ad esempio, la configurazione di IIS è funzionale per la compressione dinamica. Se IIS è configurato a livello di server per l'uso della compressione dinamica, l'elemento <urlCompression> nel file dell'app web.config può disabilitarlo per un'app ASP.NET Core.

Per ulteriori informazioni, vedi gli argomenti seguenti:

Per impostare le variabili di ambiente per le singole app in esecuzione in pool di app isolate (supportato per IIS 10.0 o versione successiva), vedere la sezione relativa al AppCmd.exe comando dell'argomento Variabili <environmentVariables> di ambiente nella documentazione di riferimento di IIS.

Sezioni di configurazione di web.config

Le sezioni di configurazione di ASP.NET app 4.x in web.config non vengono usate dalle app ASP.NET Core per la configurazione:

  • <system.web>
  • <appSettings>
  • <connectionStrings>
  • <location>

Le applicazioni ASP.NET Core vengono configurate tramite altri provider di configurazione. Per altre informazioni, vedere Configurazione.

Trasformare web.config

Se è necessario trasformare web.config in fase di pubblicazione, vedere Trasformare web.config. Potrebbe essere necessario trasformare web.config durante la pubblicazione per impostare le variabili di ambiente in base alla configurazione, al profilo o all'ambiente.

Risorse aggiuntive