Modulo ASP.NET CoreASP.NET Core Module

Di Tom Dykstra, Rick Strahl, Chris Ross, Rick Anderson, Sourabh Shirhatti, Justin Kotalik e Luke LathamBy Tom Dykstra, Rick Strahl, Chris Ross, Rick Anderson, Sourabh Shirhatti, Justin Kotalik, and Luke Latham

Il modulo ASP.NET Core è un modulo IIS nativo collegato alla pipeline di IIS per eseguire le operazioni seguenti:The ASP.NET Core Module is a native IIS module that plugs into the IIS pipeline to either:

Versioni di Windows supportate:Supported Windows versions:

  • Windows 7 o versione successivaWindows 7 or later
  • Windows Server 2008 R2 o versioni successiveWindows Server 2008 R2 or later

In caso di hosting in-process, il modulo usa un'implementazione di server in-process per IIS detta server HTTP di IIS (IISHttpServer).When hosting in-process, the module uses an in-process server implementation for IIS, called IIS HTTP Server (IISHttpServer).

In caso di hosting out-of-process, il modulo funziona solo con Kestrel.When hosting out-of-process, the module only works with Kestrel. Il modulo non funziona con http. sys.The module doesn't function with HTTP.sys.

Modelli di hostingHosting models

Modello di hosting in-processIn-process hosting model

ASP.NET Core app predefinite per il modello di hosting in-process.ASP.NET Core apps default to the in-process hosting model.

In caso di hosting in-process, vengono applicate le caratteristiche seguenti:The following characteristics apply when hosting in-process:

  • Viene usato un server HTTP di IIS (IISHttpServer) al posto del server Kestrel.IIS HTTP Server (IISHttpServer) is used instead of Kestrel server. Per in-process, CreateDefaultBuilder chiama UseIIS per:For in-process, CreateDefaultBuilder calls UseIIS to:

    • Registrare IISHttpServer.Register the 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.Configure the port and base path the server should listen on when running behind the ASP.NET Core Module.
    • Configurare l'host per l'acquisizione degli errori di avvio.Configure the host to capture startup errors.
  • L'attributo requestTimeout non viene applicato all'hosting in-process.The requestTimeout attribute doesn't apply to in-process hosting.

  • Non è supportata la condivisione di un pool di app tra le app.Sharing an app pool among apps isn't supported. Usare un pool di app per ogni app.Use one app pool per 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.When using Web Deploy or manually placing an app_offline.htm file in the deployment, the app might not shut down immediately if there's an open connection. Ad esempio, una connessione WebSocket può ritardare l'arresto dell'app.For example, a websocket connection may delay app shut down.

  • 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.The architecture (bitness) of the app and installed runtime (x64 or x86) must match the architecture of the app pool.

  • Le disconnessioni del client vengono rilevate.Client disconnects are detected. Il token di annullamento HttpContext.RequestAborted viene cancellato quando il client si disconnette.The HttpContext.RequestAborted cancellation token is cancelled when the client disconnects.

  • 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).In ASP.NET Core 2.2.1 or earlier, GetCurrentDirectory returns the worker directory of the process started by IIS rather than the app's directory (for example, C:\Windows\System32\inetsrv for w3wp.exe).

    Per vedere il codice di esempio che imposta la directory corrente dell'app, vedere la classe CurrentDirectoryHelpers.For sample code that sets the app's current directory, see the CurrentDirectoryHelpers class. Chiamare il metodo SetCurrentDirectory.Call the SetCurrentDirectory method. Le chiamate successive a GetCurrentDirectory specificano la directory dell'app.Subsequent calls to GetCurrentDirectory provide the app's directory.

  • In caso di hosting in-process, AuthenticateAsync non viene chiamato internamente per inizializzare un utente.When hosting in-process, AuthenticateAsync isn't called internally to initialize a user. Pertanto, un'implementazione di IClaimsTransformation usate per trasformare le attestazioni dopo ogni autenticazione non viene attivata per impostazione predefinita.Therefore, an IClaimsTransformation implementation used to transform claims after every authentication isn't activated by default. Quando si trasformano le attestazioni con un'implementazione di IClaimsTransformation, chiamare AddAuthentication per aggiungere i servizi di autenticazione:When transforming claims with an IClaimsTransformation implementation, call AddAuthentication to add authentication services:

    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-processOut-of-process hosting model

Per configurare un'app per l'hosting out-of-process, impostare il valore della proprietà <AspNetCoreHostingModel> su OutOfProcess nel file di progetto (conestensione csproj):To configure an app for out-of-process hosting, set the value of the <AspNetCoreHostingModel> property to OutOfProcess in the project file (.csproj):

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

L'hosting in-process viene impostato con InProcess, che corrisponde al valore predefinito.In-process hosting is set with InProcess, which is the default value.

Il valore di <AspNetCoreHostingModel> non fa distinzione tra maiuscole e minuscole, pertanto inprocess e outofprocess sono valori validi.The value of <AspNetCoreHostingModel> is case insensitive, so inprocess and outofprocess are valid values.

Viene usato il server Kestrel al posto di un server HTTP di IIS (IISHttpServer).Kestrel server is used instead of IIS HTTP Server (IISHttpServer).

Per out-of-process, CreateDefaultBuilder chiama UseIISIntegration per:For out-of-process, CreateDefaultBuilder calls UseIISIntegration to:

  • 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.Configure the port and base path the server should listen on when running behind the ASP.NET Core Module.
  • Configurare l'host per l'acquisizione degli errori di avvio.Configure the host to capture startup errors.

Modifiche del modello di hostingHosting model changes

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.If the hostingModel setting is changed in the web.config file (explained in the Configuration with web.config section), the module recycles the worker process for IIS.

Per IIS Express, il modulo non ricicla il processo di lavoro. Attiva invece un arresto normale del processo di IIS Express corrente.For IIS Express, the module doesn't recycle the worker process but instead triggers a graceful shutdown of the current IIS Express process. La richiesta successiva all'app attiva un nuovo processo di IIS Express.The next request to the app spawns a new IIS Express process.

Nome processoProcess name

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

Molti moduli nativi, ad esempio l'autenticazione di Windows, rimangono attivi.Many native modules, such as Windows Authentication, remain active. Per altre informazioni sui moduli IIS attivi con il modulo ASP.NET Core, vedere Moduli IIS con ASP.NET Core.To learn more about IIS modules active with the ASP.NET Core Module, see Moduli IIS con ASP.NET Core.

Il modulo ASP.NET Core può anche:The ASP.NET Core Module can also:

  • Impostare variabili di ambiente per il processo di lavoro.Set environment variables for the worker process.
  • Registrare output stdout in una risorsa di archiviazione di file per la risoluzione di problemi di avvio.Log stdout output to file storage for troubleshooting startup issues.
  • Inoltrare token di autenticazione di Windows.Forward Windows authentication tokens.

Come installare e usare il modulo ASP.NET CoreHow to install and use the ASP.NET Core Module

Per istruzioni su come installare e usare il modulo ASP.NET Core, vedere Installare il bundle di hosting .NET Core.For instructions on how to install the ASP.NET Core Module, see Install the .NET Core Hosting Bundle.

Configurazione con web.configConfiguration with web.config

Il modulo ASP.NET Core viene configurato tramite la sezione aspNetCore del nodo system.webServer nel file web.config del sito.The ASP.NET Core Module is configured with the aspNetCore section of the system.webServer node in the site's web.config file.

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:The following web.config file is published for a framework-dependent deployment and configures the ASP.NET Core Module to handle site requests:

<?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:The following web.config is published for a self-contained deployment:

<?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 proprietà InheritInChildApplications è impostata su false per indicare che le impostazioni specificate nell'elemento <percorso> non sono ereditate da app che risiedono in una sottodirectory dell'app.The InheritInChildApplications property is set to false to indicate that the settings specified within the <location> element aren't inherited by apps that reside in a subdirectory of the app.

Quando un'app viene distribuita in Servizio app di Azure, il percorso stdoutLogFile è impostato su \\?\%home%\LogFiles\stdout.When an app is deployed to Azure App Service, the stdoutLogFile path is set to \\?\%home%\LogFiles\stdout. Il percorso salva i log stdout nella cartella LogFiles, ovvero una posizione creata automaticamente dal servizio.The path saves stdout logs to the LogFiles folder, which is a location automatically created by the service.

Per informazioni sulla configurazione delle applicazioni secondarie IIS, vedere Host ASP.NET Core in Windows con IIS.For information on IIS sub-application configuration, see Host ASP.NET Core in Windows con IIS.

Attributi dell'elemento aspNetCoreAttributes of the aspNetCore element

AttributoAttribute DescrizioneDescription Impostazione predefinitaDefault
arguments

Attributo stringa facoltativo.Optional string attribute.

Argomenti per l'eseguibile specificato in processPath.Arguments to the executable specified in processPath.

disableStartUpErrorPage

Attributo booleano facoltativo.Optional Boolean attribute.

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.If true, the 502.5 - Process Failure page is suppressed, and the 502 status code page configured in the web.config takes precedence.

false
forwardWindowsAuthToken

Attributo booleano facoltativo.Optional Boolean attribute.

Se true, il token viene inoltrato al processo figlio in ascolto su %ASPNETCORE_PORT% come un'intestazione 'MS-ASPNETCORE-WINAUTHTOKEN' per ogni richiesta.If true, the token is forwarded to the child process listening on %ASPNETCORE_PORT% as a header 'MS-ASPNETCORE-WINAUTHTOKEN' per request. È responsabilità del processo chiamare CloseHandle su questo token per ogni richiesta.It's the responsibility of that process to call CloseHandle on this token per request.

true
hostingModel

Attributo stringa facoltativo.Optional string attribute.

Specifica il modello di hosting come in-process (InProcess/inprocess) o out-of-process (OutOfProcess/outofprocess).Specifies the hosting model as in-process (InProcess/inprocess) or out-of-process (OutOfProcess/outofprocess).

InProcess
inprocess
processesPerApplication

Attributo Integer facoltativo.Optional integer attribute.

Specifica il numero di istanze del processo specificato nell'impostazione processPath che può essere riattivato per ogni app.Specifies the number of instances of the process specified in the processPath setting that can be spun up per app.

†Per l'hosting in-process, il valore è limitato a 1.†For in-process hosting, the value is limited to 1.

L'impostazione di processesPerApplication è sconsigliata.Setting processesPerApplication is discouraged. Questo attributo sarà rimosso nelle versioni future.This attribute will be removed in a future release.

Valore predefinito: 1Default: 1
Min: 1Min: 1
Max: 100Max: 100
processPath

Attributo stringa obbligatorio.Required string attribute.

