ASP.NET Core Module (ANCM) per IIS

Articolo
11/30/2023

Nota

Questa non è la versione più recente di questo articolo. Per la versione corrente, vedere la versione .NET 8 di questo articolo.

Avviso

Questa versione di ASP.NET Core non è più supportata. Per altre informazioni, vedere Criteri di supporto di .NET e .NET Core. Per la versione corrente, vedere la versione .NET 8 di questo articolo.

Importante

Queste informazioni si riferiscono a un prodotto non definitive che può essere modificato in modo sostanziale prima che venga rilasciato commercialmente. Microsoft non riconosce alcuna garanzia, espressa o implicita, in merito alle informazioni qui fornite.

Per la versione corrente, vedere la versione .NET 8 di questo articolo.

Il modulo ASP.NET Core (ANCM) è un modulo IIS nativo che si collega alla pipeline IIS, consentendo alle applicazioni ASP.NET Core di lavorare con IIS. Eseguire app ASP.NET Core con IIS in uno dei due casi:

Hosting di un'app ASP.NET Core all'interno del processo di lavoro IIS (w3wp.exe), denominato modello di hosting in-process.
Inoltro di richieste Web a un'app back-end ASP.NET Core che esegue il Kestrel server, denominato modello di hosting out-of-process.

Esistono compromessi tra ognuno dei modelli di hosting. Per impostazione predefinita, il modello di hosting in-process viene usato a causa di prestazioni e diagnostica migliori.

Per altre informazioni e indicazioni per la configurazione, vedere gli argomenti seguenti:

Implementazioni del server Web in ASP.NET Core

Installare ASP.NET Core Module (ANCM)

Il modulo ASP.NET Core (ANCM) viene installato con il runtime di .NET Core dal bundle di hosting .NET Core. Il modulo ASP.NET Core è compatibile con le versioni precedenti e successive con le versioni in-support di .NET.

Le modifiche di rilievo e gli avvisi di sicurezza vengono segnalati nel repository Annunci. Gli annunci possono essere limitati a una versione specifica selezionando un filtro Etichetta .

Scaricare il programma di installazione mediante il collegamento seguente:

Programma di installazione del bundle di hosting .NET Core corrente (download diretto)

Per altre informazioni, inclusa l'installazione di una versione precedente del modulo, vedere Hosting Bundle.

Per un'esercitazione sulla pubblicazione di un'app ASP.NET Core in un server IIS, vedere Pubblicare un'app ASP.NET Core in IIS.

Il modulo ASP.NET Core (ANCM) è un modulo IIS nativo che collega la pipeline IIS a:

Ospitare un app ASP.NET Core all'interno del processo di lavoro IIS (w3wp.exe), denominato modello di hosting in-process.
Inoltrare le richieste Web a un'app back-end ASP.NET Core che esegue il Kestrel server, denominato modello di hosting out-of-process.

Versioni supportate di Windows:

Windows 7 o versione successiva
Windows Server 2012 R2 o versione successiva

In caso di hosting in-process, il modulo usa un'implementazione di server in-process per IIS detta server HTTP di IIS (IISHttpServer).

Quando si ospita out-of-process, il modulo funziona solo con Kestrel. Il modulo non funziona con HTTP.sys.

Modelli di hosting

Modello di hosting in-process

ASP.NET app core per impostazione predefinita è il modello di hosting in-process.

In caso di hosting in-process, vengono applicate le caratteristiche seguenti:

Il server HTTP IIS (IISHttpServer) viene usato invece del Kestrel server. Per in-process, CreateDefaultBuilder chiama UseIIS per:
- Registrare IISHttpServer.
- Configurare la porta e il percorso di base su cui il server deve eseguire l'ascolto in caso di esecuzione dietro il modulo ASP.NET Core.
- Configurare l'host per l'acquisizione degli errori di avvio.
L'attributo requestTimeout non viene applicato all'hosting in-process.
Non è supportata la condivisione di un pool di app tra le app. Usare un pool di app per ogni app.
Quando si usa distribuzione Web o si inserisce manualmente un app_offline.htm file nella distribuzione, l'app potrebbe non arrestarsi immediatamente se è presente una connessione aperta. Ad esempio, una connessione WebSocket potrebbe ritardare l'arresto dell'app.
L'architettura, vale a dire il numero di bit dell'app, e il runtime installato (x64 o x86) devono corrispondere all'architettura del pool di app.
Le disconnessioni del client vengono rilevate. Il HttpContext.RequestAborted token di annullamento viene annullato quando il client si disconnette.
In ASP.NET Core 2.2.1 o versioni precedenti restituisce GetCurrentDirectory la directory di lavoro del processo avviato da IIS anziché la directory dell'app (ad esempio, C:\Windows\System32\inetsrv per w3wp.exe).

Per il codice di esempio che imposta la directory corrente dell'app, vedi la CurrentDirectoryHelpers classe . Chiamare il metodo SetCurrentDirectory . Le chiamate successive a GetCurrentDirectory specificano la directory dell'app.
In caso di hosting in-process, AuthenticateAsync non viene chiamato internamente per inizializzare un utente. Pertanto, un'implementazione di IClaimsTransformation usate per trasformare le attestazioni dopo ogni autenticazione non viene attivata per impostazione predefinita. Quando si trasformano le attestazioni con un'implementazione di IClaimsTransformation, chiamare AddAuthentication per aggiungere i servizi di autenticazione:
```
public void ConfigureServices(IServiceCollection services)
{
    services.AddTransient<IClaimsTransformation, ClaimsTransformer>();
    services.AddAuthentication(IISServerDefaults.AuthenticationScheme);
}

public void Configure(IApplicationBuilder app)
{
    app.UseAuthentication();
}
```
- Le distribuzioni di pacchetti Web (a file singolo) non sono supportate.

Modello di hosting out-of-process

Per configurare un'app per l'hosting out-of-process, impostare il valore della <AspNetCoreHostingModel> proprietà su OutOfProcess nel file di progetto (.csproj):

<PropertyGroup>
  <AspNetCoreHostingModel>OutOfProcess</AspNetCoreHostingModel>
</PropertyGroup>

L'hosting in-process viene impostato con InProcess, ovvero il valore predefinito.

Il valore di <AspNetCoreHostingModel> non fa distinzione tra maiuscole e minuscole, quindi inprocess sono outofprocess valori validi.

Kestrel il server viene usato invece del server HTTP IIS (IISHttpServer).

Per le chiamate UseIISIntegration out-of-process aCreateDefaultBuilder:

Configurare la porta e il percorso di base su cui il server deve eseguire l'ascolto in caso di esecuzione dietro il modulo ASP.NET Core.
Configurare l'host per l'acquisizione degli errori di avvio.

Modifiche del modello di hosting

Se l'impostazione hostingModel viene modificata nel web.config file (illustrato nella sezione Configurazione con web.config ), il modulo ricicla il processo di lavoro per IIS.

Per IIS Express, il modulo non ricicla il processo di lavoro. Attiva invece un arresto normale del processo di IIS Express corrente. La richiesta successiva all'app attiva un nuovo processo di IIS Express.

Nome processo

Process.GetCurrentProcess().ProcessName dichiara w3wp/iisexpress (In-Process) o dotnet (out-of-process).

Molti moduli nativi, ad esempio l'autenticazione di Windows, rimangono attivi. Per altre informazioni sui moduli IIS attivi con il modulo ASP.NET Core, vedere Moduli IIS con ASP.NET Core.

Il modulo ASP.NET Core può anche:

Impostare variabili di ambiente per il processo di lavoro.
Registrare output stdout in una risorsa di archiviazione di file per la risoluzione di problemi di avvio.
Inoltrare token di autenticazione di Windows.

Come installare e usare ASP.NET Core Module (ANCM)

Per istruzioni su come installare e usare il modulo ASP.NET Core, vedere Installare il bundle di hosting .NET Core. Il modulo ASP.NET Core è compatibile con le versioni precedenti e successive con le versioni in-support di .NET.

Le modifiche di rilievo e gli avvisi di sicurezza vengono segnalati nel repository Annunci. Gli annunci possono essere limitati a una versione specifica selezionando un filtro Etichetta .

Configurazione con web.config

Il modulo ASP.NET Core viene configurato tramite la sezione aspNetCore del nodo system.webServer nel file web.config del 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>

Il file web.config seguente 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 dell'applicazione secondaria IIS, vedere Host ASP.NET Core in Windows con IIS.

Attributi dell'elemento aspNetCore