Percorso del file eseguibile che avvia un processo in ascolto delle richieste HTTP.Path to the executable that launches a process listening for HTTP requests. I percorsi relativi sono supportati.Relative paths are supported. Se il percorso inizia con ., viene considerato relativo alla radice del sito.If the path begins with ., the path is considered to be relative to the site root.

rapidFailsPerMinute

Attributo Integer facoltativo.Optional integer attribute.

Specifica il numero di arresti anomali al minuto per il processo specificato in processPath.Specifies the number of times the process specified in processPath is allowed to crash per minute. Se questo limite viene superato, il modulo smette di avviare il processo per la parte restante del minuto.If this limit is exceeded, the module stops launching the process for the remainder of the minute.

Non supportato con l'hosting in-process.Not supported with in-process hosting.

Valore predefinito: 10Default: 10
Min: 0Min: 0
Max: 100Max: 100
requestTimeout

Attributo Timespan facoltativo.Optional timespan attribute.

Specifica la durata per cui il modulo ASP.NET Core attende una risposta dal processo in ascolto su %ASPNETCORE_PORT%.Specifies the duration for which the ASP.NET Core Module waits for a response from the process listening on %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.In versions of the ASP.NET Core Module that shipped with the release of ASP.NET Core 2.1 or later, the requestTimeout is specified in hours, minutes, and seconds.

Non è applicabile all'hosting in-process.Doesn't apply to in-process hosting. Per l'hosting in-process, il modulo resta in attesa che l'app elabori la richiesta.For in-process hosting, the module waits for the app to process the request.

I valori validi per i segmenti della stringa relativi a minuti e secondi sono compresi nell'intervallo tra 0 e 59.Valid values for minutes and seconds segments of the string are in the range 0-59. Se si usa 60 come valore per i minuti o i secondi, viene generato un errore 500 - Errore interno del server.Use of 60 in the value for minutes or seconds results in a 500 - Internal Server Error.

Valore predefinito: 00:02:00Default: 00:02:00
Min: 00:00:00Min: 00:00:00
Max: 360:00:00Max: 360:00:00
shutdownTimeLimit

Attributo Integer facoltativo.Optional integer attribute.

Durata in secondi per cui il modulo attende che il file eseguibile venga arrestato normalmente quando viene rilevato il file app_offline.htm.Duration in seconds that the module waits for the executable to gracefully shutdown when the app_offline.htm file is detected.

Valore predefinito: 10Default: 10
Min: 0Min: 0
Max: 600Max: 600
startupTimeLimit

Attributo Integer facoltativo.Optional integer attribute.

Durata in secondi per cui il modulo attende l'avvio di un processo in ascolto sulla porta da parte del file eseguibile.Duration in seconds that the module waits for the executable to start a process listening on the port. Se questo limite di tempo viene superato, il modulo termina il processo.If this time limit is exceeded, the module kills the process. 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.The module attempts to relaunch the process when it receives a new request and continues to attempt to restart the process on subsequent incoming requests unless the app fails to start rapidFailsPerMinute number of times in the last rolling minute.

Un valore pari a 0 (zero) non è considerato un timeout infinito.A value of 0 (zero) is not considered an infinite timeout.

Valore predefinito: 120Default: 120
Min: 0Min: 0
Max: 3600Max: 3600
stdoutLogEnabled

Attributo booleano facoltativo.Optional Boolean attribute.

Se true, stdout e stderr per il processo specificato in processPath vengono reindirizzati al file specificato in stdoutLogFile.If true, stdout and stderr for the process specified in processPath are redirected to the file specified in stdoutLogFile.

false
stdoutLogFile

Attributo stringa facoltativo.Optional string attribute.

Specifica il percorso relativo o assoluto per cui vengono registrati stdout e stderr dal processo specificato in processPath.Specifies the relative or absolute file path for which stdout and stderr from the process specified in processPath are logged. I percorsi relativi sono relativi alla radice del sito.Relative paths are relative to the root of the site. Qualsiasi percorso che inizia con . è relativo al sito radice e tutti gli altri percorsi vengono trattati come percorsi assoluti.Any path starting with . are relative to the site root and all other paths are treated as absolute paths. Le eventuali cartelle specificate nel percorso vengono create dal modulo quando viene creato il file di log.Any folders provided in the path are created by the module when the log file is created. 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.Using underscore delimiters, a timestamp, process ID, and file extension (.log) are added to the last segment of the stdoutLogFile path. 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.If .\logs\stdout is supplied as a value, an example stdout log is saved as stdout_20180205194132_1934.log in the logs folder when saved on 2/5/2018 at 19:41:32 with a process ID of 1934.

aspnetcore-stdout

Impostare le variabili di ambienteSet environment variables

È possibile specificare le variabili di ambiente per il processo nell'attributo processPath.Environment variables can be specified for the process in the processPath attribute. Specificare una variabile di ambiente con l'elemento figlio <environmentVariable> di un elemento della raccolta <environmentVariables>.Specify an environment variable with the <environmentVariable> child element of an <environmentVariables> collection element. Le variabili di ambiente impostate in questa sezione hanno la precedenza sulle variabili di ambiente di sistema.Environment variables set in this section take precedence over system environment variables.

Nell'esempio seguente vengono impostate due variabili di ambiente in Web. config. ASPNETCORE_ENVIRONMENT configura l'ambiente dell'app in modo da Development.The following example sets two environment variables in web.config. ASPNETCORE_ENVIRONMENT configures the app's environment to 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.A developer may temporarily set this value in the web.config file in order to force the Developer Exception Page to load when debugging an app exception. 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.CONFIG_DIR is an example of a user-defined environment variable, where the developer has written code that reads the value on startup to form a path for loading the app's configuration file.

<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 dell'ambiente direttamente in Web. config consiste nell'includere la proprietà <EnvironmentName> nel profilo di pubblicazione (con estensione pubxml) o nel file di progetto.An alternative to setting the environment directly in web.config is to include the <EnvironmentName> property in the publish profile (.pubxml) or project file. Questo approccio imposta l'ambiente in web.config quando viene pubblicato il progetto:This approach sets the environment in web.config when the project is published:

<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.Only set the ASPNETCORE_ENVIRONMENT environment variable to Development on staging and testing servers that aren't accessible to untrusted networks, such as the Internet.

app_offline.htmapp_offline.htm

Se un file denominato app_offline.htm viene rilevato nella directory radice di un'app, il modulo ASP.NET Core tenta di arrestare normalmente l'app e arresta l'elaborazione delle richieste in ingresso.If a file with the name app_offline.htm is detected in the root directory of an app, the ASP.NET Core Module attempts to gracefully shutdown the app and stop processing incoming requests. Se l'app è ancora in esecuzione dopo il numero di secondi definito in shutdownTimeLimit, il modulo ASP.NET Core termina il processo in esecuzione.If the app is still running after the number of seconds defined in shutdownTimeLimit, the ASP.NET Core Module kills the running process.

Mentre il file app_offline.htm è presente, il modulo ASP.NET Core risponde alle richieste restituendo il contenuto del file app_offline.htm.While the app_offline.htm file is present, the ASP.NET Core Module responds to requests by sending back the contents of the app_offline.htm file. Quando il file app_offline.htm viene rimosso, la richiesta successiva avvia l'app.When the app_offline.htm file is removed, the next request starts the app.

Quando si usa il modello di hosting out-of-process, l'app potrebbe non arrestarsi immediatamente se una connessione è aperta.When using the out-of-process hosting model, the app might not shut down immediately if there's an open connection. Ad esempio, una connessione WebSocket può ritardare l'arresto dell'app.For example, a websocket connection may delay app shut down.

Pagina di errore di avvioStart-up error page

Sia l'hosting In-Process che quello out-of-process producono pagine di errore personalizzate quando non riescono ad avviare l'app.Both in-process and out-of-process hosting produce custom error pages when they fail to start the 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.If the ASP.NET Core Module fails to find either the in-process or out-of-process request handler, a 500.0 - In-Process/Out-Of-Process Handler Load Failure status code page appears.

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.For in-process hosting if the ASP.NET Core Module fails to start the app, a 500.30 - Start Failure status code page appears.

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.For out-of-process hosting if the ASP.NET Core Module fails to launch the backend process or the backend process starts but fails to listen on the configured port, a 502.5 - Process Failure status code page appears.

Per non visualizzare questa pagina e tornare alla tabella codici di stato 5xx predefinita di IIS, usare l'attributo disableStartUpErrorPage.To suppress this page and revert to the default IIS 5xx status code page, use the disableStartUpErrorPage attribute. Per altre informazioni sulla configurazione di messaggi di errore personalizzati, vedere Errori HTTP <httpErrors>.For more information on configuring custom error messages, see HTTP Errors <httpErrors>.

Creazione e reindirizzamento dei logLog creation and redirection

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.The ASP.NET Core Module redirects stdout and stderr console output to disk if the stdoutLogEnabled and stdoutLogFile attributes of the aspNetCore element are set. Le eventuali le cartelle nel percorso stdoutLogFile vengono create dal modulo quando viene creato il file di log.Any folders in the stdoutLogFile path are created by the module when the log file is created. 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).The app pool must have write access to the location where the logs are written (use IIS AppPool\<app_pool_name> to provide write permission).

I log non vengono ruotati, a meno che non si verifichi il riciclo/riavvio del processo.Logs aren't rotated, unless process recycling/restart occurs. È responsabilità del provider di servizi di hosting limitare lo spazio su disco usato dai log.It's the responsibility of the hoster to limit the disk space the logs consume.

L'uso del log stdout è consigliato solo per la risoluzione dei problemi di avvio dell'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 in locale e l'esecuzione dell'app con IIS Express.Using the stdout log is only recommended for troubleshooting app startup issues when hosting on IIS or when using development-time support for IIS with Visual Studio, not while debugging locally and running the app with IIS Express.

Non usare il log stdout per scopi di registrazione generale delle app.Don't use the stdout log for general app logging purposes. 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.For routine logging in an ASP.NET Core app, use a logging library that limits log file size and rotates logs. Per altre informazioni, vedere Provider di registrazione di terze parti.For more information, see third-party logging providers.

Un timestamp e l'estensione del file vengono aggiunti automaticamente al momento della creazione del file di log.A timestamp and file extension are added automatically when the log file is created. 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.The log file name is composed by appending the timestamp, process ID, and file extension (.log) to the last segment of the stdoutLogFile path (typically stdout) delimited by underscores. 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.If the stdoutLogFile path ends with stdout, a log for an app with a PID of 1934 created on 2/5/2018 at 19:42:32 has the file name stdout_20180205194132_1934.log.

Se stdoutLogEnabled è false, gli errori che si verificano all'avvio dell'app vengono acquisiti ed emessi nel log eventi fino a 30 KB.If stdoutLogEnabled is false, errors that occur on app startup are captured and emitted to the event log up to 30 KB. Dopo l'avvio, tutti i log aggiuntivi vengono rimossi.After startup, all additional logs are discarded.

Nell'elemento aspNetCore di esempio seguente viene configurata la registrazione di stdout nel percorso relativo .\log\.The following sample aspNetCore element configures stdout logging at the relative path .\log\. Verificare che l'identità dell'utente AppPool disponga dell'autorizzazione di scrittura per il percorso specificato.Confirm that the AppPool user identity has permission to write to the path provided.

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

Quando si pubblica un'app per la distribuzione di app Azure Service, l'SDK Web imposta il valore di stdoutLogFile su \\?\%home%\LogFiles\stdout.When publishing an app for Azure App Service deployment, the Web SDK sets the stdoutLogFile value to \\?\%home%\LogFiles\stdout. La variabile di ambiente %home è predefinita per le app ospitate dal servizio app Azure.The %home environment variable is predefined for apps hosted by Azure App Service.

Per creare regole di filtro di registrazione, vedere le sezioni configurazione e filtro dei log della documentazione relativa alla registrazione del ASP.NET Core.To create logging filter rules, see the Configuration and Log filtering sections of the ASP.NET Core logging documentation.

Per ulteriori informazioni sui formati di percorso, vedere formati di percorso dei file nei sistemi Windows.For more information on path formats, see File path formats on Windows systems.

Log di diagnostica avanzatiEnhanced diagnostic logs

Il modulo ASP.NET Core può essere configurato per restituire log di diagnostica avanzata.The ASP.NET Core Module is configurable to provide enhanced diagnostics logs. Aggiungere l'elemento <handlerSettings> all'elemento <aspNetCore> in Web. config. L'impostazione del debugLevel su TRACE espone una maggiore fedeltà delle informazioni di diagnostica:Add the <handlerSettings> element to the <aspNetCore> element in web.config. Setting the debugLevel to TRACE exposes a higher fidelity of diagnostic information:

<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 eventuali cartelle nel percorso (logs nell'esempio precedente) vengono create dal modulo quando viene creato il file di log.Any folders in the path (logs in the preceding example) are created by the module when the log file is created. 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).The app pool must have write access to the location where the logs are written (use IIS AppPool\<app_pool_name> to provide write permission).

I valori di livello debug (debugLevel) possono includere sia il livello che il percorso.Debug level (debugLevel) values can include both the level and the location.

Livelli (in ordine dal meno dettagliato al più dettagliato):Levels (in order from least to most verbose):

  • ERRORERROR
  • WARNINGWARNING
  • INFOINFO
  • TRACETRACE

Posizioni (sono consentite più posizioni):Locations (multiple locations are permitted):

  • CONSOLECONSOLE
  • EVENTLOGEVENTLOG
  • FILEFILE

Le impostazioni del gestore possono essere specificate anche tramite le variabili di ambiente:The handler settings can also be provided via environment variables:

  • ASPNETCORE_MODULE_DEBUG_FILE – Percorso del file di logo di debug.ASPNETCORE_MODULE_DEBUG_FILE – Path to the debug log file. (Impostazione predefinita: aspnetcore-debug.log)(Default: aspnetcore-debug.log)
  • ASPNETCORE_MODULE_DEBUG – Impostazione del livello di debug.ASPNETCORE_MODULE_DEBUG – Debug level setting.

Avviso

Non lasciare la registrazione del debug abilitata nella distribuzione per un tempo superiore a quello necessario alla risoluzione di problema.Do not leave debug logging enabled in the deployment for longer than required to troubleshoot an issue. Le dimensioni del log non sono limitate.The size of the log isn't limited. 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.Leaving the debug log enabled can exhaust the available disk space and crash the server or app service.

Vedere Configurazione con web.config per un esempio dell'elemento aspNetCore nel file web.config.See Configuration with web.config for an example of the aspNetCore element in the web.config file.

Modificare le dimensioni dello stackModify the stack size

Si applica solo quando si usa il modello di hosting in-process.Only applies when using the in-process hosting model.

Configurare la dimensione dello stack gestito usando l'impostazione stackSize in byte in Web. config. Le dimensioni predefinite sono 1048576 byte (1 MB).Configure the managed stack size using the stackSize setting in bytes in web.config. The default size is 1048576 bytes (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 associazioneProxy configuration uses HTTP protocol and a pairing token

Si applica solo all'hosting out-of-process.Only applies to out-of-process hosting.

Il proxy creato tra il modulo ASP.NET Core e Kestrel usa il protocollo HTTP.The proxy created between the ASP.NET Core Module and Kestrel uses the HTTP protocol. Non vi è alcun rischio di intercettazione del traffico tra il modulo e Kestrel da una posizione esterna al server.There's no risk of eavesdropping the traffic between the module and Kestrel from a location off of the server.

Viene usato un token di associazione per garantire che le richieste ricevute da Kestrel siano state trasmesse tramite proxy da IIS e non provengano da un'altra origine.A pairing token is used to guarantee that the requests received by Kestrel were proxied by IIS and didn't come from some other source. Il token di associazione viene creato e impostato in una variabile di ambiente (ASPNETCORE_TOKEN) dal modulo.The pairing token is created and set into an environment variable (ASPNETCORE_TOKEN) by the module. Il token di associazione viene impostato anche in un'intestazione (MS-ASPNETCORE-TOKEN) in tutte le richieste trasmesse tramite proxy.The pairing token is also set into a header (MS-ASPNETCORE-TOKEN) on every proxied request. 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.IIS Middleware checks each request it receives to confirm that the pairing token header value matches the environment variable value. Se i valori del token non corrispondono, la richiesta viene registrata e rifiutata.If the token values are mismatched, the request is logged and rejected. La variabile di ambiente del token di associazione e il traffico tra il modulo e Kestrel non sono accessibili da una posizione esterna al server.The pairing token environment variable and the traffic between the module and Kestrel aren't accessible from a location off of the server. Senza conoscere il valore del token di associazione, un utente malintenzionato non può inviare richieste che ignorano il controllo nel middleware di IIS.Without knowing the pairing token value, an attacker can't submit requests that bypass the check in the IIS Middleware.

Modulo ASP.NET Core con configurazione condivisa di IISASP.NET Core Module with an IIS Shared Configuration

Il programma di installazione del modulo ASP.NET Core viene eseguito con i privilegi dell'account TrustedInstaller.The ASP.NET Core Module installer runs with the privileges of the TrustedInstaller account. 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.Because the local system account doesn't have modify permission for the share path used by the IIS Shared Configuration, the installer throws an access denied error when attempting to configure the module settings in the applicationHost.config file on the share.

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:When using an IIS Shared Configuration on the same machine as the IIS installation, run the ASP.NET Core Hosting Bundle installer with the OPT_NO_SHARED_CONFIG_CHECK parameter set to 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:When the path to the shared configuration isn't on the same machine as the IIS installation, follow these steps:

  1. Disabilitare la configurazione condivisa di IIS.Disable the IIS Shared Configuration.
  2. Eseguire il programma di installazione.Run the installer.
  3. Esportare il file applicationHost.config aggiornato nella condivisione.Export the updated applicationHost.config file to the share.
  4. Abilitare di nuovo la configurazione condivisa di IIS.Re-enable the IIS Shared Configuration.

Versione del modulo e log del programma di installazione del bundle di hostingModule version and Hosting Bundle installer logs

Per determinare la versione del modulo ASP.NET Core installato:To determine the version of the installed ASP.NET Core Module:

  1. Nel sistema host passare a %windir%\System32\inetsrv.On the hosting system, navigate to %windir%\System32\inetsrv.
  2. Individuare il file aspnetcore.dll.Locate the aspnetcore.dll file.
  3. Fare clic con il pulsante destro del mouse sul file e scegliere Proprietà dal menu di scelta rapida.Right-click the file and select Properties from the contextual menu.
  4. Selezionare la scheda Dettagli . La versione del file e la versione del prodotto rappresentano la versione installata del modulo.Select the Details tab. The File version and Product version represent the installed version of the module.

I log del programma di installazione del bundle di hosting per il modulo sono disponibili in C:\utenti\% username%\AppData\\locale. Il file è denominato dd_DotNetCoreWinSvrHosting__<timestamp > _000_AspNetCoreModule_x64. log.The Hosting Bundle installer logs for the module are found at C:\Users\%UserName%\AppData\Local\Temp. The file is named dd_DotNetCoreWinSvrHosting__<timestamp>_000_AspNetCoreModule_x64.log.

Percorsi dei file di modulo, schema e configurazioneModule, schema, and configuration file locations

ModuloModule

IIS (x86/amd64):IIS (x86/amd64):

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

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

  • %Programmi%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll%ProgramFiles%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll

  • %Programmi(x86)%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll%ProgramFiles(x86)%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll

IIS Express (x86/amd64):IIS Express (x86/amd64):

  • %ProgramFiles%\IIS Express\aspnetcore.dll%ProgramFiles%\IIS Express\aspnetcore.dll

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

  • %Programmi%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll%ProgramFiles%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll

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

SchemaSchema

IISIIS

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

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

IIS ExpressIIS Express

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

  • %Programmi%\IIS Express\config\schema\aspnetcore_schema_v2.xml%ProgramFiles%\IIS Express\config\schema\aspnetcore_schema_v2.xml

ConfigurazioneConfiguration

IISIIS

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

IIS ExpressIIS Express

  • Visual Studio: {APPLICATION ROOT}\.vs\config\applicationHost.configVisual Studio: {APPLICATION ROOT}\.vs\config\applicationHost.config

  • Interfaccia della riga di comando di iisexpress.exe: %USERPROFILE%\Documents\IISExpress\config\applicationhost.configiisexpress.exe CLI: %USERPROFILE%\Documents\IISExpress\config\applicationhost.config

È possibile trovare i file eseguendo una ricerca di aspnetcore nel file applicationHost.config.The files can be found by searching for aspnetcore in the applicationHost.config file.

Il modulo ASP.NET Core è un modulo IIS nativo collegato alla pipeline di IIS per eseguire le operazioni seguenti:The ASP.NET Core Module is a native IIS module that plugs into the IIS pipeline to either:

Versioni di Windows supportate:Supported Windows versions:

  • Windows 7 o versione successivaWindows 7 or later
  • Windows Server 2008 R2 o versioni successiveWindows Server 2008 R2 or later

In caso di hosting in-process, il modulo usa un'implementazione di server in-process per IIS detta server HTTP di IIS (IISHttpServer).When hosting in-process, the module uses an in-process server implementation for IIS, called IIS HTTP Server (IISHttpServer).

In caso di hosting out-of-process, il modulo funziona solo con Kestrel.When hosting out-of-process, the module only works with Kestrel. Il modulo non funziona con http. sys.The module doesn't function with HTTP.sys.

Modelli di hostingHosting models

Modello di hosting in-processIn-process hosting model

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):To configure an app for in-process hosting, add the <AspNetCoreHostingModel> property to the app's project file with a value of InProcess (out-of-process hosting is set with OutOfProcess):

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