Attributo	Descrizione	Default
`arguments`	Attributo stringa facoltativo. Argomenti per l'eseguibile specificato in processPath.
`disableStartUpErrorPage`	Attributo booleano facoltativo. Se true, la pagina 502.5 - Errore del processo non viene visualizzata e la tabella codici di stato 502 configurata in web.config ha la 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 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`).	`InProcess` `inprocess`
`processesPerApplication`	Attributo Integer facoltativo. Specifica il numero di istanze del processo specificato nell'impostazione processPath che può essere riattivato 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 arresti anomali al minuto per il processo specificato in processPath. 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. Se si usa 60 come valore per i minuti o i secondi, viene generato un errore 500 - Errore 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. Quando si ospita 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 avvii rapidFailsPerMinute 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 relativo o assoluto per cui vengono registrati stdout e stderr dal processo specificato in processPath. 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 percorso stdoutLogFile . Se `.\logs\stdout` viene specificato come valore, un log stdout di esempio viene salvato come `stdout_20180205194132_1934.log` nella `logs` cartella quando viene salvato il 2/5/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.

`app_offline.htm`

Se viene rilevato un file con il nome app_offline.htm nella directory radice di un'app, il modulo principale ASP.NET tenta di arrestare correttamente l'app e interrompere l'elaborazione delle richieste in ingresso. Se l'app è ancora in esecuzione dopo il numero di secondi definito in shutdownTimeLimit, il modulo ASP.NET Core termina il processo in esecuzione.

Mentre il app_offline.htm file è presente, il modulo core ASP.NET risponde alle richieste inviando di nuovo il contenuto del app_offline.htm file. Quando il app_offline.htm file viene rimosso, la richiesta successiva avvia l'app.

Quando si usa il modello di hosting out-of-process, l'app potrebbe non arrestarsi immediatamente se una connessione è aperta. Ad esempio, una connessione WebSocket potrebbe ritardare l'arresto dell'app.

Pagina di errore di avvio

Sia l'hosting In-Process che quello out-of-process producono pagine di errore personalizzate quando non riescono ad avviare l'app.

Se il modulo ASP.NET Core non riesce a trovare il gestore richieste In-Process o out-of-process, viene visualizzata una tabella codici di stato 500.0 - Errore di caricamento del gestore In-Process/out-of-process.

Per l'hosting In-Process, se il modulo ASP.NET Core non riesce ad avviare l'app, viene visualizzata una tabella codici di stato 500.30 - Errore di avvio.

Per l'hosting out-of-process, se il modulo ASP.NET Core non riesce ad avviare il processo di back-end o il processo di back-end viene avviato ma non riesce a restare in ascolto sulla porta configurata, verrà visualizzata la tabella codici di stato 502.5 - Errore del processo.

Per non visualizzare questa pagina e tornare alla tabella codici di stato 5xx predefinita di IIS, usare l'attributo disableStartUpErrorPage. Per altre informazioni sulla configurazione di messaggi di errore personalizzati, vedere Errori HTTP <httpErrors>.

Creazione e reindirizzamento dei log

Il modulo ASP.NET Core reindirizza su disco l'output della console stdout e stderr se sono impostati gli attributi stdoutLogEnabled e stdoutLogFile dell'elemento aspNetCore. Le eventuali le cartelle nel percorso stdoutLogFile vengono create dal modulo quando viene creato il file di log. Il pool di app deve avere accesso in scrittura alla posizione in cui vengono scritti i log (usare IIS AppPool\<app_pool_name> per specificare l'autorizzazione di scrittura).

I log non vengono ruotati, a meno che non si verifichi il riciclo/riavvio del processo. È responsabilità del provider di servizi di hosting limitare lo spazio su disco usato dai log.

L'uso del log stdout è consigliato solo per la risoluzione dei problemi di avvio delle app durante l'hosting in IIS o quando si usa il supporto in fase di sviluppo per IIS con Visual Studio, non durante il debug locale e l'esecuzione dell'app con IIS Express.

Non usare il log stdout per scopi di registrazione generale delle app. Per la registrazione di routine in un'app ASP.NET Core, usare una libreria di registrazione che limita le dimensioni dei file di log e ne esegue la rotazione. Per altre informazioni, vedere Provider di registrazione di terze parti.

Un timestamp e l'estensione del file vengono aggiunti automaticamente al momento della creazione del file di log. Il nome del file di log è composto aggiungendo il timestamp, l'ID processo e l'estensione di file (.log) all'ultimo segmento del stdoutLogFile percorso (in stdoutgenere ) delimitato da caratteri di sottolineatura. Se il stdoutLogFile percorso termina con stdout, un log per un'app con PID 1934 creato il 2/5/2018 alle 19:42:32 ha il nome stdout_20180205194132_1934.logfile .

Se stdoutLogEnabled è false, gli errori che si verificano all'avvio dell'app vengono acquisiti ed emessi nel log eventi fino a 30 KB. Dopo l'avvio, tutti i log aggiuntivi vengono rimossi.

L'elemento di esempio aspNetCore seguente configura la registrazione stdout nel percorso .\log\relativo . Verificare che l'utente di AppPool abbia l'autorizzazione identity per scrivere nel percorso specificato.

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="true"
    stdoutLogFile=".\logs\stdout"
    hostingModel="inprocess">
</aspNetCore>

Quando si pubblica un'app per la distribuzione del servizio app Azure, Web SDK imposta il stdoutLogFile valore su \\?\%home%\LogFiles\stdout. La %home variabile di ambiente è predefinita per le app ospitate da app Azure Servizio.

Per creare regole di filtro di registrazione, vedere la sezione Applicare le regole di filtro dei log nel codice della documentazione relativa alla registrazione di base di ASP.NET.

Per altre informazioni sui formati di percorso, vedere Formati di percorso dei file nei sistemi Windows.

Log di diagnostica avanzati

Il modulo ASP.NET Core può essere configurato per restituire log di diagnostica avanzata. Aggiungere l'elemento <handlerSettings> all'elemento <aspNetCore> in web.config. L'impostazione di debugLevel su TRACE restituisce una maggior fedeltà dei dati diagnostici:

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="false"
    stdoutLogFile="\\?\%home%\LogFiles\stdout"
    hostingModel="inprocess">
  <handlerSettings>
    <handlerSetting name="debugFile" value=".\logs\aspnetcore-debug.log" />
    <handlerSetting name="debugLevel" value="FILE,TRACE" />
  </handlerSettings>
</aspNetCore>

Tutte le cartelle nel percorso (logs nell'esempio precedente) vengono create dal modulo quando viene creato il file di log. Il pool di app deve avere accesso in scrittura al percorso in cui vengono scritti i log (usare IIS AppPool\{APP POOL NAME}, dove il segnaposto {APP POOL NAME} è il nome del pool di app, per fornire l'autorizzazione di scrittura).

I valori di livello debug (debugLevel) possono includere sia il livello che il percorso.

Livelli (in ordine dal meno dettagliato al più dettagliato):

ERROR
AVVISO
INFO
TRACE

Posizioni (sono consentite più posizioni):

CONSOLE
EVENTLOG
FILE

Le impostazioni del gestore possono essere specificate anche tramite le variabili di ambiente:

ASPNETCORE_MODULE_DEBUG_FILE: percorso del file di log di debug. Impostazione predefinita: aspnetcore-debug.log
ASPNETCORE_MODULE_DEBUG: impostazione del livello di debug.

Avviso

Non lasciare la registrazione del debug abilitata nella distribuzione per un tempo superiore a quello necessario alla risoluzione di problema. Le dimensioni del log non sono limitate. Se si lascia abilitato il log di debug, lo spazio disponibile su disco può esaurirsi e il server o il servizio app può registrare un arresto anomalo.

Per un esempio dell'elemento aspNetCore nel file, vedere Configuration with web.config (Configurazione con web.config).web.config

Modificare le dimensioni dello stack

Si applica solo quando si usa il modello di hosting in-process.

Configurare le dimensioni dello stack gestito usando l'impostazione stackSize in byte in web.config. Le dimensioni predefinite sono 1.048.576 byte (1 MB).

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="false"
    stdoutLogFile="\\?\%home%\LogFiles\stdout"
    hostingModel="inprocess">
  <handlerSettings>
    <handlerSetting name="stackSize" value="2097152" />
  </handlerSettings>
</aspNetCore>

La configurazione del proxy usa il protocollo HTTP e un token di associazione

Si applica solo all'hosting out-of-process.

Il proxy creato tra il modulo principale di ASP.NET e Kestrel usa il protocollo HTTP. Non esiste alcun rischio di intercettazione del traffico tra il modulo e Kestrel da una posizione al di fuori del server.

Un token di associazione viene usato per garantire che le richieste ricevute da Kestrel siano state inoltrate tramite proxy da IIS e non provengano da un'altra origine. Il token di associazione viene creato e impostato in una variabile di ambiente (ASPNETCORE_TOKEN) dal modulo. Il token di associazione viene impostato anche in un'intestazione (MS-ASPNETCORE-TOKEN) in tutte le richieste trasmesse tramite proxy. Il middleware di IIS controlla ogni richiesta che riceve in modo da confermare che il valore dell'intestazione del token di associazione corrisponda al valore della variabile di ambiente. Se i valori del token non corrispondono, la richiesta viene registrata e rifiutata. La variabile di ambiente del token di associazione e il traffico tra il modulo e Kestrel non sono accessibili da una posizione al di fuori del server. Senza conoscere il valore del token di associazione, un cyberattacker non può inviare richieste che ignorano il controllo nel middleware IIS.

Modulo ASP.NET Core con configurazione condivisa di IIS

Il programma di installazione del modulo ASP.NET Core viene eseguito con i privilegi dell'account TrustedInstaller. Poiché l'account di sistema locale non dispone dell'autorizzazione di modifica per il percorso di condivisione usato dalla configurazione condivisa IIS, il programma di installazione genera un errore di accesso negato quando si tenta di configurare le impostazioni del modulo nel file nella applicationHost.config condivisione.

Quando si usa una configurazione condivisa di IIS nello stesso computer dell'installazione di IIS, eseguire il programma di installazione del bundle di hosting ASP.NET Core con il parametro OPT_NO_SHARED_CONFIG_CHECK impostato su 1:

dotnet-hosting-{VERSION}.exe OPT_NO_SHARED_CONFIG_CHECK=1

Quando il percorso della configurazione condivisa non è nello stesso computer dell'installazione di IIS, seguire questa procedura:

Disabilitare la configurazione condivisa di IIS.
Eseguire il programma di installazione.
Esportare il file aggiornato applicationHost.config nella condivisione.
Abilitare di nuovo la configurazione condivisa di IIS.

Versione del modulo e log del programma di installazione del bundle di hosting

Per determinare la versione del modulo ASP.NET Core installato:

Nel sistema di hosting passare a %windir%\System32\inetsrv.
Individuare il aspnetcore.dll file.
Fare clic con il pulsante destro del mouse sul file e scegliere Proprietà dal menu di scelta rapida.
Selezionare la scheda Dettagli . La versione file e la versione del prodotto rappresentano la versione installata del modulo.

I log del programma di installazione del bundle di hosting per il modulo sono disponibili in C:\Users\%UserName%\AppData\Local\Temp. Il file è denominato dd_DotNetCoreWinSvrHosting__{TIMESTAMP}_000_AspNetCoreModule_x64.log.

Percorsi dei file di modulo, schema e configurazione

Modulo

IIS (x86/amd64):

%windir%\System32\inetsrv\aspnetcore.dll
%windir%\SysWOW64\inetsrv\aspnetcore.dll
%ProgramFiles%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll
%ProgramFiles(x86)%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll

IIS Express (x86/amd64):

%ProgramFiles%\IIS Express\aspnetcore.dll
%ProgramFiles(x86)%\IIS Express\aspnetcore.dll
%ProgramFiles%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll
%ProgramFiles(x86)%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll

Schema

IIS

%windir%\System32\inetsrv\config\schema\aspnetcore_schema.xml
%windir%\System32\inetsrv\config\schema\aspnetcore_schema_v2.xml

IIS Express

%ProgramFiles%\IIS Express\config\schema\aspnetcore_schema.xml
%ProgramFiles%\IIS Express\config\schema\aspnetcore_schema_v2.xml

Impostazione

IIS

%windir%\System32\inetsrv\config\applicationHost.config

IIS Express

Visual Studio: {APPLICATION ROOT}\.vs\config\applicationHost.config
interfaccia della riga di comando iisexpress.exe: %USERPROFILE%\Documents\IISExpress\config\applicationhost.config

I file sono disponibili cercando aspnetcore nel applicationHost.config file .

Il modulo ASP.NET Core (ANCM) è un modulo IIS nativo che collega la pipeline IIS a:

Ospitare un app ASP.NET Core all'interno del processo di lavoro IIS (w3wp.exe), denominato modello di hosting in-process.
Inoltrare le richieste Web a un'app back-end ASP.NET Core che esegue il Kestrel server, denominato modello di hosting out-of-process.

Versioni supportate di Windows:

Windows 7 o versione successiva
Windows Server 2008 R2 o versione successiva

In caso di hosting in-process, il modulo usa un'implementazione di server in-process per IIS detta server HTTP di IIS (IISHttpServer).

Quando si ospita out-of-process, il modulo funziona solo con Kestrel. Il modulo non funziona con HTTP.sys.

Modelli di hosting

Modello di hosting in-process

Per configurare un'app per l'hosting in-process, aggiungere la proprietà <AspNetCoreHostingModel> al file di progetto dell'app usando il valore InProcess (l'hosting out-of-process viene impostato con OutOfProcess):

<PropertyGroup>
  <AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>
</PropertyGroup>

Il modello di hosting In-Process non è supportato per le app ASP.NET Core destinate a .NET Framework.

Il valore di <AspNetCoreHostingModel> non fa distinzione tra maiuscole e minuscole, quindi inprocess sono outofprocess valori validi.

Se la proprietà <AspNetCoreHostingModel> non è presente nel file, il valore predefinito è OutOfProcess.

In caso di hosting in-process, vengono applicate le caratteristiche seguenti:

Il server HTTP IIS (IISHttpServer) viene usato invece del Kestrel server. Per in-process, CreateDefaultBuilder chiama UseIIS per:
- Registrare IISHttpServer.
- Configurare la porta e il percorso di base su cui il server deve eseguire l'ascolto in caso di esecuzione dietro il modulo ASP.NET Core.
- Configurare l'host per l'acquisizione degli errori di avvio.
L'attributo requestTimeout non viene applicato all'hosting in-process.
Non è supportata la condivisione di un pool di app tra le app. Usare un pool di app per ogni app.
Quando si usa la Distribuzione Web o si inserisce manualmente un file app_offline.htm nella distribuzione, l'app potrebbe non arrestarsi immediatamente se una connessione è aperta. Ad esempio, una connessione WebSocket può ritardare l'arresto dell'app.
L'architettura, vale a dire il numero di bit dell'app, e il runtime installato (x64 o x86) devono corrispondere all'architettura del pool di app.
Le disconnessioni del client vengono rilevate. Il token di annullamento HttpContext.RequestAborted viene cancellato quando il client si disconnette.
In ASP.NET Core 2.2.1 o versioni precedenti, GetCurrentDirectory restituisce la directory di lavoro del processo avviato da IIS invece che la directory dell'app (ad esempio, C:\Windows\System32\inetsrv per w3wp.exe).

Per vedere il codice di esempio che imposta la directory corrente dell'app, vedere la classe CurrentDirectoryHelpers. Chiamare il metodo SetCurrentDirectory . Le chiamate successive a GetCurrentDirectory specificano la directory dell'app.
In caso di hosting in-process, AuthenticateAsync non viene chiamato internamente per inizializzare un utente. Pertanto, un'implementazione di IClaimsTransformation usate per trasformare le attestazioni dopo ogni autenticazione non viene attivata per impostazione predefinita. Quando si trasformano le attestazioni con un'implementazione di IClaimsTransformation, chiamare AddAuthentication per aggiungere i servizi di autenticazione:
```
public void ConfigureServices(IServiceCollection services)
{
    services.AddTransient<IClaimsTransformation, ClaimsTransformer>();
    services.AddAuthentication(IISServerDefaults.AuthenticationScheme);
}