Il modello di hosting In-Process non è supportato per le app ASP.NET Core destinate a .NET Framework.The in-process hosting model isn't supported for ASP.NET Core apps that target the .NET Framework.

Il valore di <AspNetCoreHostingModel> non fa distinzione tra maiuscole e minuscole, pertanto inprocess e outofprocess sono valori validi.The value of <AspNetCoreHostingModel> is case insensitive, so inprocess and outofprocess are valid values.

Se la proprietà <AspNetCoreHostingModel> non è presente nel file, il valore predefinito è OutOfProcess.If the <AspNetCoreHostingModel> property isn't present in the file, the default value is OutOfProcess.

In caso di hosting in-process, vengono applicate le caratteristiche seguenti:The following characteristics apply when hosting in-process:

  • Viene usato un server HTTP di IIS (IISHttpServer) al posto del server Kestrel.IIS HTTP Server (IISHttpServer) is used instead of Kestrel server. Per in-process, CreateDefaultBuilder chiama UseIIS per:For in-process, CreateDefaultBuilder calls UseIIS to:

    • Registrare IISHttpServer.Register the 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.Configure the port and base path the server should listen on when running behind the ASP.NET Core Module.
    • Configurare l'host per l'acquisizione degli errori di avvio.Configure the host to capture startup errors.
  • L'attributo requestTimeout non viene applicato all'hosting in-process.The requestTimeout attribute doesn't apply to in-process hosting.

  • Non è supportata la condivisione di un pool di app tra le app.Sharing an app pool among apps isn't supported. Usare un pool di app per ogni app.Use one app pool per 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.When using Web Deploy or manually placing an app_offline.htm file in the deployment, the app might not shut down immediately if there's an open connection. Ad esempio, una connessione WebSocket può ritardare l'arresto dell'app.For example, a websocket connection may delay app shut down.

  • 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.The architecture (bitness) of the app and installed runtime (x64 or x86) must match the architecture of the app pool.

  • Le disconnessioni del client vengono rilevate.Client disconnects are detected. Il token di annullamento HttpContext.RequestAborted viene cancellato quando il client si disconnette.The HttpContext.RequestAborted cancellation token is cancelled when the client disconnects.

  • 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).In ASP.NET Core 2.2.1 or earlier, GetCurrentDirectory returns the worker directory of the process started by IIS rather than the app's directory (for example, C:\Windows\System32\inetsrv for w3wp.exe).

    Per vedere il codice di esempio che imposta la directory corrente dell'app, vedere la classe CurrentDirectoryHelpers.For sample code that sets the app's current directory, see the CurrentDirectoryHelpers class. Chiamare il metodo SetCurrentDirectory.Call the SetCurrentDirectory method. Le chiamate successive a GetCurrentDirectory specificano la directory dell'app.Subsequent calls to GetCurrentDirectory provide the app's directory.

  • In caso di hosting in-process, AuthenticateAsync non viene chiamato internamente per inizializzare un utente.When hosting in-process, AuthenticateAsync isn't called internally to initialize a user. Pertanto, un'implementazione di IClaimsTransformation usate per trasformare le attestazioni dopo ogni autenticazione non viene attivata per impostazione predefinita.Therefore, an IClaimsTransformation implementation used to transform claims after every authentication isn't activated by default. Quando si trasformano le attestazioni con un'implementazione di IClaimsTransformation, chiamare AddAuthentication per aggiungere i servizi di autenticazione:When transforming claims with an IClaimsTransformation implementation, call AddAuthentication to add authentication services:

    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-processOut-of-process hosting model

Per configurare un'app per l'hosting out-of-process, usare uno dei due approcci seguenti nel file di progetto:To configure an app for out-of-process hosting, use either of the following approaches in the project file:

  • Non specificare la proprietà <AspNetCoreHostingModel>.Don't specify the <AspNetCoreHostingModel> property. Se la proprietà <AspNetCoreHostingModel> non è presente nel file, il valore predefinito è OutOfProcess.If the <AspNetCoreHostingModel> property isn't present in the file, the default value is OutOfProcess.
  • Impostare il valore della proprietà <AspNetCoreHostingModel> su OutOfProcess (l'hosting in-process è impostato con InProcess):Set the value of the <AspNetCoreHostingModel> property to OutOfProcess (in-process hosting is set with InProcess):
<PropertyGroup>
  <AspNetCoreHostingModel>OutOfProcess</AspNetCoreHostingModel>
</PropertyGroup>

Il valore non fa distinzione tra maiuscole e minuscole, pertanto inprocess e outofprocess sono valori validi.The value is case insensitive, so inprocess and outofprocess are valid values.

Viene usato il server Kestrel al posto di un server HTTP di IIS (IISHttpServer).Kestrel server is used instead of IIS HTTP Server (IISHttpServer).

Per out-of-process, CreateDefaultBuilder chiama UseIISIntegration per:For out-of-process, CreateDefaultBuilder calls UseIISIntegration to:

  • 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.Configure the port and base path the server should listen on when running behind the ASP.NET Core Module.
  • Configurare l'host per l'acquisizione degli errori di avvio.Configure the host to capture startup errors.

Modifiche del modello di hostingHosting model changes

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.If the hostingModel setting is changed in the web.config file (explained in the Configuration with web.config section), the module recycles the worker process for IIS.

Per IIS Express, il modulo non ricicla il processo di lavoro. Attiva invece un arresto normale del processo di IIS Express corrente.For IIS Express, the module doesn't recycle the worker process but instead triggers a graceful shutdown of the current IIS Express process. La richiesta successiva all'app attiva un nuovo processo di IIS Express.The next request to the app spawns a new IIS Express process.

Nome processoProcess name

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

Molti moduli nativi, ad esempio l'autenticazione di Windows, rimangono attivi.Many native modules, such as Windows Authentication, remain active. Per altre informazioni sui moduli IIS attivi con il modulo ASP.NET Core, vedere Moduli IIS con ASP.NET Core.To learn more about IIS modules active with the ASP.NET Core Module, see Moduli IIS con ASP.NET Core.

Il modulo ASP.NET Core può anche:The ASP.NET Core Module can also:

  • Impostare variabili di ambiente per il processo di lavoro.Set environment variables for the worker process.
  • Registrare output stdout in una risorsa di archiviazione di file per la risoluzione di problemi di avvio.Log stdout output to file storage for troubleshooting startup issues.
  • Inoltrare token di autenticazione di Windows.Forward Windows authentication tokens.

Come installare e usare il modulo ASP.NET CoreHow to install and use the ASP.NET Core Module

Per istruzioni su come installare e usare il modulo ASP.NET Core, vedere Installare il bundle di hosting .NET Core.For instructions on how to install the ASP.NET Core Module, see Install the .NET Core Hosting Bundle.

Configurazione con web.configConfiguration with web.config

Il modulo ASP.NET Core viene configurato tramite la sezione aspNetCore del nodo system.webServer nel file web.config del sito.The ASP.NET Core Module is configured with the aspNetCore section of the system.webServer node in the site's web.config file.

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:The following web.config file is published for a framework-dependent deployment and configures the ASP.NET Core Module to handle site requests:

<?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:The following web.config is published for a self-contained deployment:

<?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 proprietà InheritInChildApplications è impostata su false per indicare che le impostazioni specificate nell'elemento <percorso> non sono ereditate da app che risiedono in una sottodirectory dell'app.The InheritInChildApplications property is set to false to indicate that the settings specified within the <location> element aren't inherited by apps that reside in a subdirectory of the app.

Quando un'app viene distribuita in Servizio app di Azure, il percorso stdoutLogFile è impostato su \\?\%home%\LogFiles\stdout.When an app is deployed to Azure App Service, the stdoutLogFile path is set to \\?\%home%\LogFiles\stdout. Il percorso salva i log stdout nella cartella LogFiles, ovvero una posizione creata automaticamente dal servizio.The path saves stdout logs to the LogFiles folder, which is a location automatically created by the service.

Per informazioni sulla configurazione delle applicazioni secondarie IIS, vedere Host ASP.NET Core in Windows con IIS.For information on IIS sub-application configuration, see Host ASP.NET Core in Windows con IIS.

Attributi dell'elemento aspNetCoreAttributes of the aspNetCore element

AttributoAttribute DescrizioneDescription Impostazione predefinitaDefault
arguments

Attributo stringa facoltativo.Optional string attribute.

Argomenti per l'eseguibile specificato in processPath.Arguments to the executable specified in processPath.

disableStartUpErrorPage

Attributo booleano facoltativo.Optional Boolean attribute.

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.If true, the 502.5 - Process Failure page is suppressed, and the 502 status code page configured in the web.config takes precedence.

false
forwardWindowsAuthToken

Attributo booleano facoltativo.Optional Boolean attribute.

Se true, il token viene inoltrato al processo figlio in ascolto su %ASPNETCORE_PORT% come un'intestazione 'MS-ASPNETCORE-WINAUTHTOKEN' per ogni richiesta.If true, the token is forwarded to the child process listening on %ASPNETCORE_PORT% as a header 'MS-ASPNETCORE-WINAUTHTOKEN' per request. È responsabilità del processo chiamare CloseHandle su questo token per ogni richiesta.It's the responsibility of that process to call CloseHandle on this token per request.

true
hostingModel

Attributo stringa facoltativo.Optional string attribute.

Specifica il modello di hosting come in-process (InProcess/inprocess) o out-of-process (OutOfProcess/outofprocess).Specifies the hosting model as in-process (InProcess/inprocess) or out-of-process (OutOfProcess/outofprocess).

OutOfProcess
outofprocess
processesPerApplication

Attributo Integer facoltativo.Optional integer attribute.

Specifica il numero di istanze del processo specificato nell'impostazione processPath che può essere riattivato per ogni app.Specifies the number of instances of the process specified in the processPath setting that can be spun up per app.

†Per l'hosting in-process, il valore è limitato a 1.†For in-process hosting, the value is limited to 1.

L'impostazione di processesPerApplication è sconsigliata.Setting processesPerApplication is discouraged. Questo attributo sarà rimosso nelle versioni future.This attribute will be removed in a future release.

Valore predefinito: 1Default: 1
Min: 1Min: 1
Max: 100Max: 100
processPath

Attributo stringa obbligatorio.Required string attribute.

Percorso del file eseguibile che avvia un processo in ascolto delle richieste HTTP.Path to the executable that launches a process listening for HTTP requests. I percorsi relativi sono supportati.Relative paths are supported. Se il percorso inizia con ., viene considerato relativo alla radice del sito.If the path begins with ., the path is considered to be relative to the site root.

rapidFailsPerMinute

Attributo Integer facoltativo.Optional integer attribute.

Specifica il numero di arresti anomali al minuto per il processo specificato in processPath.Specifies the number of times the process specified in processPath is allowed to crash per minute. Se questo limite viene superato, il modulo smette di avviare il processo per la parte restante del minuto.If this limit is exceeded, the module stops launching the process for the remainder of the minute.

Non supportato con l'hosting in-process.Not supported with in-process hosting.

Valore predefinito: 10Default: 10
Min: 0Min: 0
Max: 100Max: 100
requestTimeout

Attributo Timespan facoltativo.Optional timespan attribute.

Specifica la durata per cui il modulo ASP.NET Core attende una risposta dal processo in ascolto su %ASPNETCORE_PORT%.Specifies the duration for which the ASP.NET Core Module waits for a response from the process listening on %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.In versions of the ASP.NET Core Module that shipped with the release of ASP.NET Core 2.1 or later, the requestTimeout is specified in hours, minutes, and seconds.

Non è applicabile all'hosting in-process.Doesn't apply to in-process hosting. Per l'hosting in-process, il modulo resta in attesa che l'app elabori la richiesta.For in-process hosting, the module waits for the app to process the request.

I valori validi per i segmenti della stringa relativi a minuti e secondi sono compresi nell'intervallo tra 0 e 59.Valid values for minutes and seconds segments of the string are in the range 0-59. Se si usa 60 come valore per i minuti o i secondi, viene generato un errore 500 - Errore interno del server.Use of 60 in the value for minutes or seconds results in a 500 - Internal Server Error.

Valore predefinito: 00:02:00Default: 00:02:00
Min: 00:00:00Min: 00:00:00
Max: 360:00:00Max: 360:00:00
shutdownTimeLimit

Attributo Integer facoltativo.Optional integer attribute.

Durata in secondi per cui il modulo attende che il file eseguibile venga arrestato normalmente quando viene rilevato il file app_offline.htm.Duration in seconds that the module waits for the executable to gracefully shutdown when the app_offline.htm file is detected.

Valore predefinito: 10Default: 10
Min: 0Min: 0
Max: 600Max: 600
startupTimeLimit

Attributo Integer facoltativo.Optional integer attribute.

Durata in secondi per cui il modulo attende l'avvio di un processo in ascolto sulla porta da parte del file eseguibile.Duration in seconds that the module waits for the executable to start a process listening on the port. Se questo limite di tempo viene superato, il modulo termina il processo.If this time limit is exceeded, the module kills the process. 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.The module attempts to relaunch the process when it receives a new request and continues to attempt to restart the process on subsequent incoming requests unless the app fails to start rapidFailsPerMinute number of times in the last rolling minute.

Un valore pari a 0 (zero) non è considerato un timeout infinito.A value of 0 (zero) is not considered an infinite timeout.

Valore predefinito: 120Default: 120
Min: 0Min: 0
Max: 3600Max: 3600
stdoutLogEnabled

Attributo booleano facoltativo.Optional Boolean attribute.

Se true, stdout e stderr per il processo specificato in processPath vengono reindirizzati al file specificato in stdoutLogFile.If true, stdout and stderr for the process specified in processPath are redirected to the file specified in stdoutLogFile.

false
stdoutLogFile

Attributo stringa facoltativo.Optional string attribute.

Specifica il percorso relativo o assoluto per cui vengono registrati stdout e stderr dal processo specificato in processPath.Specifies the relative or absolute file path for which stdout and stderr from the process specified in processPath are logged. I percorsi relativi sono relativi alla radice del sito.Relative paths are relative to the root of the site. Qualsiasi percorso che inizia con . è relativo al sito radice e tutti gli altri percorsi vengono trattati come percorsi assoluti.Any path starting with . are relative to the site root and all other paths are treated as absolute paths. Le eventuali cartelle specificate nel percorso vengono create dal modulo quando viene creato il file di log.Any folders provided in the path are created by the module when the log file is created. 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.Using underscore delimiters, a timestamp, process ID, and file extension (.log) are added to the last segment of the stdoutLogFile path. 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.If .\logs\stdout is supplied as a value, an example stdout log is saved as stdout_20180205194132_1934.log in the logs folder when saved on 2/5/2018 at 19:41:32 with a process ID of 1934.

aspnetcore-stdout

Impostazione delle variabili di ambienteSetting environment variables

È possibile specificare le variabili di ambiente per il processo nell'attributo processPath.Environment variables can be specified for the process in the processPath attribute. Specificare una variabile di ambiente con l'elemento figlio <environmentVariable> di un elemento della raccolta <environmentVariables>.Specify an environment variable with the <environmentVariable> child element of an <environmentVariables> collection element. Le variabili di ambiente impostate in questa sezione hanno la precedenza sulle variabili di ambiente di sistema.Environment variables set in this section take precedence over system environment variables.

Nell'esempio seguente vengono impostate due variabili di ambiente.The following example sets two environment variables. ASPNETCORE_ENVIRONMENT configura l'ambiente dell'app su Development.ASPNETCORE_ENVIRONMENT configures the app's environment to 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.A developer may temporarily set this value in the web.config file in order to force the Developer Exception Page to load when debugging an app exception. 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.CONFIG_DIR is an example of a user-defined environment variable, where the developer has written code that reads the value on startup to form a path for loading the app's configuration file.

<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 dell'ambiente direttamente in Web. config consiste nell'includere la proprietà <EnvironmentName> nel profilo di pubblicazione (con estensione pubxml) o nel file di progetto.An alternative to setting the environment directly in web.config is to include the <EnvironmentName> property in the publish profile (.pubxml) or project file. Questo approccio imposta l'ambiente in web.config quando viene pubblicato il progetto:This approach sets the environment in web.config when the project is published:

<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.Only set the ASPNETCORE_ENVIRONMENT environment variable to Development on staging and testing servers that aren't accessible to untrusted networks, such as the Internet.

app_offline.htmapp_offline.htm

Se un file denominato app_offline.htm viene rilevato nella directory radice di un'app, il modulo ASP.NET Core tenta di arrestare normalmente l'app e arresta l'elaborazione delle richieste in ingresso.If a file with the name app_offline.htm is detected in the root directory of an app, the ASP.NET Core Module attempts to gracefully shutdown the app and stop processing incoming requests. Se l'app è ancora in esecuzione dopo il numero di secondi definito in shutdownTimeLimit, il modulo ASP.NET Core termina il processo in esecuzione.If the app is still running after the number of seconds defined in shutdownTimeLimit, the ASP.NET Core Module kills the running process.

Mentre il file app_offline.htm è presente, il modulo ASP.NET Core risponde alle richieste restituendo il contenuto del file app_offline.htm.While the app_offline.htm file is present, the ASP.NET Core Module responds to requests by sending back the contents of the app_offline.htm file. Quando il file app_offline.htm viene rimosso, la richiesta successiva avvia l'app.When the app_offline.htm file is removed, the next request starts the app.

Quando si usa il modello di hosting out-of-process, l'app potrebbe non arrestarsi immediatamente se una connessione è aperta.When using the out-of-process hosting model, the app might not shut down immediately if there's an open connection. Ad esempio, una connessione WebSocket può ritardare l'arresto dell'app.For example, a websocket connection may delay app shut down.

Pagina di errore di avvioStart-up error page

Sia l'hosting In-Process che quello out-of-process producono pagine di errore personalizzate quando non riescono ad avviare l'app.Both in-process and out-of-process hosting produce custom error pages when they fail to start the 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.If the ASP.NET Core Module fails to find either the in-process or out-of-process request handler, a 500.0 - In-Process/Out-Of-Process Handler Load Failure status code page appears.

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.For in-process hosting if the ASP.NET Core Module fails to start the app, a 500.30 - Start Failure status code page appears.

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.For out-of-process hosting if the ASP.NET Core Module fails to launch the backend process or the backend process starts but fails to listen on the configured port, a 502.5 - Process Failure status code page appears.

Per non visualizzare questa pagina e tornare alla tabella codici di stato 5xx predefinita di IIS, usare l'attributo disableStartUpErrorPage.To suppress this page and revert to the default IIS 5xx status code page, use the disableStartUpErrorPage attribute. Per altre informazioni sulla configurazione di messaggi di errore personalizzati, vedere Errori HTTP <httpErrors>.For more information on configuring custom error messages, see HTTP Errors <httpErrors>.

Creazione e reindirizzamento dei logLog creation and redirection

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.The ASP.NET Core Module redirects stdout and stderr console output to disk if the stdoutLogEnabled and stdoutLogFile attributes of the aspNetCore element are set. Le eventuali le cartelle nel percorso stdoutLogFile vengono create dal modulo quando viene creato il file di log.Any folders in the stdoutLogFile path are created by the module when the log file is created. 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).The app pool must have write access to the location where the logs are written (use IIS AppPool\<app_pool_name> to provide write permission).

I log non vengono ruotati, a meno che non si verifichi il riciclo/riavvio del processo.Logs aren't rotated, unless process recycling/restart occurs. È responsabilità del provider di servizi di hosting limitare lo spazio su disco usato dai log.It's the responsibility of the hoster to limit the disk space the logs consume.

L'uso del log stdout è consigliato solo per la risoluzione dei problemi di avvio dell'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 in locale e l'esecuzione dell'app con IIS Express.Using the stdout log is only recommended for troubleshooting app startup issues when hosting on IIS or when using development-time support for IIS with Visual Studio, not while debugging locally and running the app with IIS Express.

Non usare il log stdout per scopi di registrazione generale delle app.Don't use the stdout log for general app logging purposes. 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.For routine logging in an ASP.NET Core app, use a logging library that limits log file size and rotates logs. Per altre informazioni, vedere Provider di registrazione di terze parti.For more information, see third-party logging providers.

Un timestamp e l'estensione del file vengono aggiunti automaticamente al momento della creazione del file di log.A timestamp and file extension are added automatically when the log file is created. 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.The log file name is composed by appending the timestamp, process ID, and file extension (.log) to the last segment of the stdoutLogFile path (typically stdout) delimited by underscores. 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.If the stdoutLogFile path ends with stdout, a log for an app with a PID of 1934 created on 2/5/2018 at 19:42:32 has the file name stdout_20180205194132_1934.log.