public void Configure(IApplicationBuilder app)
{
    app.UseAuthentication();
}
```

Modello di hosting out-of-process

Per configurare un'app per l'hosting out-of-process, usare uno dei due approcci seguenti nel file di progetto:

Non specificare la proprietà <AspNetCoreHostingModel>. Se la proprietà <AspNetCoreHostingModel> non è presente nel file, il valore predefinito è OutOfProcess.
Impostare il valore della proprietà <AspNetCoreHostingModel> su OutOfProcess (l'hosting in-process è impostato con InProcess):

<PropertyGroup>
  <AspNetCoreHostingModel>OutOfProcess</AspNetCoreHostingModel>
</PropertyGroup>

Il valore non fa distinzione tra maiuscole e minuscole, quindi inprocess sono outofprocess valori validi.

Kestrel il server viene usato invece del server HTTP IIS (IISHttpServer).

Per out-of-process, CreateDefaultBuilder chiama UseIISIntegration per:

Configurare la porta e il percorso di base su cui il server deve eseguire l'ascolto in caso di esecuzione dietro il modulo ASP.NET Core.
Configurare l'host per l'acquisizione degli errori di avvio.

Modifiche del modello di hosting

Se l'impostazione hostingModel viene modificata nel file web.config (descritto nella sezione Configurazione con web.config), il modulo ricicla il processo di lavoro per IIS.

Nome processo

Process.GetCurrentProcess().ProcessName dichiara w3wp/iisexpress (In-Process) o dotnet (out-of-process).

Molti moduli nativi, ad esempio l'autenticazione di Windows, rimangono attivi. Per altre informazioni sui moduli IIS attivi con il modulo ASP.NET Core, vedere Moduli IIS con ASP.NET Core.

Il modulo ASP.NET Core può anche:

Impostare variabili di ambiente per il processo di lavoro.
Registrare output stdout in una risorsa di archiviazione di file per la risoluzione di problemi di avvio.
Inoltrare token di autenticazione di Windows.

Come installare e usare ASP.NET Core Module (ANCM)

Le modifiche di rilievo e gli avvisi di sicurezza vengono segnalati nel repository Annunci. Gli annunci possono essere limitati a una versione specifica selezionando un filtro Etichetta .

Configurazione con web.config

Il modulo ASP.NET Core viene configurato tramite la sezione aspNetCore del nodo system.webServer nel file web.config del sito.

Il file web.config seguente 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>

Il file web.config seguente 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 cartella LogFiles, ovvero una posizione creata automaticamente dal servizio.

Per informazioni sulla configurazione dell'applicazione secondaria IIS, vedere Host ASP.NET Core in Windows con IIS.

Attributi dell'elemento aspNetCore

Attributo	Descrizione	Default
`arguments`	Attributo stringa facoltativo. Argomenti per l'eseguibile specificato in `processPath`.
`disableStartUpErrorPage`	Attributo booleano facoltativo. Se true, la pagina 502.5 - Errore del processo non viene visualizzata e la tabella codici di stato 502 configurata in web.config ha la precedenza.	`false`
`forwardWindowsAuthToken`	Attributo booleano facoltativo. Se true, il token viene inoltrato al processo figlio in ascolto su %ASPNETCORE_PORT% come un'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`
`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. Se si usa 60 come valore per i minuti o i secondi, viene generato un errore 500 - Errore 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 viene salvato il 2/5/2018 alle 19:41:32 con id processo 1934.	`aspnetcore-stdout`

Impostazioni delle variabili di ambiente

Nell'esempio seguente vengono impostate due variabili di ambiente. 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 (con estensione 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.

app_offline.htm

Quando si usa il modello di hosting out-of-process, l'app potrebbe non arrestarsi immediatamente se una connessione è aperta. Ad esempio, una connessione WebSocket può ritardare l'arresto dell'app.

Pagina di errore di avvio

Sia l'hosting In-Process che quello out-of-process producono pagine di errore personalizzate quando non riescono ad avviare l'app.

Per l'hosting In-Process, se il modulo ASP.NET Core non riesce ad avviare l'app, viene visualizzata una tabella codici di stato 500.30 - Errore di avvio.

Creazione e reindirizzamento dei log

Il modulo ASP.NET Core reindirizza su disco l'output della console stdout e stderr se sono impostati gli attributi stdoutLogEnabled e stdoutLogFile dell'elemento aspNetCore. Le eventuali le cartelle nel percorso stdoutLogFile vengono create dal modulo quando viene creato il file di log. Il pool di app deve avere accesso in scrittura al percorso in cui vengono scritti i log (usare IIS AppPool\{APP POOL NAME} per fornire l'autorizzazione di scrittura, dove il segnaposto {APP POOL NAME} è il nome del pool di app).

I log non vengono ruotati, a meno che non si verifichi il riciclo/riavvio del processo. È responsabilità del provider di servizi di hosting limitare lo spazio su disco usato dai log.

Se stdoutLogEnabled è false, gli errori che si verificano all'avvio dell'app vengono acquisiti ed emessi nel log eventi fino a 30 KB. Dopo l'avvio, tutti i log aggiuntivi vengono rimossi.

L'elemento di esempio aspNetCore seguente configura la registrazione stdout nel percorso .\log\relativo . Verificare che l'utente identity del pool di app disponga dell'autorizzazione per scrivere nel percorso specificato.

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="true"
    stdoutLogFile=".\logs\stdout"
    hostingModel="inprocess">
</aspNetCore>

Per altre informazioni sui formati di percorso, vedere Formati di percorso dei file nei sistemi Windows.

Log di diagnostica avanzati

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="false"
    stdoutLogFile="\\?\%home%\LogFiles\stdout"
    hostingModel="inprocess">
  <handlerSettings>
    <handlerSetting name="debugFile" value=".\logs\aspnetcore-debug.log" />
    <handlerSetting name="debugLevel" value="FILE,TRACE" />
  </handlerSettings>
</aspNetCore>

Le cartelle nel percorso fornito al <handlerSetting> valore (logs nell'esempio precedente) non vengono create automaticamente dal modulo e devono esistere già nella distribuzione. Il pool di app deve avere accesso in scrittura al percorso in cui vengono scritti i log (usare IIS AppPool\{APP POOL NAME} per fornire l'autorizzazione di scrittura, dove il segnaposto {APP POOL NAME} è il nome del pool di app).

I valori di livello debug (debugLevel) possono includere sia il livello che il percorso.

Livelli (in ordine dal meno dettagliato al più dettagliato):

ERROR
AVVISO
INFO
TRACE

Posizioni (sono consentite più posizioni):

CONSOLE
EVENTLOG
FILE

Le impostazioni del gestore possono essere specificate anche tramite le variabili di ambiente:

ASPNETCORE_MODULE_DEBUG_FILE: percorso del file di log di debug. Impostazione predefinita: aspnetcore-debug.log
ASPNETCORE_MODULE_DEBUG: impostazione del livello di debug.

Avviso

Per un esempio dell'elemento aspNetCore nel file, vedere Configuration with web.config (Configurazione con web.config).web.config

La configurazione del proxy usa il protocollo HTTP e un token di associazione

Si applica solo all'hosting out-of-process.

Modulo ASP.NET Core con configurazione condivisa di IIS

Il programma di installazione di ASP.NET Core Module viene eseguito con i privilegi dell'account TrustedInstaller . Poiché l'account di sistema locale non dispone dell'autorizzazione di modifica per il percorso di condivisione usato dalla configurazione condivisa IIS, il programma di installazione genera un errore di accesso negato quando si tenta di configurare le impostazioni del modulo nel file nella applicationHost.config condivisione.

dotnet-hosting-{VERSION}.exe OPT_NO_SHARED_CONFIG_CHECK=1

Quando il percorso della configurazione condivisa non è nello stesso computer dell'installazione di IIS, seguire questa procedura:

Disabilitare la configurazione condivisa di IIS.
Eseguire il programma di installazione.
Esportare il file aggiornato applicationHost.config nella condivisione.
Abilitare di nuovo la configurazione condivisa di IIS.

Versione del modulo e log del programma di installazione del bundle di hosting

Per determinare la versione del modulo ASP.NET Core installato:

Nel sistema di hosting passare a %windir%\System32\inetsrv.
Individuare il aspnetcore.dll file.
Fare clic con il pulsante destro del mouse sul file e scegliere Proprietà dal menu di scelta rapida.
Selezionare la scheda Dettagli . La versione file e la versione del prodotto rappresentano la versione installata del modulo.

I log del programma di installazione del bundle di hosting per il modulo sono disponibili in C:\\Users\\%UserName%\\AppData\\Local\\Temp. Il file è denominato dd_DotNetCoreWinSvrHosting__\{TIMESTAMP}_000_AspNetCoreModule_x64.log, dove il segnaposto {TIMESTAMP} è il timestamp.

Percorsi dei file di modulo, schema e configurazione

Modulo

IIS (x86/amd64):

%windir%\System32\inetsrv\aspnetcore.dll
%windir%\SysWOW64\inetsrv\aspnetcore.dll
%ProgramFiles%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll
%ProgramFiles(x86)%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll

IIS Express (x86/amd64):

%ProgramFiles%\IIS Express\aspnetcore.dll
%ProgramFiles(x86)%\IIS Express\aspnetcore.dll
%ProgramFiles%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll
%ProgramFiles(x86)%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll

Schema

IIS

%windir%\System32\inetsrv\config\schema\aspnetcore_schema.xml
%windir%\System32\inetsrv\config\schema\aspnetcore_schema_v2.xml

IIS Express

%ProgramFiles%\IIS Express\config\schema\aspnetcore_schema.xml
%ProgramFiles%\IIS Express\config\schema\aspnetcore_schema_v2.xml

Impostazione

IIS

%windir%\System32\inetsrv\config\applicationHost.config

IIS Express

Visual Studio: {APPLICATION ROOT}\.vs\config\applicationHost.config
interfaccia della riga di comando iisexpress.exe: %USERPROFILE%\Documents\IISExpress\config\applicationhost.config

I file sono disponibili cercando aspnetcore nel applicationHost.config file .

Il modulo ASP.NET Core (ANCM) è un modulo IIS nativo che si collega alla pipeline IIS per inoltrare le richieste Web alle app back-end ASP.NET Core.

Versioni supportate di Windows:

Windows 7 o versione successiva
Windows Server 2008 R2 o versione successiva

Il modulo funziona solo con Kestrel. Il modulo non è compatibile con HTTP.sys.

Poiché le app ASP.NET Core vengono eseguite in un processo distinto dal processo di lavoro IIS, il modulo esegue anche la gestione dei processi. Il modulo avvia il processo per l'app ASP.NET Core quando arriva la prima richiesta e riavvia l'app se si verifica un arresto anomalo di questa. Si tratta essenzialmente dello stesso comportamento delle app ASP.NET 4.x eseguite In-Process in IIS e gestite dal servizio Attivazione processo Windows (WAS, Windows Activation Service).

Il diagramma seguente illustra la relazione tra IIS, il modulo ASP.NET Core e un'app:

Modulo ASP.NET Core

Le richieste arrivano dal Web al driver HTTP.sys in modalità kernel. Il driver instrada le richieste a IIS sulla porta configurata per il sito Web, in genere 80 (HTTP) o 443 (HTTPS). Il modulo inoltra le richieste a Kestrel su una porta casuale per l'app non corrispondente alla porta 80 o 443.

Il modulo specifica la porta tramite una variabile di ambiente all'avvio e il middleware di integrazione IIS configura il server per l'ascolto su http://localhost:{port}. Vengono eseguiti controlli aggiuntivi e le richieste che non provengono dal modulo vengono rifiutate. Il modulo non supporta l'inoltro HTTPS, pertanto le richieste vengono inoltrate tramite HTTP anche se sono state ricevute da IIS tramite HTTPS.

Dopo che Kestrel ha prelevato la richiesta dal modulo, viene eseguito il push della richiesta nella pipeline middleware di ASP.NET Core. La pipeline middleware gestisce la richiesta e la passa come istanza di HttpContext alla logica dell'app. Il middleware aggiunto dall'integrazione di IIS aggiorna lo schema, l'IP remoto e la base del percorso per l'account per l'inoltro della richiesta a Kestrel. La risposta dell'app viene quindi passata a IIS, che ne esegue di nuovo il push al client HTTP che ha avviato la richiesta.

Molti moduli nativi, ad esempio l'autenticazione di Windows, rimangono attivi. Per altre informazioni sui moduli IIS attivi con il modulo ASP.NET Core, vedere Moduli IIS con ASP.NET Core.

Il modulo ASP.NET Core può anche:

Impostare variabili di ambiente per il processo di lavoro.
Registrare output stdout in una risorsa di archiviazione di file per la risoluzione di problemi di avvio.
Inoltrare token di autenticazione di Windows.

Come installare e usare ASP.NET Core Module (ANCM)

Per istruzioni su come installare e usare il modulo ASP.NET Core, vedere Installare il bundle di hosting .NET Core.

Configurazione con web.config

Il modulo ASP.NET Core viene configurato tramite la sezione aspNetCore del nodo system.webServer nel file web.config del sito.

Il file web.config seguente 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>
  <system.webServer>
    <handlers>
      <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModule" resourceType="Unspecified" />
    </handlers>
    <aspNetCore processPath="dotnet"
                arguments=".\MyApp.dll"
                stdoutLogEnabled="false"
                stdoutLogFile=".\logs\stdout" />
  </system.webServer>
</configuration>

Il file web.config seguente viene pubblicato per una distribuzione autonoma:

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

Per informazioni sulla configurazione dell'applicazione secondaria IIS, vedere Host ASP.NET Core in Windows con IIS.

Attributi dell'elemento aspNetCore

Attributo	Descrizione	Default
`arguments`	Attributo stringa facoltativo. Argomenti per l'eseguibile specificato in processPath.
`disableStartUpErrorPage`	Attributo booleano facoltativo. Se true, la pagina 502.5 - Errore del processo non viene visualizzata e la tabella codici di stato 502 configurata in web.config ha la precedenza.	`false`
`forwardWindowsAuthToken`	Attributo booleano facoltativo. Se true, il token viene inoltrato al processo figlio in ascolto su %ASPNETCORE_PORT% come un'intestazione 'MS-ASPNETCORE-WINAUTHTOKEN' per ogni richiesta. È responsabilità del processo chiamare CloseHandle su questo token per ogni richiesta.	`true`
`processesPerApplication`	Attributo Integer facoltativo. Specifica il numero di istanze del processo specificato nell'impostazione processPath che può essere riattivato per ogni app. 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 arresti anomali al minuto per il processo specificato in processPath. Se questo limite viene superato, il modulo smette di avviare il processo per la parte restante del minuto.	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.	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. Il modulo tenta di avviare nuovamente il processo quando riceve una nuova richiesta e continua a tentare di riavviare il processo alle successive richieste in ingresso, a meno che non risulti impossibile avviare l'app un numero di volte pari a rapidFailsPerMinute nell'ultimo minuto continuo. 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 relativo o assoluto per cui vengono registrati stdout e stderr dal processo specificato in processPath. 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 devono essere già esistenti affinché il modulo possa creare il file di log. Usando il carattere di sottolineatura come delimitatore, il timestamp, l'ID processo e l'estensione del file (.log) vengono aggiunti all'ultimo segmento del percorso stdoutLogFile. Se si specifica `.\logs\stdout` come valore, un log stdout di esempio salvato il 5/2/2018 alle 19:41:32 con un ID processo 1934 viene salvato come stdout_20180205194132_1934.log nella cartella logs.	`aspnetcore-stdout`

Impostazioni delle variabili di ambiente

Avviso

Le variabili di ambiente impostate in questa sezione sono in conflitto con le variabili di ambiente di sistema impostate con lo stesso nome. Se una variabile di ambiente è impostata sia nel file web.config sia a livello di sistema in Windows, il valore del file web.config viene aggiunto al valore della variabile di ambiente di sistema, ad esempio ASPNETCORE_ENVIRONMENT: Development;Development, e ciò impedisce l'avvio dell'app.

Nell'esempio seguente vengono impostate due variabili di ambiente. ASPNETCORE_ENVIRONMENT configura l'ambiente dell'app su Development. Uno sviluppatore può impostare temporaneamente questo valore nel file web.config per forzare il caricamento della pagina delle eccezioni per gli 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="\\?\%home%\LogFiles\stdout">
  <environmentVariables>
    <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
    <environmentVariable name="CONFIG_DIR" value="f:\application_config" />
  </environmentVariables>
</aspNetCore>

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.

app_offline.htm

Pagina di errore di avvio

Se il modulo ASP.NET Core non riesce ad avviare il processo di back-end o il processo di back-end viene avviato ma non riesce a restare in ascolto sulla porta configurata, verrà visualizzata la tabella codici di stato 502.5 - Errore del processo. Per non visualizzare questa pagina e tornare alla tabella codici di stato 502 predefinita di IIS, usare l'attributo disableStartUpErrorPage. Per altre informazioni sulla configurazione di messaggi di errore personalizzati, vedere Errori HTTP <httpErrors>.

Creazione e reindirizzamento dei log

I log non vengono ruotati, a meno che non si verifichi il riciclo/riavvio del processo. È responsabilità del provider di servizi di hosting limitare lo spazio su disco usato dai log.

Un timestamp e l'estensione del file vengono aggiunti automaticamente al momento della creazione del file di log. Il nome del file di log è composto aggiungendo il timestamp, l'ID processo e l'estensione del file (.log) all'ultimo segmento del percorso stdoutLogFile (in genere stdout), con caratteri di sottolineatura come delimitatori. Se il percorso stdoutLogFile termina con stdout, un log per un'app con un PID 1934 creata il 5/2/2018 alle 19:42:32 sarà denominato stdout_20180205194132_1934.log.

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="true"
    stdoutLogFile=".\logs\stdout">
</aspNetCore>

Per creare regole di filtro di registrazione, vedere la sezione Applicare le regole di filtro dei log nel codice della documentazione relativa alla registrazione di base di ASP.NET.

Per altre informazioni sui formati di percorso, vedere Formati di percorso dei file nei sistemi Windows.

La configurazione del proxy usa il protocollo HTTP e un token di associazione

Modulo ASP.NET Core con configurazione condivisa di IIS

Il programma di installazione del modulo ASP.NET Core viene eseguito con i privilegi dell'account TrustedInstaller. Poiché l'account di sistema locale non dispone dell'autorizzazione di modifica per il percorso della condivisione usato dalla configurazione condivisa di IIS, il programma di installazione genera un errore di accesso negato durante il tentativo di configurare le impostazioni del modulo nel file applicationHost.config nella condivisione.

Quando si usa una configurazione condivisa di IIS, attenersi ai passaggi riportati di seguito:

Disabilitare la configurazione condivisa di IIS.
Eseguire il programma di installazione.
Esportare il file applicationHost.config aggiornato nella condivisione.
Abilitare di nuovo la configurazione condivisa di IIS.

Versione del modulo e log del programma di installazione del bundle di hosting

Per determinare la versione del modulo ASP.NET Core installato:

Nel sistema host passare a %windir%\System32\inetsrv.
Individuare il file aspnetcore.dll.
Fare clic con il pulsante destro del mouse sul file e scegliere Proprietà dal menu di scelta rapida.
Selezionare la scheda Dettagli . La versione file e la versione del prodotto rappresentano la versione installata del modulo.

I log del programma di installazione del bundle di hosting per il modulo sono disponibili in C:\Users\%UserName%\AppData\Local\Temp. Il file è denominato dd_DotNetCoreWinSvrHosting__<timestamp>_000_AspNetCoreModule_x64.log.

Percorsi dei file di modulo, schema e configurazione

Modulo

IIS (x86/amd64):

%windir%\System32\inetsrv\aspnetcore.dll
%windir%\SysWOW64\inetsrv\aspnetcore.dll

IIS Express (x86/amd64):

%ProgramFiles%\IIS Express\aspnetcore.dll
%ProgramFiles(x86)%\IIS Express\aspnetcore.dll

Schema

IIS

%windir%\System32\inetsrv\config\schema\aspnetcore_schema.xml

IIS Express

%ProgramFiles%\IIS Express\config\schema\aspnetcore_schema.xml

Impostazione

IIS

%windir%\System32\inetsrv\config\applicationHost.config

IIS Express

Visual Studio: {APPLICATION ROOT}\.vs\config\applicationHost.config
Interfaccia della riga di comando di iisexpress.exe: %USERPROFILE%\Documents\IISExpress\config\applicationhost.config

È possibile trovare i file eseguendo una ricerca di aspnetcore nel file applicationHost.config.

Risorse aggiuntive

Host ASP.NET Core in Windows con IIS
Distribuire le app ASP.NET Core in Servizio app di Azure
ASP.NET'origine di riferimento del modulo core [ramo predefinito (main)]: usare l'elenco a discesa Branch per selezionare una versione specifica (ad esempio, release/3.1).
Moduli IIS con ASP.NET Core

Condividi tramite

ASP.NET Core Module (ANCM) per IIS

Installare ASP.NET Core Module (ANCM)

Modelli di hosting

Modello di hosting in-process

Modello di hosting out-of-process

Modifiche del modello di hosting

Nome processo

Come installare e usare ASP.NET Core Module (ANCM)

Configurazione con web.config

Attributi dell'elemento aspNetCore

Impostare le variabili di ambiente

app_offline.htm

Pagina di errore di avvio

Creazione e reindirizzamento dei log

Log di diagnostica avanzati

Modificare le dimensioni dello stack

La configurazione del proxy usa il protocollo HTTP e un token di associazione

Modulo ASP.NET Core con configurazione condivisa di IIS

Versione del modulo e log del programma di installazione del bundle di hosting

Percorsi dei file di modulo, schema e configurazione

Modulo

Schema

Impostazione

Modelli di hosting

Modello di hosting in-process

Modello di hosting out-of-process

Modifiche del modello di hosting

Nome processo

Come installare e usare ASP.NET Core Module (ANCM)

Configurazione con web.config

Attributi dell'elemento aspNetCore

Impostazioni delle variabili di ambiente

app_offline.htm

Pagina di errore di avvio

Creazione e reindirizzamento dei log

Log di diagnostica avanzati

La configurazione del proxy usa il protocollo HTTP e un token di associazione

Modulo ASP.NET Core con configurazione condivisa di IIS

Versione del modulo e log del programma di installazione del bundle di hosting

Percorsi dei file di modulo, schema e configurazione

Modulo

Schema

Impostazione

Come installare e usare ASP.NET Core Module (ANCM)

Configurazione con web.config

Attributi dell'elemento aspNetCore

Impostazioni delle variabili di ambiente

app_offline.htm

Pagina di errore di avvio

Creazione e reindirizzamento dei log

La configurazione del proxy usa il protocollo HTTP e un token di associazione

Modulo ASP.NET Core con configurazione condivisa di IIS

Versione del modulo e log del programma di installazione del bundle di hosting

Percorsi dei file di modulo, schema e configurazione

Modulo

Schema

Impostazione

Risorse aggiuntive

Risorse aggiuntive

`app_offline.htm`