Se stdoutLogEnabled è false, gli errori che si verificano all'avvio dell'app vengono acquisiti ed emessi nel log eventi fino a 30 KB.If stdoutLogEnabled is false, errors that occur on app startup are captured and emitted to the event log up to 30 KB. Dopo l'avvio, tutti i log aggiuntivi vengono rimossi.After startup, all additional logs are discarded.

Nell'elemento aspNetCore di esempio seguente viene configurata la registrazione di stdout nel percorso relativo .\log\.The following sample aspNetCore element configures stdout logging at the relative path .\log\. Verificare che l'identità dell'utente AppPool disponga dell'autorizzazione di scrittura per il percorso specificato.Confirm that the AppPool user identity has permission to write to the path provided.

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

Quando si pubblica un'app per la distribuzione di app Azure Service, l'SDK Web imposta il valore di stdoutLogFile su \\?\%home%\LogFiles\stdout.When publishing an app for Azure App Service deployment, the Web SDK sets the stdoutLogFile value to \\?\%home%\LogFiles\stdout. La variabile di ambiente %home è predefinita per le app ospitate dal servizio app Azure.The %home environment variable is predefined for apps hosted by Azure App Service.

Per ulteriori informazioni sui formati di percorso, vedere formati di percorso dei file nei sistemi Windows.For more information on path formats, see File path formats on Windows systems.

Log di diagnostica avanzatiEnhanced diagnostic logs

Il modulo ASP.NET Core può essere configurato per restituire log di diagnostica avanzata.The ASP.NET Core Module is configurable to provide enhanced diagnostics logs. Aggiungere l'elemento <handlerSettings> all'elemento <aspNetCore> in Web. config. L'impostazione del debugLevel su TRACE espone una maggiore fedeltà delle informazioni di diagnostica:Add the <handlerSettings> element to the <aspNetCore> element in web.config. Setting the debugLevel to TRACE exposes a higher fidelity of diagnostic information:

<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 specificato per il valore <handlerSetting> (logs nell'esempio precedente) non vengono create automaticamente dal modulo e devono essere già presenti nella distribuzione.Folders in the path provided to the <handlerSetting> value (logs in the preceding example) aren't created by the module automatically and should pre-exist in the deployment. 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).The app pool must have write access to the location where the logs are written (use IIS AppPool\<app_pool_name> to provide write permission).

I valori di livello debug (debugLevel) possono includere sia il livello che il percorso.Debug level (debugLevel) values can include both the level and the location.

Livelli (in ordine dal meno dettagliato al più dettagliato):Levels (in order from least to most verbose):

  • ERRORERROR
  • WARNINGWARNING
  • INFOINFO
  • TRACETRACE

Posizioni (sono consentite più posizioni):Locations (multiple locations are permitted):

  • CONSOLECONSOLE
  • EVENTLOGEVENTLOG
  • FILEFILE

Le impostazioni del gestore possono essere specificate anche tramite le variabili di ambiente:The handler settings can also be provided via environment variables:

  • ASPNETCORE_MODULE_DEBUG_FILE – Percorso del file di logo di debug.ASPNETCORE_MODULE_DEBUG_FILE – Path to the debug log file. (Impostazione predefinita: aspnetcore-debug.log)(Default: aspnetcore-debug.log)
  • ASPNETCORE_MODULE_DEBUG – Impostazione del livello di debug.ASPNETCORE_MODULE_DEBUG – Debug level setting.

Avviso

Non lasciare la registrazione del debug abilitata nella distribuzione per un tempo superiore a quello necessario alla risoluzione di problema.Do not leave debug logging enabled in the deployment for longer than required to troubleshoot an issue. Le dimensioni del log non sono limitate.The size of the log isn't limited. 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.Leaving the debug log enabled can exhaust the available disk space and crash the server or app service.

Vedere Configurazione con web.config per un esempio dell'elemento aspNetCore nel file web.config.See Configuration with web.config for an example of the aspNetCore element in the web.config file.

La configurazione del proxy usa il protocollo HTTP e un token di associazioneProxy configuration uses HTTP protocol and a pairing token

Si applica solo all'hosting out-of-process.Only applies to out-of-process hosting.

Il proxy creato tra il modulo ASP.NET Core e Kestrel usa il protocollo HTTP.The proxy created between the ASP.NET Core Module and Kestrel uses the HTTP protocol. Non vi è alcun rischio di intercettazione del traffico tra il modulo e Kestrel da una posizione esterna al server.There's no risk of eavesdropping the traffic between the module and Kestrel from a location off of the server.

Viene usato un token di associazione per garantire che le richieste ricevute da Kestrel siano state trasmesse tramite proxy da IIS e non provengano da un'altra origine.A pairing token is used to guarantee that the requests received by Kestrel were proxied by IIS and didn't come from some other source. Il token di associazione viene creato e impostato in una variabile di ambiente (ASPNETCORE_TOKEN) dal modulo.The pairing token is created and set into an environment variable (ASPNETCORE_TOKEN) by the module. Il token di associazione viene impostato anche in un'intestazione (MS-ASPNETCORE-TOKEN) in tutte le richieste trasmesse tramite proxy.The pairing token is also set into a header (MS-ASPNETCORE-TOKEN) on every proxied request. 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.IIS Middleware checks each request it receives to confirm that the pairing token header value matches the environment variable value. Se i valori del token non corrispondono, la richiesta viene registrata e rifiutata.If the token values are mismatched, the request is logged and rejected. La variabile di ambiente del token di associazione e il traffico tra il modulo e Kestrel non sono accessibili da una posizione esterna al server.The pairing token environment variable and the traffic between the module and Kestrel aren't accessible from a location off of the server. Senza conoscere il valore del token di associazione, un utente malintenzionato non può inviare richieste che ignorano il controllo nel middleware di IIS.Without knowing the pairing token value, an attacker can't submit requests that bypass the check in the IIS Middleware.

Modulo ASP.NET Core con configurazione condivisa di IISASP.NET Core Module with an IIS Shared Configuration

Il programma di installazione del modulo ASP.NET Core viene eseguito con i privilegi dell'account TrustedInstaller.The ASP.NET Core Module installer runs with the privileges of the TrustedInstaller account. 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.Because the local system account doesn't have modify permission for the share path used by the IIS Shared Configuration, the installer throws an access denied error when attempting to configure the module settings in the applicationHost.config file on the share.

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:When using an IIS Shared Configuration on the same machine as the IIS installation, run the ASP.NET Core Hosting Bundle installer with the OPT_NO_SHARED_CONFIG_CHECK parameter set to 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:When the path to the shared configuration isn't on the same machine as the IIS installation, follow these steps:

  1. Disabilitare la configurazione condivisa di IIS.Disable the IIS Shared Configuration.
  2. Eseguire il programma di installazione.Run the installer.
  3. Esportare il file applicationHost.config aggiornato nella condivisione.Export the updated applicationHost.config file to the share.
  4. Abilitare di nuovo la configurazione condivisa di IIS.Re-enable the IIS Shared Configuration.

Versione del modulo e log del programma di installazione del bundle di hostingModule version and Hosting Bundle installer logs

Per determinare la versione del modulo ASP.NET Core installato:To determine the version of the installed ASP.NET Core Module:

  1. Nel sistema host passare a %windir%\System32\inetsrv.On the hosting system, navigate to %windir%\System32\inetsrv.
  2. Individuare il file aspnetcore.dll.Locate the aspnetcore.dll file.
  3. Fare clic con il pulsante destro del mouse sul file e scegliere Proprietà dal menu di scelta rapida.Right-click the file and select Properties from the contextual menu.
  4. Selezionare la scheda Dettagli . La versione del file e la versione del prodotto rappresentano la versione installata del modulo.Select the Details tab. The File version and Product version represent the installed version of the module.

I log del programma di installazione del bundle di hosting per il modulo sono disponibili in C:\utenti\% username%\AppData\\locale. Il file è denominato dd_DotNetCoreWinSvrHosting__<timestamp > _000_AspNetCoreModule_x64. log.The Hosting Bundle installer logs for the module are found at C:\Users\%UserName%\AppData\Local\Temp. The file is named dd_DotNetCoreWinSvrHosting__<timestamp>_000_AspNetCoreModule_x64.log.

Percorsi dei file di modulo, schema e configurazioneModule, schema, and configuration file locations

ModuloModule

IIS (x86/amd64):IIS (x86/amd64):

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

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

  • %Programmi%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll%ProgramFiles%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll

  • %Programmi(x86)%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll%ProgramFiles(x86)%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll

IIS Express (x86/amd64):IIS Express (x86/amd64):

  • %ProgramFiles%\IIS Express\aspnetcore.dll%ProgramFiles%\IIS Express\aspnetcore.dll

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

  • %Programmi%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll%ProgramFiles%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll

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

SchemaSchema

IISIIS

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

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

IIS ExpressIIS Express

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

  • %Programmi%\IIS Express\config\schema\aspnetcore_schema_v2.xml%ProgramFiles%\IIS Express\config\schema\aspnetcore_schema_v2.xml

ConfigurazioneConfiguration

IISIIS

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

IIS ExpressIIS Express

  • Visual Studio: {APPLICATION ROOT}\.vs\config\applicationHost.configVisual Studio: {APPLICATION ROOT}\.vs\config\applicationHost.config

  • Interfaccia della riga di comando di iisexpress.exe: %USERPROFILE%\Documents\IISExpress\config\applicationhost.configiisexpress.exe CLI: %USERPROFILE%\Documents\IISExpress\config\applicationhost.config

È possibile trovare i file eseguendo una ricerca di aspnetcore nel file applicationHost.config.The files can be found by searching for aspnetcore in the applicationHost.config file.

Il modulo ASP.NET Core è un modulo IIS nativo collegato alla pipeline di IIS che inoltra le richieste Web alle app back-end ASP.NET Core.The ASP.NET Core Module is a native IIS module that plugs into the IIS pipeline to forward web requests to backend ASP.NET Core apps.

Versioni di Windows supportate:Supported Windows versions:

  • Windows 7 o versione successivaWindows 7 or later
  • Windows Server 2008 R2 o versioni successiveWindows Server 2008 R2 or later

Il modulo funziona solo con Kestrel.The module only works with Kestrel. Il modulo non è compatibile con HTTP.sys.The module is incompatible with 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.Because ASP.NET Core apps run in a process separate from the IIS worker process, the module also handles process management. 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.The module starts the process for the ASP.NET Core app when the first request arrives and restarts the app if it crashes. 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).This is essentially the same behavior as seen with ASP.NET 4.x apps that run in-process in IIS that are managed by the Windows Process Activation Service (WAS).

Il diagramma seguente illustra la relazione tra IIS, il modulo ASP.NET Core e un'app:The following diagram illustrates the relationship between IIS, the ASP.NET Core Module, and an app:

Modulo ASP.NET Core

Le richieste arrivano dal Web al driver HTTP.sys in modalità kernel.Requests arrive from the web to the kernel-mode HTTP.sys driver. Il driver instrada le richieste a IIS sulla porta configurata per il sito Web, in genere 80 (HTTP) o 443 (HTTPS).The driver routes the requests to IIS on the website's configured port, usually 80 (HTTP) or 443 (HTTPS). Il modulo inoltra le richieste a Kestrel su una porta casuale per l'app non corrispondente alla porta 80 o 443.The module forwards the requests to Kestrel on a random port for the app, which isn't port 80 or 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}.The module specifies the port via an environment variable at startup, and the IIS Integration Middleware configures the server to listen on http://localhost:{port}. Vengono eseguiti controlli aggiuntivi e le richieste che non provengono dal modulo vengono rifiutate.Additional checks are performed, and requests that don't originate from the module are rejected. Il modulo non supporta l'inoltro HTTPS, pertanto le richieste vengono inoltrate tramite HTTP anche se sono state ricevute da IIS tramite HTTPS.The module doesn't support HTTPS forwarding, so requests are forwarded over HTTP even if received by IIS over HTTPS.

Dopo che Kestrel ha prelevato la richiesta dal modulo, viene eseguito il push della richiesta nella pipeline middleware ASP.NET Core.After Kestrel picks up the request from the module, the request is pushed into the ASP.NET Core middleware pipeline. La pipeline middleware gestisce la richiesta e la passa come istanza di HttpContext alla logica dell'app.The middleware pipeline handles the request and passes it on as an HttpContext instance to the app's logic. Il middleware aggiunto dall'integrazione di IIS aggiorna lo schema, l'IP remoto e il percorso di base all'account per l'inoltro della richiesta a Kestrel.Middleware added by IIS Integration updates the scheme, remote IP, and pathbase to account for forwarding the request to 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.The app's response is passed back to IIS, which pushes it back out to the HTTP client that initiated the request.

Molti moduli nativi, ad esempio l'autenticazione di Windows, rimangono attivi.Many native modules, such as Windows Authentication, remain active. Per altre informazioni sui moduli IIS attivi con il modulo ASP.NET Core, vedere Moduli IIS con ASP.NET Core.To learn more about IIS modules active with the ASP.NET Core Module, see Moduli IIS con ASP.NET Core.

Il modulo ASP.NET Core può anche:The ASP.NET Core Module can also:

  • Impostare variabili di ambiente per il processo di lavoro.Set environment variables for the worker process.
  • Registrare output stdout in una risorsa di archiviazione di file per la risoluzione di problemi di avvio.Log stdout output to file storage for troubleshooting startup issues.
  • Inoltrare token di autenticazione di Windows.Forward Windows authentication tokens.

Come installare e usare il modulo ASP.NET CoreHow to install and use the ASP.NET Core Module

Per istruzioni su come installare e usare il modulo ASP.NET Core, vedere Installare il bundle di hosting .NET Core.For instructions on how to install the ASP.NET Core Module, see Install the .NET Core Hosting Bundle.

Configurazione con web.configConfiguration with web.config

Il modulo ASP.NET Core viene configurato tramite la sezione aspNetCore del nodo system.webServer nel file web.config del sito.The ASP.NET Core Module is configured with the aspNetCore section of the system.webServer node in the site's web.config file.

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:The following web.config file is published for a framework-dependent deployment and configures the ASP.NET Core Module to handle site requests:

<?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:The following web.config is published for a self-contained deployment:

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

Quando un'app viene distribuita in Servizio app di Azure, il percorso stdoutLogFile è impostato su \\?\%home%\LogFiles\stdout.When an app is deployed to Azure App Service, the stdoutLogFile path is set to \\?\%home%\LogFiles\stdout. Il percorso salva i log stdout nella cartella LogFiles, ovvero una posizione creata automaticamente dal servizio.The path saves stdout logs to the LogFiles folder, which is a location automatically created by the service.

Per informazioni sulla configurazione delle applicazioni secondarie IIS, vedere Host ASP.NET Core in Windows con IIS.For information on IIS sub-application configuration, see Host ASP.NET Core in Windows con IIS.

Attributi dell'elemento aspNetCoreAttributes of the aspNetCore element

AttributoAttribute DescrizioneDescription Impostazione predefinitaDefault
arguments

Attributo stringa facoltativo.Optional string attribute.

Argomenti per l'eseguibile specificato in processPath.Arguments to the executable specified in processPath.

disableStartUpErrorPage

Attributo booleano facoltativo.Optional Boolean attribute.

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.If true, the 502.5 - Process Failure page is suppressed, and the 502 status code page configured in the web.config takes precedence.

false
forwardWindowsAuthToken

Attributo booleano facoltativo.Optional Boolean attribute.

Se true, il token viene inoltrato al processo figlio in ascolto su %ASPNETCORE_PORT% come un'intestazione 'MS-ASPNETCORE-WINAUTHTOKEN' per ogni richiesta.If true, the token is forwarded to the child process listening on %ASPNETCORE_PORT% as a header 'MS-ASPNETCORE-WINAUTHTOKEN' per request. È responsabilità del processo chiamare CloseHandle su questo token per ogni richiesta.It's the responsibility of that process to call CloseHandle on this token per request.

true
processesPerApplication

Attributo Integer facoltativo.Optional integer attribute.

Specifica il numero di istanze del processo specificato nell'impostazione processPath che può essere riattivato per ogni app.Specifies the number of instances of the process specified in the processPath setting that can be spun up per app.

L'impostazione di processesPerApplication è sconsigliata.Setting processesPerApplication is discouraged. Questo attributo sarà rimosso nelle versioni future.This attribute will be removed in a future release.

Valore predefinito: 1Default: 1
Min: 1Min: 1
Max: 100Max: 100
processPath

Attributo stringa obbligatorio.Required string attribute.

Percorso del file eseguibile che avvia un processo in ascolto delle richieste HTTP.Path to the executable that launches a process listening for HTTP requests. I percorsi relativi sono supportati.Relative paths are supported. Se il percorso inizia con ., viene considerato relativo alla radice del sito.If the path begins with ., the path is considered to be relative to the site root.

rapidFailsPerMinute

Attributo Integer facoltativo.Optional integer attribute.

Specifica il numero di arresti anomali al minuto per il processo specificato in processPath.Specifies the number of times the process specified in processPath is allowed to crash per minute. Se questo limite viene superato, il modulo smette di avviare il processo per la parte restante del minuto.If this limit is exceeded, the module stops launching the process for the remainder of the minute.

Valore predefinito: 10Default: 10
Min: 0Min: 0
Max: 100Max: 100
requestTimeout

Attributo Timespan facoltativo.Optional timespan attribute.

Specifica la durata per cui il modulo ASP.NET Core attende una risposta dal processo in ascolto su %ASPNETCORE_PORT%.Specifies the duration for which the ASP.NET Core Module waits for a response from the process listening on %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.In versions of the ASP.NET Core Module that shipped with the release of ASP.NET Core 2.1 or later, the requestTimeout is specified in hours, minutes, and seconds.

Valore predefinito: 00:02:00Default: 00:02:00
Min: 00:00:00Min: 00:00:00
Max: 360:00:00Max: 360:00:00
shutdownTimeLimit

Attributo Integer facoltativo.Optional integer attribute.

Durata in secondi per cui il modulo attende che il file eseguibile venga arrestato normalmente quando viene rilevato il file app_offline.htm.Duration in seconds that the module waits for the executable to gracefully shutdown when the app_offline.htm file is detected.

Valore predefinito: 10Default: 10
Min: 0Min: 0
Max: 600Max: 600
startupTimeLimit

Attributo Integer facoltativo.Optional integer attribute.

Durata in secondi per cui il modulo attende l'avvio di un processo in ascolto sulla porta da parte del file eseguibile.Duration in seconds that the module waits for the executable to start a process listening on the port. Se questo limite di tempo viene superato, il modulo termina il processo.If this time limit is exceeded, the module kills the process. 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.The module attempts to relaunch the process when it receives a new request and continues to attempt to restart the process on subsequent incoming requests unless the app fails to start rapidFailsPerMinute number of times in the last rolling minute.

Un valore pari a 0 (zero) non è considerato un timeout infinito.A value of 0 (zero) is not considered an infinite timeout.

Valore predefinito: 120Default: 120
Min: 0Min: 0
Max: 3600Max: 3600
stdoutLogEnabled

Attributo booleano facoltativo.Optional Boolean attribute.

Se true, stdout e stderr per il processo specificato in processPath vengono reindirizzati al file specificato in stdoutLogFile.If true, stdout and stderr for the process specified in processPath are redirected to the file specified in stdoutLogFile.

false
stdoutLogFile

Attributo stringa facoltativo.Optional string attribute.

Specifica il percorso relativo o assoluto per cui vengono registrati stdout e stderr dal processo specificato in processPath.Specifies the relative or absolute file path for which stdout and stderr from the process specified in processPath are logged. I percorsi relativi sono relativi alla radice del sito.Relative paths are relative to the root of the site. Qualsiasi percorso che inizia con . è relativo al sito radice e tutti gli altri percorsi vengono trattati come percorsi assoluti.Any path starting with . are relative to the site root and all other paths are treated as absolute paths. Le eventuali cartelle specificate nel percorso devono essere già esistenti affinché il modulo possa creare il file di log.Any folders provided in the path must exist in order for the module to create the log file. 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.Using underscore delimiters, a timestamp, process ID, and file extension (.log) are added to the last segment of the stdoutLogFile path. 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.If .\logs\stdout is supplied as a value, an example stdout log is saved as stdout_20180205194132_1934.log in the logs folder when saved on 2/5/2018 at 19:41:32 with a process ID of 1934.

aspnetcore-stdout

Impostazione delle variabili di ambienteSetting environment variables

È possibile specificare le variabili di ambiente per il processo nell'attributo processPath.Environment variables can be specified for the process in the processPath attribute. Specificare una variabile di ambiente con l'elemento figlio <environmentVariable> di un elemento della raccolta <environmentVariables>.Specify an environment variable with the <environmentVariable> child element of an <environmentVariables> collection element.

Avviso

Le variabili di ambiente impostate in questa sezione sono in conflitto con le variabili di ambiente di sistema impostate con lo stesso nome.Environment variables set in this section conflict with system environment variables set with the same name. 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.If an environment variable is set in both the web.config file and at the system level in Windows, the value from the web.config file becomes appended to the system environment variable value (for example, ASPNETCORE_ENVIRONMENT: Development;Development), which prevents the app from starting.

Nell'esempio seguente vengono impostate due variabili di ambiente.The following example sets two environment variables. ASPNETCORE_ENVIRONMENT configura l'ambiente dell'app su Development.ASPNETCORE_ENVIRONMENT configures the app's environment to 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.A developer may temporarily set this value in the web.config file in order to force the Developer Exception Page to load when debugging an app exception. 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.CONFIG_DIR is an example of a user-defined environment variable, where the developer has written code that reads the value on startup to form a path for loading the app's configuration file.

<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.Only set the ASPNETCORE_ENVIRONMENT environment variable to Development on staging and testing servers that aren't accessible to untrusted networks, such as the Internet.

app_offline.htmapp_offline.htm

Se un file denominato app_offline.htm viene rilevato nella directory radice di un'app, il modulo ASP.NET Core tenta di arrestare normalmente l'app e arresta l'elaborazione delle richieste in ingresso.If a file with the name app_offline.htm is detected in the root directory of an app, the ASP.NET Core Module attempts to gracefully shutdown the app and stop processing incoming requests. Se l'app è ancora in esecuzione dopo il numero di secondi definito in shutdownTimeLimit, il modulo ASP.NET Core termina il processo in esecuzione.If the app is still running after the number of seconds defined in shutdownTimeLimit, the ASP.NET Core Module kills the running process.

Mentre il file app_offline.htm è presente, il modulo ASP.NET Core risponde alle richieste restituendo il contenuto del file app_offline.htm.While the app_offline.htm file is present, the ASP.NET Core Module responds to requests by sending back the contents of the app_offline.htm file. Quando il file app_offline.htm viene rimosso, la richiesta successiva avvia l'app.When the app_offline.htm file is removed, the next request starts the app.

Pagina di errore di avvioStart-up error page

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.If the ASP.NET Core Module fails to launch the backend process or the backend process starts but fails to listen on the configured port, a 502.5 - Process Failure status code page appears. Per non visualizzare questa pagina e tornare alla tabella codici di stato 502 predefinita di IIS, usare l'attributo disableStartUpErrorPage.To suppress this page and revert to the default IIS 502 status code page, use the disableStartUpErrorPage attribute. Per altre informazioni sulla configurazione di messaggi di errore personalizzati, vedere Errori HTTP <httpErrors>.For more information on configuring custom error messages, see HTTP Errors <httpErrors>.

Tabella codici di stato 502.5 Errore del processo

Creazione e reindirizzamento dei logLog creation and redirection

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.The ASP.NET Core Module redirects stdout and stderr console output to disk if the stdoutLogEnabled and stdoutLogFile attributes of the aspNetCore element are set. Le eventuali le cartelle nel percorso stdoutLogFile vengono create dal modulo quando viene creato il file di log.Any folders in the stdoutLogFile path are created by the module when the log file is created. 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).The app pool must have write access to the location where the logs are written (use IIS AppPool\<app_pool_name> to provide write permission).

I log non vengono ruotati, a meno che non si verifichi il riciclo/riavvio del processo.Logs aren't rotated, unless process recycling/restart occurs. È responsabilità del provider di servizi di hosting limitare lo spazio su disco usato dai log.It's the responsibility of the hoster to limit the disk space the logs consume.

L'uso del log stdout è consigliato solo per la risoluzione dei problemi di avvio dell'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 in locale e l'esecuzione dell'app con IIS Express.Using the stdout log is only recommended for troubleshooting app startup issues when hosting on IIS or when using development-time support for IIS with Visual Studio, not while debugging locally and running the app with IIS Express.

Non usare il log stdout per scopi di registrazione generale delle app.Don't use the stdout log for general app logging purposes. 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.For routine logging in an ASP.NET Core app, use a logging library that limits log file size and rotates logs. Per altre informazioni, vedere Provider di registrazione di terze parti.For more information, see third-party logging providers.

Un timestamp e l'estensione del file vengono aggiunti automaticamente al momento della creazione del file di log.A timestamp and file extension are added automatically when the log file is created. 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.The log file name is composed by appending the timestamp, process ID, and file extension (.log) to the last segment of the stdoutLogFile path (typically stdout) delimited by underscores. 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.If the stdoutLogFile path ends with stdout, a log for an app with a PID of 1934 created on 2/5/2018 at 19:42:32 has the file name stdout_20180205194132_1934.log.

Nell'elemento aspNetCore di esempio seguente viene configurata la registrazione di stdout nel percorso relativo .\log\.The following sample aspNetCore element configures stdout logging at the relative path .\log\. Verificare che l'identità dell'utente AppPool disponga dell'autorizzazione di scrittura per il percorso specificato.Confirm that the AppPool user identity has permission to write to the path provided.

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

Quando si pubblica un'app per la distribuzione di app Azure Service, l'SDK Web imposta il valore di stdoutLogFile su \\?\%home%\LogFiles\stdout.When publishing an app for Azure App Service deployment, the Web SDK sets the stdoutLogFile value to \\?\%home%\LogFiles\stdout. La variabile di ambiente %home è predefinita per le app ospitate dal servizio app Azure.The %home environment variable is predefined for apps hosted by Azure App Service.

Per creare regole di filtro di registrazione, vedere le sezioni configurazione e filtro dei log della documentazione relativa alla registrazione del ASP.NET Core.To create logging filter rules, see the Configuration and Log filtering sections of the ASP.NET Core logging documentation.

Per ulteriori informazioni sui formati di percorso, vedere formati di percorso dei file nei sistemi Windows.For more information on path formats, see File path formats on Windows systems.

La configurazione del proxy usa il protocollo HTTP e un token di associazioneProxy configuration uses HTTP protocol and a pairing token

Il proxy creato tra il modulo ASP.NET Core e Kestrel usa il protocollo HTTP.The proxy created between the ASP.NET Core Module and Kestrel uses the HTTP protocol. Non vi è alcun rischio di intercettazione del traffico tra il modulo e Kestrel da una posizione esterna al server.There's no risk of eavesdropping the traffic between the module and Kestrel from a location off of the server.

Viene usato un token di associazione per garantire che le richieste ricevute da Kestrel siano state trasmesse tramite proxy da IIS e non provengano da un'altra origine.A pairing token is used to guarantee that the requests received by Kestrel were proxied by IIS and didn't come from some other source. Il token di associazione viene creato e impostato in una variabile di ambiente (ASPNETCORE_TOKEN) dal modulo.The pairing token is created and set into an environment variable (ASPNETCORE_TOKEN) by the module. Il token di associazione viene impostato anche in un'intestazione (MS-ASPNETCORE-TOKEN) in tutte le richieste trasmesse tramite proxy.The pairing token is also set into a header (MS-ASPNETCORE-TOKEN) on every proxied request. 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.IIS Middleware checks each request it receives to confirm that the pairing token header value matches the environment variable value. Se i valori del token non corrispondono, la richiesta viene registrata e rifiutata.If the token values are mismatched, the request is logged and rejected. La variabile di ambiente del token di associazione e il traffico tra il modulo e Kestrel non sono accessibili da una posizione esterna al server.The pairing token environment variable and the traffic between the module and Kestrel aren't accessible from a location off of the server. Senza conoscere il valore del token di associazione, un utente malintenzionato non può inviare richieste che ignorano il controllo nel middleware di IIS.Without knowing the pairing token value, an attacker can't submit requests that bypass the check in the IIS Middleware.

Modulo ASP.NET Core con configurazione condivisa di IISASP.NET Core Module with an IIS Shared Configuration

Il programma di installazione del modulo ASP.NET Core viene eseguito con i privilegi dell'account TrustedInstaller.The ASP.NET Core Module installer runs with the privileges of the TrustedInstaller account. 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.Because the local system account doesn't have modify permission for the share path used by the IIS Shared Configuration, the installer throws an access denied error when attempting to configure the module settings in the applicationHost.config file on the share.

Quando si usa una configurazione condivisa di IIS, attenersi ai passaggi riportati di seguito:When using an IIS Shared Configuration, follow these steps:

  1. Disabilitare la configurazione condivisa di IIS.Disable the IIS Shared Configuration.
  2. Eseguire il programma di installazione.Run the installer.
  3. Esportare il file applicationHost.config aggiornato nella condivisione.Export the updated applicationHost.config file to the share.
  4. Abilitare di nuovo la configurazione condivisa di IIS.Re-enable the IIS Shared Configuration.

Versione del modulo e log del programma di installazione del bundle di hostingModule version and Hosting Bundle installer logs

Per determinare la versione del modulo ASP.NET Core installato:To determine the version of the installed ASP.NET Core Module:

  1. Nel sistema host passare a %windir%\System32\inetsrv.On the hosting system, navigate to %windir%\System32\inetsrv.
  2. Individuare il file aspnetcore.dll.Locate the aspnetcore.dll file.
  3. Fare clic con il pulsante destro del mouse sul file e scegliere Proprietà dal menu di scelta rapida.Right-click the file and select Properties from the contextual menu.
  4. Selezionare la scheda Dettagli . La versione del file e la versione del prodotto rappresentano la versione installata del modulo.Select the Details tab. The File version and Product version represent the installed version of the module.

I log del programma di installazione del bundle di hosting per il modulo sono disponibili in C:\utenti\% username%\AppData\\locale. Il file è denominato dd_DotNetCoreWinSvrHosting__<timestamp > _000_AspNetCoreModule_x64. log.The Hosting Bundle installer logs for the module are found at C:\Users\%UserName%\AppData\Local\Temp. The file is named dd_DotNetCoreWinSvrHosting__<timestamp>_000_AspNetCoreModule_x64.log.

Percorsi dei file di modulo, schema e configurazioneModule, schema, and configuration file locations

ModuloModule

IIS (x86/amd64):IIS (x86/amd64):

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

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

IIS Express (x86/amd64):IIS Express (x86/amd64):

  • %ProgramFiles%\IIS Express\aspnetcore.dll%ProgramFiles%\IIS Express\aspnetcore.dll

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

SchemaSchema

IISIIS

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

IIS ExpressIIS Express

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

ConfigurazioneConfiguration

IISIIS

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

IIS ExpressIIS Express

  • Visual Studio: {APPLICATION ROOT}\.vs\config\applicationHost.configVisual Studio: {APPLICATION ROOT}\.vs\config\applicationHost.config

  • Interfaccia della riga di comando di iisexpress.exe: %USERPROFILE%\Documents\IISExpress\config\applicationhost.configiisexpress.exe CLI: %USERPROFILE%\Documents\IISExpress\config\applicationhost.config

È possibile trovare i file eseguendo una ricerca di aspnetcore nel file applicationHost.config.The files can be found by searching for aspnetcore in the applicationHost.config file.

Risorse aggiuntiveAdditional resources