Číst v angličtině

Sdílet prostřednictvím

Modul ASP.NET Core (ANCM) pro službu IIS

  • Článek

Poznámka

Toto není nejnovější verze tohoto článku. Aktuální verzi najdete v tomto článku ve verzi .NET 9.

Upozornění

Tato verze ASP.NET Core se už nepodporuje. Další informace najdete v zásadách podpory .NET a .NET Core. Aktuální verzi najdete v tomto článku ve verzi .NET 9.

Důležité

Tyto informace se týkají předběžného vydání produktu, který může být podstatně změněn před komerčním vydáním. Microsoft neposkytuje žádné záruky, výslovné ani předpokládané, týkající se zde uváděných informací.

Aktuální verzi najdete v tomto článku ve verzi .NET 9.

Modul ASP.NET Core (ANCM) je nativní modul SLUŽBY IIS, který se připojuje ke kanálu SLUŽBY IIS, což umožňuje ASP.NET core aplikacím pracovat se službou IIS. Spusťte aplikace ASP.NET Core se službou IIS:

  • Hostování aplikace ASP.NET Core uvnitř pracovního procesu služby IIS (w3wp.exeoznačovaného jako model hostování v procesu).
  • Předávání webových požadavků do back-endové aplikace ASP.NET Core, na Kestrel které běží server, se označuje jako model hostování mimo proces.

Mezi jednotlivými modely hostování existují kompromisy. Ve výchozím nastavení se model hostování v procesu používá kvůli lepšímu výkonu a diagnostice.

Další informace a doprovodné materiály ke konfiguraci najdete v následujících tématech:

Instalace základního modulu ASP.NET (ANCM)

Modul ASP.NET Core (ANCM) se instaluje s modulem runtime .NET Core z hostitelské sady .NET Core. Modul ASP.NET Core je dopředu a zpětně kompatibilní s verzemi v rámci podpory rozhraní .NET.

V úložišti Oznámení se zobrazují zásadní změny a informační zpravodaje zabezpečení. Oznámení můžou být omezena na konkrétní verzi výběrem filtru Popisek .

Stáhněte si instalační program na následujícím odkazu:

Instalační program aktuální sady pro hosting .NET Core (přímé stažení)

Další informace, včetně instalace starší verze modulu, naleznete v tématu Hosting Bundle.

Kurz publikování aplikace ASP.NET Core na serveru služby IIS najdete tady: Publikování aplikace ASP.NET Core ve službě IIS.

Modul ASP.NET Core (ANCM) je nativní modul SLUŽBY IIS, který se připojuje ke kanálu služby IIS a umožňuje:

  • Hostování aplikace ASP.NET Core uvnitř pracovního procesu služby IIS (w3wp.exeoznačovaného jako model hostování v procesu).
  • Přesměrovávat webové požadavky do back-endové aplikace ASP.NET Core, na Kestrel které běží server, označovaný jako model hostování mimo proces.

Podporované verze Windows:

  • Windows 7 nebo novější
  • Windows Server 2012 R2 nebo novější

Při hostování v procesu modul používá implementaci procesového serveru pro službu IIS s názvem IIS HTTP Server (IISHttpServer).

Při hostování out-of-process, modul funguje pouze s Kestrel. Modul nefunguje s HTTP.sys.

Modely hostingu

Model vnitroprocesového hostování

ASP.NET základní aplikace jsou výchozí pro model hostování v procesu.

Při hostování v procesu platí následující charakteristiky:

  • Server HTTP služby IIS (IISHttpServer) se používá místo Kestrel serveru. V případě in-process, CreateDefaultBuilder volání UseIIS do:

    • Zaregistrujte .IISHttpServer
    • Nakonfigurujte port a základní cestu, na které by měl server naslouchat při spuštění za modulem ASP.NET Core.
    • Nakonfigurujte hostitele tak, aby zachytil chyby při spuštění.

  • Atribut requestTimeout se nevztahuje na hostování v procesu.

  • Sdílení fondu aplikací mezi aplikacemi se nepodporuje. Pro každou aplikaci použijte jeden fond aplikací.

  • Pokud používáte nasazení webu nebo ručně umístíte app_offline.htm soubor do nasazení, nemusí se aplikace okamžitě vypnout, pokud existuje otevřené připojení. Například připojení Protokolu WebSocket může zpozdit vypnutí aplikace.

  • Architektura (bitová verze) aplikace a nainstalovaného modulu runtime (x64 nebo x86) musí odpovídat architektuře fondu aplikací.

  • Zjistí se odpojení klienta. Token HttpContext.RequestAborted zrušení se zruší, když se klient odpojí.

  • V ASP.NET Core 2.2.1 nebo starší GetCurrentDirectory vrátí pracovní adresář procesu spuštěného službou IIS místo adresáře aplikace (například C:\Windows\System32\inetsrv ).w3wp.exe

    Ukázkový kód, který nastaví aktuální adresář aplikace, najdete v CurrentDirectoryHelpers třídě. Zavolejte metodu SetCurrentDirectory . Následná volání pro GetCurrentDirectory poskytnutí adresáře aplikace.

  • Při hostování v procesu se nevolá interně za AuthenticateAsync účelem inicializace uživatele. Proto se implementace použitá IClaimsTransformation k transformaci deklarací identity po každém ověření ve výchozím nastavení neaktivuje. Při transformaci deklarací identity pomocí IClaimsTransformation implementace volání AddAuthentication pro přidání ověřovacích služeb:

    C# 
    public void ConfigureServices(IServiceCollection services)
{
    services.AddTransient<IClaimsTransformation, ClaimsTransformer>();
    services.AddAuthentication(IISServerDefaults.AuthenticationScheme);
}

public void Configure(IApplicationBuilder app)
{
    app.UseAuthentication();
}
    • Nasazení webového balíčku (s jedním souborem) se nepodporují.

Model mimoprocesového hostování

Pokud chcete nakonfigurovat aplikaci pro hostování mimo proces, nastavte hodnotu <AspNetCoreHostingModel> vlastnosti v OutOfProcess souboru projektu (.csproj):

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

Hostování v procesu je nastaveno na InProcessvýchozí hodnotu.

Hodnota <AspNetCoreHostingModel> nerozlišuje malá a velká písmena, takže inprocess jsou outofprocess platné hodnoty.

Kestrel server se používá místo serveru HTTP služby IIS (IISHttpServer).

V případě mimoprocesu CreateDefaultBuilder volání UseIISIntegration na:

  • Nakonfigurujte port a základní cestu, na které by měl server naslouchat při spuštění za modulem ASP.NET Core.
  • Nakonfigurujte hostitele tak, aby zachytil chyby při spuštění.

Změny modelu hostování

hostingModel Pokud je nastavení v web.config souboru změněno (vysvětleno v části Konfigurace s oddílemweb.config), modul recykluje pracovní proces pro službu IIS.

V případě služby IIS Express modul nerecykluje pracovní proces, ale místo toho aktivuje řádné vypnutí aktuálního procesu SLUŽBY IIS Express. Další požadavek aplikace vytvoří nový proces SLUŽBY IIS Express.

Název procesu

Process.GetCurrentProcess().ProcessName sestav w3wp/iisexpress (v procesu) nebo dotnet (mimo proces).

Mnoho nativních modulů, jako je ověřování systému Windows, zůstává aktivních. Další informace o modulech SLUŽBY IIS, které jsou aktivní s modulem ASP.NET Core, najdete v tématu Moduly IIS s ASP.NET Core.

Základní modul ASP.NET může také:

  • Nastavte proměnné prostředí pro pracovní proces.
  • Výstup protokolu stdout do úložiště souborů pro řešení potíží se spuštěním
  • Předávat ověřovací tokeny Systému Windows

Jak nainstalovat a používat modul ASP.NET Core (ANCM)

Pokyny k instalaci modulu ASP.NET Core najdete v tématu Instalace sady hostingu .NET Core. Modul ASP.NET Core je dopředu a zpětně kompatibilní s verzemi v rámci podpory rozhraní .NET.

V úložišti Oznámení se zobrazují zásadní změny a informační zpravodaje zabezpečení. Oznámení můžou být omezena na konkrétní verzi výběrem filtru Popisek .

Konfigurace pomocí web.config

Modul ASP.NET Core je nakonfigurovaný s aspNetCore částí system.webServer uzlu v souboru web.config webu.

Následující web.config soubor se publikuje pro nasazení závislé na rozhraní a nakonfiguruje modul ASP.NET Core pro zpracování požadavků lokality:

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

Následující soubor web.config se publikuje pro samostatné nasazení:

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

Vlastnost InheritInChildApplications je nastavena tak, aby false indikovala, že nastavení zadaná v rámci <location> elementu nejsou zděděna aplikacemi, které se nacházejí v podadresáři aplikace.

Když je aplikace nasazená do služby Aplikace Azure Service, je cesta nastavená stdoutLogFile na \\?\%home%\LogFiles\stdout. Cesta ukládá protokoly stdout do LogFiles složky, což je umístění automaticky vytvořené službou.

Informace o konfiguraci dílčí aplikace služby IIS naleznete v tématu Hostitel ASP.NET Core ve Windows se službou IIS.

Atributy elementu aspNetCore

Atribut Popis Výchozí
arguments

Volitelný atribut řetězce.

Argumenty spustitelného souboru zadaného v cestě processPath.
disableStartUpErrorPage

Volitelný logický atribut.

Pokud je pravda, stránka 502.5 – Selhání procesu je potlačena a stránka stavového kódu 502 nakonfigurovaná v souboru web.config má přednost.

 false
forwardWindowsAuthToken

Volitelný logický atribut.

Pokud je hodnota true, token se předá podřízeného procesu, na %ASPNETCORE_PORT% který naslouchá jako hlavička 'MS-ASPNETCORE-WINAUTHTOKEN' na požadavek. Za volání CloseHandle na tento token na žádost zodpovídá tento proces.

 true
hostingModel

Volitelný atribut řetězce.

Určuje model hostování jako in-process (InProcess/inprocess) nebo out-of-process ().OutOfProcess/outofprocess

 InProcess
inprocess
processesPerApplication

Volitelný celočíselnou atribut.

Určuje počet instancí procesu zadaného v nastavení processPath , které je možné pro každou aplikaci spustit.

†Na hostování v procesu je hodnota omezena na 1.

Nastavení processesPerApplication se nedoporučuje. Tento atribut bude odebrán v budoucí verzi.

 Výchozí: 1
Min: 1
Max: 100†
processPath

Povinný atribut řetězce.

Cesta ke spustitelnému souboru, který spouští proces, který naslouchá požadavkům HTTP. Podporují se relativní cesty. Pokud cesta začíná ., cesta se považuje za relativní vzhledem ke kořenovému adresáři webu.
rapidFailsPerMinute

Volitelný celočíselnou atribut.

Určuje počet povolených chybových ukončení procesu zadaných v cestě processPath za minutu. Pokud tento limit překročíte, modul po zbytek minuty zastaví spuštění procesu.

Nepodporuje se hostování v procesu.

 Výchozí: 10
Min: 0
Max: 100
requestTimeout

Volitelný atribut časového rozsahu

Určuje dobu, po kterou ASP.NET základní modul čeká na odpověď z procesu, na kterém naslouchá %ASPNETCORE_PORT%.

Ve verzích modulu ASP.NET Core, který se dodává s vydáním verze ASP.NET Core 2.1 nebo novější, requestTimeout se zadává v hodinách, minutách a sekundách.

Nevztahuje se na hostování v procesu. V případě hostování v procesu modul čeká, až aplikace zpracuje požadavek.

Platné hodnoty pro minuty a sekundy řetězce jsou v rozsahu 0–59. Výsledkem použití 60 v hodnotě minut nebo sekund je 500 – vnitřní chyba serveru.

 Výchozí: 00:02:00
Min: 00:00:00
Max: 360:00:00
shutdownTimeLimit

Volitelný celočíselnou atribut.

Doba trvání v sekundách, po kterou modul čeká na řádné vypnutí spustitelného app_offline.htm souboru při zjištění souboru.

 Výchozí: 10
Min: 0
Max: 600
startupTimeLimit

Volitelný celočíselnou atribut.

Doba trvání v sekundách, po kterou modul čeká, než spustitelný soubor spustí proces, který naslouchá na portu. Pokud tento časový limit překročíte, modul proces ukončí.

Při hostování v procesu: Proces se nerestartuje a nepoužívá nastavení rapidFailsPerMinute.

Při hostování out-of-process: Modul se pokusí znovu spustit proces, když obdrží nový požadavek a pokračuje v pokusu o restartování procesu při následných příchozích požadavcích, pokud aplikace nespustí rychlý početfailsPerMinute v poslední klouzavé minutě.

Hodnota 0 (nula) se nepovažuje za nekonečný časový limit.

 Výchozí: 120
Min: 0
Max: 3600
stdoutLogEnabled

Volitelný logický atribut.

Pokud je hodnota true, stdout a stderr pro proces zadaný v processPath jsou přesměrovány na soubor zadaný v stdoutLogFile.

 false
stdoutLogFile

Volitelný atribut řetězce.

Určuje relativní nebo absolutní cestu k souboru, pro kterou jsou protokolovány stdout a stderr z procesu zadaného v processPath . Relativní cesty jsou relativní vzhledem ke kořenovému adresáři webu. Každá cesta začínající . na kořen webu je relativní a všechny ostatní cesty se považují za absolutní cesty. Všechny složky zadané v cestě vytvoří modul při vytvoření souboru protokolu. Pomocí oddělovačů podtržítka se přidá časové razítko, ID procesu a přípona souboru (.log) do posledního segmentu cesty stdoutLogFile . Pokud .\logs\stdout je zadána jako hodnota, příklad protokolu stdout je uložen jako stdout_20180205194132_1934.log ve logs složce při uložení 2. 5. 2018 v 19:41:32 s ID procesu 1934.

 aspnetcore-stdout

Nastavení proměnných prostředí

Proměnné prostředí lze zadat pro proces v atributu processPath . Zadejte proměnnou prostředí s <environmentVariable> podřízeným prvkem <environmentVariables> elementu kolekce. Proměnné prostředí nastavené v této části mají přednost před proměnnými systémového prostředí.

Následující příklad nastaví dvě proměnné prostředí v web.config. ASPNETCORE_ENVIRONMENT nakonfiguruje prostředí aplikace na Development. Vývojář může dočasně nastavit tuto hodnotu v web.config souboru, aby se při ladění výjimky aplikace načetla stránka výjimky vývojáře. CONFIG_DIR je příkladem uživatelem definované proměnné prostředí, kde vývojář napsal kód, který čte hodnotu při spuštění, aby vytvořil cestu pro načtení konfiguračního souboru aplikace.

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

Poznámka

Alternativou k nastavení prostředí přímo v web.config je zahrnutí <EnvironmentName> vlastnosti do profilu publikování (.pubxml) nebo souboru projektu. Tento přístup nastaví prostředí při web.config publikování projektu:

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

Upozornění

Proměnnou ASPNETCORE_ENVIRONMENT prostředí nastavte jenom na Development přípravných a testovacích serverech, které nejsou přístupné nedůvěryhodným sítím, jako je například internet.

app_offline.htm

Pokud se v kořenovém adresáři aplikace zjistí soubor s názvem app_offline.htm , pokusí se ASP.NET Core Module aplikaci řádně vypnout a zastavit zpracování příchozích požadavků. Pokud aplikace stále běží po počtu sekund definovaných v shutdownTimeLimitmodulu ASP.NET Core proces spuštění ukonče.

V době, kdy app_offline.htm je soubor k dispozici, ASP.NET Core Module reaguje na požadavky odesláním obsahu app_offline.htm souboru. app_offline.htm Když se soubor odebere, spustí se další požadavek.

Pokud používáte model hostování mimo proces, nemusí se aplikace okamžitě vypnout, pokud existuje otevřené připojení. Například připojení Protokolu WebSocket může zpozdit vypnutí aplikace.

Úvodní chybová stránka

Hostování v procesu i mimo proces vytváří vlastní chybové stránky, když se jim nedaří spustit aplikaci.

Pokud základní modul ASP.NET nenajde obslužnou rutinu požadavku v procesu nebo mimo proces, zobrazí se stránka se stavovým kódem selhání načtení obslužné rutiny 500.0 – In Process/Out-Of-Process Handler.

Pro hostování v procesu, pokud se ASP.NET core modulu nepodaří spustit aplikaci, zobrazí se stránka se stavovým kódem chyby 500.30.

Pro hostování mimo proces, pokud se ASP.NET core module nepodaří spustit back-endový proces nebo se spustí back-endový proces, ale nenaslouchá na nakonfigurovaný port, zobrazí se stránka se stavovým kódem selhání procesu 502.5.

Chcete-li tuto stránku potlačit a vrátit se na výchozí stavovou stránku služby IIS 5xx, použijte disableStartUpErrorPage atribut. Další informace o konfiguraci vlastních chybových zpráv naleznete v tématu Chyby <httpErrors>HTTP .

Vytvoření a přesměrování protokolu

Modul ASP.NET Core přesměruje výstup konzoly stdout a stderr na disk, pokud stdoutLogEnabled jsou nastaveny atributy stdoutLogFile elementu aspNetCore . Všechny složky v cestě stdoutLogFile vytvoří modul při vytvoření souboru protokolu. Fond aplikací musí mít přístup k zápisu do umístění, kde se protokoly zapisují (slouží IIS AppPool\<app_pool_name> k poskytnutí oprávnění k zápisu).

Protokoly se nestřídají, pokud nedojde k recyklaci nebo restartování procesu. Je zodpovědností hostitele omezit místo na disku, které protokoly spotřebovávají.

Použití protokolu stdout se doporučuje pouze při řešení potíží se spuštěním aplikace při hostování ve službě IIS nebo při použití podpory doby vývoje pro službu IIS se sadou Visual Studio, nikoli při místním ladění a spuštění aplikace pomocí služby IIS Express.

Nepoužívejte protokol stdout pro obecné účely protokolování aplikace. Pro rutinní protokolování v aplikaci ASP.NET Core použijte knihovnu protokolování, která omezuje velikost souboru protokolu a obměňuje protokoly. Další informace najdete v tématu Zprostředkovatelé protokolování třetích stran.

Při vytváření souboru protokolu se automaticky přidají časové razítko a přípona souboru. Název souboru protokolu se skládá připojením časového razítka, ID procesu a přípony souboru (.log) k poslednímu stdoutLogFile segmentu cesty (obvykle stdout) odděleného podtržítky. Pokud cesta stdoutLogFile končí stdout, protokol aplikace s PID 1934 vytvořený 2. 5. 2018 v 19:42:32 má název stdout_20180205194132_1934.logsouboru .

Pokud stdoutLogEnabled je false, chyby, ke kterým dochází při spuštění aplikace, se zachytí a vygenerují do protokolu událostí až do 30 kB. Po spuštění se všechny další protokoly zahodí.

Následující ukázkový aspNetCore element nakonfiguruje protokolování stdout v relativní cestě .\log\. Ověřte, že identita uživatele AppPool má oprávnění k zápisu do zadané cesty.

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

Při publikování aplikace pro nasazení služby Aplikace Azure Service nastaví stdoutLogFile webová sada SDK hodnotu na \\?\%home%\LogFiles\stdouthodnotu . Proměnná %home prostředí je předdefinovaná pro aplikace hostované službou Aplikace Azure Service.

Pokud chcete vytvořit pravidla filtru protokolování, přečtěte si část Kód pravidla filtru protokolu v dokumentaci k protokolování ASP.NET Core.

Další informace o formátech cest naleznete v tématu Formáty cesty k souborům v systémech Windows.

Rozšířené diagnostické protokoly

Modul ASP.NET Core je konfigurovatelný tak, aby poskytoval rozšířené diagnostické protokoly. <handlerSettings> Přidejte prvek do elementu <aspNetCore> v souboru web.config. debugLevel Nastavení pro TRACE zveřejnění vyšší přesnosti diagnostických informací:

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

Všechny složky v cestě (logs v předchozím příkladu) vytvoří modul při vytvoření souboru protokolu. Fond aplikací musí mít přístup k zápisu do umístění, kde se protokoly zapisují (pro poskytnutí oprávnění k zápisu použijte IIS AppPool\{APP POOL NAME}zástupný symbol {APP POOL NAME} název fondu aplikací).

Hodnoty úrovnědebugLevel ladění můžou zahrnovat úroveň i umístění.

Úrovně (v pořadí od nejméně po většinu podrobných):

  • CHYBA
  • UPOZORNĚNÍ
  • INFO
  • TRACE

Umístění (je povoleno více umístění):

  • KONZOLA
  • EVENTLOG
  • SOUBOR

Nastavení obslužné rutiny lze také poskytnout prostřednictvím proměnných prostředí:

  • ASPNETCORE_MODULE_DEBUG_FILE: Cesta k souboru protokolu ladění. (Výchozí: aspnetcore-debug.log)
  • ASPNETCORE_MODULE_DEBUG: Nastavení na úrovni ladění.

Upozornění

Nezanechujte protokolování ladění povolené v nasazení déle, než je nutné k řešení potíží. Velikost protokolu není omezená. Ponechání povoleného protokolu ladění může vyčerpat dostupné místo na disku a dojít k chybě serveru nebo služby App Service.

Příklad web.config.

Úprava velikosti zásobníku

Platí pouze při použití modelu hostování v procesu.

Nakonfigurujte velikost spravovaného zásobníku stackSize pomocí nastavení v bajtech v web.configobjektu . Výchozí velikost je 1 048 576 bajtů (1 MB).

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

Konfigurace proxy serveru používá protokol HTTP a párovací token.

Týká se pouze hostování mimo proces.

Proxy server vytvořený mezi modulem ASP.NET Core a Kestrel používá protokol HTTP. Neexistuje žádné riziko odposlouchávání provozu mezi modulem a Kestrel z umístění mimo server.

Párovací token se používá k zajištění toho, že žádosti přijaté službou Kestrel IIS byly zasílané službou IIS a nepřišly z jiného zdroje. Token párování se vytvoří a nastaví do proměnné prostředí (ASPNETCORE_TOKEN) modulu. Token párování se také nastaví do hlavičky (MS-ASPNETCORE-TOKEN) pro každý požadavek naxied. Middleware služby IIS kontroluje každý požadavek, který obdrží, a ověří, že hodnota hlavičky spárujícího tokenu odpovídá hodnotě proměnné prostředí. Pokud se hodnoty tokenu neshodují, požadavek se zaprotokoluje a odmítne. Proměnná prostředí párovacího tokenu a provoz mezi modulem a Kestrel nejsou přístupné z umístění mimo server. Bez znalosti hodnoty párového tokenu nemůže cyberattacker odesílat žádosti, které obcházejí kontrolu v middlewaru služby IIS.

základní modul ASP.NET se sdílenou konfigurací služby IIS

Instalační program ASP.NET Core Module běží s oprávněními účtu TrustedInstaller . Vzhledem k tomu, že místní systémový účet nemá oprávnění ke změně cesty ke sdílené složce používané sdílenou konfigurací služby IIS, vyvolá instalační program chybu odepření přístupu při pokusu o konfiguraci nastavení modulu v applicationHost.config souboru ve sdílené složce.

Pokud používáte sdílenou konfiguraci služby IIS na stejném počítači jako instalace služby IIS, spusťte instalační program sady ASP.NET Core Hosting Bundle s parametrem nastaveným OPT_NO_SHARED_CONFIG_CHECK na 1:

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

Pokud cesta ke sdílené konfiguraci není na stejném počítači jako instalace služby IIS, postupujte takto:

  1. Zakažte sdílenou konfiguraci služby IIS.
  2. Spusťte instalační program.
  3. Export aktualizovaného applicationHost.config souboru do sdílené složky
  4. Znovu povolte sdílenou konfiguraci služby IIS.

Protokoly instalačního programu modulu a hostitelské sady

Určení verze nainstalovaného modulu ASP.NET Core:

  1. V hostitelském systému přejděte na %windir%\System32\inetsrv.
  2. aspnetcore.dll Vyhledejte soubor.
  3. Klikněte pravým tlačítkem myši na soubor a v místní nabídce vyberte Vlastnosti .
  4. Vyberte kartu Podrobnosti. Verze souboru a verze produktu představují nainstalovanou verzi modulu.

Protokoly instalačního programu sady hostingu pro modul najdete na adrese C:\Users\%UserName%\AppData\Local\Temp. Soubor má název dd_DotNetCoreWinSvrHosting__{TIMESTAMP}_000_AspNetCoreModule_x64.log.

Umístění modulů, schémat a konfiguračních souborů

Modul

IIS (x86/amd64):

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

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

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

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

IIS Express (x86/amd64):

  • %ProgramFiles%\IIS Express\aspnetcore.dll

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

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

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

Schéma

IIS

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

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

IIS Express

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

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

Konfigurace

IIS

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

IIS Express

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

  • rozhraní příkazového řádku iisexpress.exe:%USERPROFILE%\Documents\IISExpress\config\applicationhost.config

Soubory najdete vyhledáním aspnetcore v applicationHost.config souboru.

Modul ASP.NET Core (ANCM) je nativní modul SLUŽBY IIS, který se připojuje ke kanálu služby IIS a umožňuje:

  • Hostování aplikace ASP.NET Core uvnitř pracovního procesu služby IIS (w3wp.exeoznačovaného jako model hostování v procesu).
  • Přesměrovávat webové požadavky do back-endové aplikace ASP.NET Core, na Kestrel které běží server, označovaný jako model hostování mimo proces.

Podporované verze Windows:

  • Windows 7 nebo novější
  • Windows Server 2008 R2 nebo novější

Při hostování v procesu modul používá implementaci procesového serveru pro službu IIS s názvem IIS HTTP Server (IISHttpServer).

Při hostování out-of-process, modul funguje pouze s Kestrel. Modul nefunguje s HTTP.sys.

Modely hostingu

Model vnitroprocesového hostování

Pokud chcete nakonfigurovat aplikaci pro hostování v procesu, přidejte <AspNetCoreHostingModel> vlastnost do souboru projektu aplikace s hodnotou InProcess (hostování mimo proces je nastaveno OutOfProcess):

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

Model hostování v procesu není podporován pro aplikace ASP.NET Core, které cílí na rozhraní .NET Framework.

Hodnota <AspNetCoreHostingModel> nerozlišuje malá a velká písmena, takže inprocess jsou outofprocess platné hodnoty.

Pokud vlastnost <AspNetCoreHostingModel> není v souboru, výchozí hodnota je OutOfProcess.

Při hostování v procesu platí následující charakteristiky:

  • Server HTTP služby IIS (IISHttpServer) se používá místo Kestrel serveru. V případě in-process, CreateDefaultBuilder volání UseIIS do:

    • Zaregistrujte .IISHttpServer
    • Nakonfigurujte port a základní cestu, na které by měl server naslouchat při spuštění za modulem ASP.NET Core.
    • Nakonfigurujte hostitele tak, aby zachytil chyby při spuštění.

  • Atribut requestTimeout se nevztahuje na hostování v procesu.

  • Sdílení fondu aplikací mezi aplikacemi se nepodporuje. Pro každou aplikaci použijte jeden fond aplikací.

  • Pokud používáte nasazení webu nebo ručně umístíte soubor app_offline.htm do nasazení, nemusí se aplikace okamžitě vypnout, pokud existuje otevřené připojení. Například připojení protokolu websocket může zpozdit vypnutí aplikace.

  • Architektura (bitová verze) aplikace a nainstalovaného modulu runtime (x64 nebo x86) musí odpovídat architektuře fondu aplikací.

  • Zjistí se odpojení klienta. Token zrušení HttpContext.RequestAborted se zruší, když se klient odpojí.

  • V ASP.NET Core 2.2.1 nebo starší GetCurrentDirectory vrátí pracovní adresář procesu spuštěného službou IIS místo adresáře aplikace (například C:\Windows\System32\inetsrv pro w3wp.exe).

    Vzorový kód, který nastaví aktuální adresář aplikace, naleznete v CurrentDirectoryHelpers třída. Zavolejte metodu SetCurrentDirectory . Následná volání pro GetCurrentDirectory poskytnutí adresáře aplikace.

  • Při hostování v procesu se nevolá interně za AuthenticateAsync účelem inicializace uživatele. Proto se implementace použitá IClaimsTransformation k transformaci deklarací identity po každém ověření ve výchozím nastavení neaktivuje. Při transformaci deklarací identity pomocí IClaimsTransformation implementace volání AddAuthentication pro přidání ověřovacích služeb:

    C# 
    public void ConfigureServices(IServiceCollection services)
{
    services.AddTransient<IClaimsTransformation, ClaimsTransformer>();
    services.AddAuthentication(IISServerDefaults.AuthenticationScheme);
}

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

Model mimoprocesového hostování

Pokud chcete nakonfigurovat aplikaci pro hostování mimo proces, použijte v souboru projektu některý z následujících přístupů:

  • Nezadávejte <AspNetCoreHostingModel> vlastnost. Pokud vlastnost <AspNetCoreHostingModel> není v souboru, výchozí hodnota je OutOfProcess.
  • Nastavte hodnotu <AspNetCoreHostingModel> vlastnosti na OutOfProcess (hostování v procesu je nastaveno pomocí InProcess):
XML 
<PropertyGroup>
  <AspNetCoreHostingModel>OutOfProcess</AspNetCoreHostingModel>
</PropertyGroup>

Hodnota nerozlišuje malá a velká písmena, takže inprocess jsou outofprocess platné hodnoty.

Kestrel server se používá místo serveru HTTP služby IIS (IISHttpServer).

V případě out-of-process CreateDefaultBuilder volání UseIISIntegration do:

  • Nakonfigurujte port a základní cestu, na které by měl server naslouchat při spuštění za modulem ASP.NET Core.
  • Nakonfigurujte hostitele tak, aby zachytil chyby při spuštění.

Změny modelu hostování

hostingModel Pokud je nastavení změněno v souboru web.config (vysvětleno v části Konfigurace s web.config), modul recykluje pracovní proces pro službu IIS.

V případě služby IIS Express modul nerecykluje pracovní proces, ale místo toho aktivuje řádné vypnutí aktuálního procesu SLUŽBY IIS Express. Další požadavek aplikace vytvoří nový proces SLUŽBY IIS Express.

Název procesu

Process.GetCurrentProcess().ProcessName sestav w3wp/iisexpress (v procesu) nebo dotnet (mimo proces).

Mnoho nativních modulů, jako je ověřování systému Windows, zůstává aktivních. Další informace o modulech SLUŽBY IIS, které jsou aktivní s modulem ASP.NET Core, najdete v tématu Moduly IIS s ASP.NET Core.

Základní modul ASP.NET může také:

  • Nastavte proměnné prostředí pro pracovní proces.
  • Výstup protokolu stdout do úložiště souborů pro řešení potíží se spuštěním
  • Předávat ověřovací tokeny Systému Windows

Jak nainstalovat a používat modul ASP.NET Core (ANCM)

Pokyny k instalaci modulu ASP.NET Core najdete v tématu Instalace sady hostingu .NET Core. Modul ASP.NET Core je dopředu a zpětně kompatibilní s verzemi v rámci podpory rozhraní .NET.

V úložišti Oznámení se zobrazují zásadní změny a informační zpravodaje zabezpečení. Oznámení můžou být omezena na konkrétní verzi výběrem filtru Popisek .

Konfigurace pomocí web.config

Modul ASP.NET Core je nakonfigurovaný s aspNetCore částí system.webServer uzlu v souboru web.config webu.

Následující soubor web.config je publikovaný pro nasazení závislé na rozhraní a nakonfiguruje modul ASP.NET Core pro zpracování požadavků webu:

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

Následující soubor web.config se publikuje pro samostatné nasazení:

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

Vlastnost InheritInChildApplications je nastavena tak, aby false indikovala, že nastavení zadaná v elementu <location> nejsou zděděna aplikacemi, které se nacházejí v podadresáři aplikace.

Když je aplikace nasazená do služby Aplikace Azure Service, je cesta nastavená stdoutLogFile na \\?\%home%\LogFiles\stdout. Cesta ukládá protokoly stdout do složky LogFiles , což je umístění automaticky vytvořené službou.

Informace o konfiguraci dílčí aplikace služby IIS naleznete v tématu Hostitel ASP.NET Core ve Windows se službou IIS.

Atributy elementu aspNetCore

Atribut Popis Výchozí
arguments

Volitelný atribut řetězce.

Argumenty spustitelnému souboru zadanému v processPath.
disableStartUpErrorPage

Volitelný logický atribut.

Pokud je pravda, stránka 502.5 – Selhání procesu je potlačena a stránka stavového kódu 502 nakonfigurovaná v souboru web.config má přednost.

 false
forwardWindowsAuthToken

Volitelný logický atribut.

Pokud je hodnota true, token se předá do podřízeného procesu, který naslouchá %ASPNETCORE_PORT% jako hlavička MS-ASPNETCORE-WINAUTHTOKEN na požadavek. Za volání CloseHandle na tento token na žádost zodpovídá tento proces.

 true
hostingModel

Volitelný atribut řetězce.

Určuje model hostování jako in-process (InProcess/inprocess) nebo out-of-process ().OutOfProcess/outofprocess

 OutOfProcess
outofprocess
processesPerApplication

Volitelný celočíselnou atribut.

Určuje počet instancí procesu zadaných v processPath nastavení, které se dá pro každou aplikaci spustit.

†Na hostování v procesu je hodnota omezena na 1.

Nastavení processesPerApplication se nedoporučuje. Tento atribut bude odebrán v budoucí verzi.

 Výchozí: 1
Min: 1
Max: 100†
processPath

Povinný atribut řetězce.

Cesta ke spustitelnému souboru, který spouští proces, který naslouchá požadavkům HTTP. Podporují se relativní cesty. Pokud cesta začíná ., cesta se považuje za relativní vzhledem ke kořenovému adresáři webu.
rapidFailsPerMinute

Volitelný celočíselnou atribut.

Určuje počet povolených chybových ukončení procesu processPath za minutu. Pokud tento limit překročíte, modul po zbytek minuty zastaví spuštění procesu.

Nepodporuje se hostování v procesu.

 Výchozí: 10
Min: 0
Max: 100
requestTimeout

Volitelný atribut časového rozsahu

Určuje dobu, po kterou ASP.NET základní modul čeká na odpověď z procesu, na kterém naslouchá %ASPNETCORE_PORT%.

Ve verzích modulu ASP.NET Core, který se dodává s vydáním verze ASP.NET Core 2.1 nebo novější, requestTimeout se zadává v hodinách, minutách a sekundách.

Nevztahuje se na hostování v procesu. V případě hostování v procesu modul čeká, až aplikace zpracuje požadavek.

Platné hodnoty pro minuty a sekundy řetězce jsou v rozsahu 0–59. Výsledkem použití 60 v hodnotě minut nebo sekund je 500 – vnitřní chyba serveru.

 Výchozí: 00:02:00
Min: 00:00:00
Max: 360:00:00
shutdownTimeLimit

Volitelný celočíselnou atribut.

Doba trvání v sekundách, po kterou modul čeká na řádné vypnutí spustitelného app_offline.htm souboru při zjištění souboru.

 Výchozí: 10
Min: 0
Max: 600
startupTimeLimit

Volitelný celočíselnou atribut.

Doba trvání v sekundách, po kterou modul čeká, než spustitelný soubor spustí proces, který naslouchá na portu. Pokud tento časový limit překročíte, modul proces ukončí.

Při hostování v procesu: Proces se nerestartuje a toto nastavení nepoužívá rapidFailsPerMinute .

Při hostování out-of-process: Modul se pokusí znovu spustit proces, když obdrží nový požadavek, a pokračuje v pokusu o restartování procesu u následných příchozích požadavků, pokud se aplikaci nepodaří spustit rapidFailsPerMinute početkrát za poslední klouzavý minutu.

Hodnota 0 (nula) se nepovažuje za nekonečný časový limit.

 Výchozí: 120
Min: 0
Max: 3600
stdoutLogEnabled

Volitelný logický atribut.

Pokud je hodnota true, příkazy stdout a stderr pro proces zadaný v processPath souboru jsou přesměrovány na soubor zadaný v souboru stdoutLogFile.

 false
stdoutLogFile

Volitelný atribut řetězce.

Určuje relativní nebo absolutní cestu k souboru, pro kterou stdout a stderr z procesu zadaného v processPath protokolu. Relativní cesty jsou relativní vzhledem ke kořenovému adresáři webu. Každá cesta začínající . na kořen webu je relativní a všechny ostatní cesty se považují za absolutní cesty. Všechny složky zadané v cestě vytvoří modul při vytvoření souboru protokolu. Použití oddělovačů podtržítka, časového razítka, ID procesu a přípony souboru (.log) se přidají do posledního stdoutLogFile segmentu cesty. Pokud .\logs\stdout je zadána jako hodnota, příklad protokolu stdout je uložen jako stdout_20180205194132_1934.log ve logs složce při uložení 2. 5. 2018 v 19:41:32 s ID procesu 1934.

 aspnetcore-stdout

Nastavení proměnných prostředí

Proměnné prostředí lze zadat pro proces v atributu processPath . Zadejte proměnnou prostředí s <environmentVariable> podřízeným prvkem <environmentVariables> elementu kolekce. Proměnné prostředí nastavené v této části mají přednost před proměnnými systémového prostředí.

Následující příklad nastaví dvě proměnné prostředí. ASPNETCORE_ENVIRONMENT nakonfiguruje prostředí aplikace na Development. Vývojář může dočasně nastavit tuto hodnotu v web.config souboru, aby se při ladění výjimky aplikace načetla stránka výjimky vývojáře. CONFIG_DIR je příkladem uživatelem definované proměnné prostředí, kde vývojář napsal kód, který čte hodnotu při spuštění, aby vytvořil cestu pro načtení konfiguračního souboru aplikace.

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

Poznámka

Alternativou k nastavení prostředí přímo v web.config je zahrnutí <EnvironmentName> vlastnosti do profilu publikování (.pubxml) nebo souboru projektu. Tento přístup nastaví prostředí při web.config publikování projektu:

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

Upozornění

Proměnnou ASPNETCORE_ENVIRONMENT prostředí nastavte jenom na Development přípravných a testovacích serverech, které nejsou přístupné nedůvěryhodným sítím, jako je například internet.

app_offline.htm

Pokud se v kořenovém adresáři aplikace zjistí soubor s názvem app_offline.htm , pokusí se ASP.NET Core Module aplikaci řádně vypnout a zastavit zpracování příchozích požadavků. Pokud aplikace stále běží po počtu sekund definovaných v shutdownTimeLimitmodulu ASP.NET Core proces spuštění ukonče.

V době, kdy app_offline.htm je soubor k dispozici, ASP.NET Core Module reaguje na požadavky odesláním obsahu app_offline.htm souboru. app_offline.htm Když se soubor odebere, spustí se další požadavek.

Pokud používáte model hostování mimo proces, nemusí se aplikace okamžitě vypnout, pokud existuje otevřené připojení. Například připojení protokolu websocket může zpozdit vypnutí aplikace.

Úvodní chybová stránka

Hostování v procesu i mimo proces vytváří vlastní chybové stránky, když se jim nedaří spustit aplikaci.

Pokud základní modul ASP.NET nenajde obslužnou rutinu požadavku v procesu nebo mimo proces, zobrazí se stránka se stavovým kódem selhání načtení obslužné rutiny 500.0 – In Process/Out-Of-Process Handler.

Pro hostování v procesu, pokud se ASP.NET core modulu nepodaří spustit aplikaci, zobrazí se stránka se stavovým kódem chyby 500.30.

Pro hostování mimo proces, pokud se ASP.NET core module nepodaří spustit back-endový proces nebo se spustí back-endový proces, ale nenaslouchá na nakonfigurovaný port, zobrazí se stránka se stavovým kódem selhání procesu 502.5.

Chcete-li tuto stránku potlačit a vrátit se na výchozí stavovou stránku služby IIS 5xx, použijte disableStartUpErrorPage atribut. Další informace o konfiguraci vlastních chybových zpráv naleznete v tématu Chyby HTTP httpErrors<>.

Vytvoření a přesměrování protokolu

Modul ASP.NET Core přesměruje výstup konzoly stdout a stderr na disk, pokud stdoutLogEnabled jsou nastaveny atributy stdoutLogFile elementu aspNetCore . Všechny složky v cestě stdoutLogFile vytvoří modul při vytvoření souboru protokolu. Fond aplikací musí mít přístup k zápisu do umístění, kde se protokoly zapisují (slouží IIS AppPool\{APP POOL NAME} k poskytnutí oprávnění k zápisu, kde zástupný symbol {APP POOL NAME} je název fondu aplikací).

Protokoly se nestřídají, pokud nedojde k recyklaci nebo restartování procesu. Je zodpovědností hostitele omezit místo na disku, které protokoly spotřebovávají.

Použití protokolu stdout se doporučuje pouze při řešení potíží se spuštěním aplikace při hostování ve službě IIS nebo při použití podpory doby vývoje pro službu IIS se sadou Visual Studio, nikoli při místním ladění a spuštění aplikace pomocí služby IIS Express.

Nepoužívejte protokol stdout pro obecné účely protokolování aplikace. Pro rutinní protokolování v aplikaci ASP.NET Core použijte knihovnu protokolování, která omezuje velikost souboru protokolu a obměňuje protokoly. Další informace najdete v tématu Zprostředkovatelé protokolování třetích stran.

Při vytváření souboru protokolu se automaticky přidají časové razítko a přípona souboru. Název souboru protokolu se skládá připojením časového razítka, ID procesu a přípony souboru (.log) k poslednímu stdoutLogFile segmentu cesty (obvykle stdout) odděleného podtržítky. Pokud cesta stdoutLogFile končí stdout, protokol aplikace s PID 1934 vytvořený 2. 5. 2018 v 19:42:32 má název stdout_20180205194132_1934.logsouboru .

Pokud stdoutLogEnabled je false, chyby, ke kterým dochází při spuštění aplikace, se zachytí a vygenerují do protokolu událostí až do 30 kB. Po spuštění se všechny další protokoly zahodí.

Následující ukázkový aspNetCore element nakonfiguruje protokolování stdout v relativní cestě .\log\. Ověřte, že identita uživatele fondu aplikací má oprávnění k zápisu do zadané cesty.

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

Při publikování aplikace pro nasazení služby Aplikace Azure Service nastaví stdoutLogFile webová sada SDK hodnotu na \\?\%home%\LogFiles\stdouthodnotu . Proměnná %home prostředí je předdefinovaná pro aplikace hostované službou Aplikace Azure Service.

Další informace o formátech cest naleznete v tématu Formáty cesty k souborům v systémech Windows.

Rozšířené diagnostické protokoly

Modul ASP.NET Core je konfigurovatelný tak, aby poskytoval rozšířené diagnostické protokoly. <handlerSettings> Přidejte prvek do elementu <aspNetCore> v souboru web.config. debugLevel Nastavení pro TRACE zveřejnění vyšší přesnosti diagnostických informací:

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

Složky v cestě zadané hodnotě <handlerSetting> (logs v předchozím příkladu) modul automaticky nevytvořil a měl by v nasazení předem existovat. Fond aplikací musí mít přístup k zápisu do umístění, kde se protokoly zapisují (slouží IIS AppPool\{APP POOL NAME} k poskytnutí oprávnění k zápisu, kde zástupný symbol {APP POOL NAME} je název fondu aplikací).

Hodnoty úrovnědebugLevel ladění můžou zahrnovat úroveň i umístění.

Úrovně (v pořadí od nejméně po většinu podrobných):

  • CHYBA
  • UPOZORNĚNÍ
  • INFO
  • TRACE

Umístění (je povoleno více umístění):

  • KONZOLA
  • EVENTLOG
  • SOUBOR

Nastavení obslužné rutiny lze také poskytnout prostřednictvím proměnných prostředí:

  • ASPNETCORE_MODULE_DEBUG_FILE: Cesta k souboru protokolu ladění. (Výchozí: aspnetcore-debug.log)
  • ASPNETCORE_MODULE_DEBUG: Nastavení na úrovni ladění.

Upozornění

Nezanechujte protokolování ladění povolené v nasazení déle, než je nutné k řešení potíží. Velikost protokolu není omezená. Ponechání povoleného protokolu ladění může vyčerpat dostupné místo na disku a dojít k chybě serveru nebo služby App Service.

Příklad web.config.

Konfigurace proxy serveru používá protokol HTTP a párovací token.

Týká se pouze hostování mimo proces.

Proxy server vytvořený mezi modulem ASP.NET Core a Kestrel používá protokol HTTP. Neexistuje žádné riziko odposlouchávání provozu mezi modulem a Kestrel z umístění mimo server.

Párovací token se používá k zajištění toho, že žádosti přijaté službou Kestrel IIS byly zasílané službou IIS a nepřišly z jiného zdroje. Token párování se vytvoří a nastaví do proměnné prostředí (ASPNETCORE_TOKEN) modulu. Token párování se také nastaví do hlavičky (MS-ASPNETCORE-TOKEN) pro každý požadavek naxied. Middleware služby IIS kontroluje každý požadavek, který obdrží, a ověří, že hodnota hlavičky spárujícího tokenu odpovídá hodnotě proměnné prostředí. Pokud se hodnoty tokenu neshodují, požadavek se zaprotokoluje a odmítne. Proměnná prostředí párovacího tokenu a provoz mezi modulem a Kestrel nejsou přístupné z umístění mimo server. Bez znalosti hodnoty párového tokenu nemůže cyberattacker odesílat žádosti, které obcházejí kontrolu v middlewaru služby IIS.

základní modul ASP.NET se sdílenou konfigurací služby IIS

Instalační program základního TrustedInstaller modulu ASP.NET běží s oprávněními účtu. Vzhledem k tomu, že místní systémový účet nemá oprávnění ke změně cesty ke sdílené složce používané sdílenou konfigurací služby IIS, vyvolá instalační program chybu odepření přístupu při pokusu o konfiguraci nastavení modulu v applicationHost.config souboru ve sdílené složce.

Pokud používáte sdílenou konfiguraci služby IIS na stejném počítači jako instalace služby IIS, spusťte instalační program sady ASP.NET Core Hosting Bundle s parametrem nastaveným OPT_NO_SHARED_CONFIG_CHECK na 1:

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

Pokud cesta ke sdílené konfiguraci není na stejném počítači jako instalace služby IIS, postupujte takto:

  1. Zakažte sdílenou konfiguraci služby IIS.
  2. Spusťte instalační program.
  3. Export aktualizovaného applicationHost.config souboru do sdílené složky
  4. Znovu povolte sdílenou konfiguraci služby IIS.

Protokoly instalačního programu modulu a hostitelské sady

Určení verze nainstalovaného modulu ASP.NET Core:

  1. V hostitelském systému přejděte na %windir%\System32\inetsrv.
  2. aspnetcore.dll Vyhledejte soubor.
  3. Klikněte pravým tlačítkem myši na soubor a v místní nabídce vyberte Vlastnosti .
  4. Vyberte kartu Podrobnosti. Verze souboru a verze produktu představují nainstalovanou verzi modulu.

Protokoly instalačního programu sady hostingu pro modul najdete na adrese C:\\Users\\%UserName%\\AppData\\Local\\Temp. Soubor má název dd_DotNetCoreWinSvrHosting__\{TIMESTAMP}_000_AspNetCoreModule_x64.log, kde zástupný symbol {TIMESTAMP} představuje časové razítko.

Umístění modulů, schémat a konfiguračních souborů

Modul

IIS (x86/amd64):

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

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

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

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

IIS Express (x86/amd64):

  • %ProgramFiles%\IIS Express\aspnetcore.dll

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

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

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

Schéma

IIS

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

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

IIS Express

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

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

Konfigurace

IIS

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

IIS Express

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

  • rozhraní příkazového řádku iisexpress.exe:%USERPROFILE%\Documents\IISExpress\config\applicationhost.config

Soubory najdete vyhledáním aspnetcore v applicationHost.config souboru.

Modul ASP.NET Core (ANCM) je nativní modul SLUŽBY IIS, který se připojuje ke kanálu SLUŽBY IIS a předává webové požadavky do back-endových aplikací ASP.NET Core.

Podporované verze Windows:

  • Windows 7 nebo novější
  • Windows Server 2008 R2 nebo novější

Modul funguje pouze s Kestrel. Modul není kompatibilní s HTTP.sys.

Vzhledem k tomu, že ASP.NET aplikace Core běží v procesu odděleně od pracovního procesu služby IIS, modul také zpracovává správu procesů. Modul spustí proces aplikace ASP.NET Core, když přijde první požadavek a restartuje aplikaci, pokud dojde k chybě. To je v podstatě stejné chování jako u aplikací ASP.NET 4.x, které běží v procesu ve službě IIS spravované službou aktivace procesu systému Windows (WAS).

Následující diagram znázorňuje vztah mezi službou IIS, modulem ASP.NET Core a aplikací:

Modul ASP.NET Core

Požadavky přijdou z webu do ovladače HTTP.sys v režimu jádra. Ovladač přesměruje požadavek do služby IIS na nakonfigurovaném portu webu, obvykle 80 (HTTP) nebo 443 (HTTPS). Modul předá požadavky na server Kestrel na náhodném portu dané aplikace mimo porty 80 a 443.

Modul tento port určí při spuštění prostřednictvím proměnné prostředí a middleware IIS Integration nakonfiguruje server tak, aby naslouchal na adrese http://localhost:{port}. Provedou se další kontroly a požadavky, které nepocházejí z tohoto modulu, se zamítnou. Modul nepodporuje předávání HTTPS, takže se požadavky předávají přes HTTP, i když je služba IIS přijme přes HTTPS.

Jakmile server Kestrel přijme požadavek z modulu, požadavek se odešle do kanálu middlewaru ASP.NET Core. Kanál middlewaru požadavek zpracuje a předá ho jako instanci HttpContext do logiky aplikace. Middleware přidaný integrací služby IIS aktualizuje schéma, vzdálenou IP adresu a základ cesty k účtu pro přesměrování požadavku na server Kestrel. Odpověď aplikace se předá zpět do služby IIS, která ji odešle klientovi HTTP, který požadavek inicioval.

Mnoho nativních modulů, jako je ověřování systému Windows, zůstává aktivních. Další informace o modulech SLUŽBY IIS, které jsou aktivní s modulem ASP.NET Core, najdete v tématu Moduly IIS s ASP.NET Core.

Základní modul ASP.NET může také:

  • Nastavte proměnné prostředí pro pracovní proces.
  • Výstup protokolu stdout do úložiště souborů pro řešení potíží se spuštěním
  • Předávat ověřovací tokeny Systému Windows

Jak nainstalovat a používat modul ASP.NET Core (ANCM)

Pokyny k instalaci modulu ASP.NET Core najdete v tématu Instalace sady hostingu .NET Core.

Konfigurace pomocí web.config

Modul ASP.NET Core je nakonfigurovaný s aspNetCore částí system.webServer uzlu v souboru web.config webu.

Následující soubor web.config je publikovaný pro nasazení závislé na rozhraní a nakonfiguruje modul ASP.NET Core pro zpracování požadavků webu:

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

Následující soubor web.config se publikuje pro samostatné nasazení:

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

Když je aplikace nasazená do služby Aplikace Azure Service, je cesta nastavená stdoutLogFile na \\?\%home%\LogFiles\stdout. Cesta ukládá protokoly stdout do složky LogFiles , což je umístění automaticky vytvořené službou.

Informace o konfiguraci dílčí aplikace služby IIS naleznete v tématu Hostitel ASP.NET Core ve Windows se službou IIS.

Atributy elementu aspNetCore

Atribut Popis Výchozí
arguments

Volitelný atribut řetězce.

Argumenty spustitelného souboru zadaného v cestě processPath.
disableStartUpErrorPage

Volitelný logický atribut.

Pokud je pravda, stránka 502.5 – Selhání procesu je potlačena a stránka stavového kódu 502 nakonfigurovaná v souboru web.config má přednost.

 false
forwardWindowsAuthToken

Volitelný logický atribut.

Pokud je hodnota true, token se předá do podřízeného procesu, který naslouchá %ASPNETCORE_PORT% jako hlavička MS-ASPNETCORE-WINAUTHTOKEN na požadavek. Za volání CloseHandle na tento token na žádost zodpovídá tento proces.

 true
processesPerApplication

Volitelný celočíselnou atribut.

Určuje počet instancí procesu zadaného v nastavení processPath , které je možné pro každou aplikaci spustit.

Nastavení processesPerApplication se nedoporučuje. Tento atribut bude odebrán v budoucí verzi.

 Výchozí: 1
Min: 1
Max: 100
processPath

Povinný atribut řetězce.

Cesta ke spustitelnému souboru, který spouští proces, který naslouchá požadavkům HTTP. Podporují se relativní cesty. Pokud cesta začíná ., cesta se považuje za relativní vzhledem ke kořenovému adresáři webu.
rapidFailsPerMinute

Volitelný celočíselnou atribut.

Určuje počet povolených chybových ukončení procesu zadaných v cestě processPath za minutu. Pokud tento limit překročíte, modul po zbytek minuty zastaví spuštění procesu.

 Výchozí: 10
Min: 0
Max: 100
requestTimeout

Volitelný atribut časového rozsahu

Určuje dobu, po kterou ASP.NET základní modul čeká na odpověď z procesu, na kterém naslouchá %ASPNETCORE_PORT%.

Ve verzích modulu ASP.NET Core, který se dodává s vydáním verze ASP.NET Core 2.1 nebo novější, requestTimeout se zadává v hodinách, minutách a sekundách.

 Výchozí: 00:02:00
Min: 00:00:00
Max: 360:00:00
shutdownTimeLimit

Volitelný celočíselnou atribut.

Doba trvání v sekundách, po kterou modul čeká na řádné vypnutí spustitelného app_offline.htm souboru při zjištění souboru.

 Výchozí: 10
Min: 0
Max: 600
startupTimeLimit

Volitelný celočíselnou atribut.

Doba trvání v sekundách, po kterou modul čeká, než spustitelný soubor spustí proces, který naslouchá na portu. Pokud tento časový limit překročíte, modul proces ukončí. Modul se pokusí znovu spustit proces, když obdrží nový požadavek, a pokračuje v pokusu o restartování procesu při následných příchozích požadavcích, pokud aplikace nespustí rychlý počet spuštěníFailsPerMinute v poslední klouzavé minutě.

Hodnota 0 (nula) se nepovažuje za nekonečný časový limit.

 Výchozí: 120
Min: 0
Max: 3600
stdoutLogEnabled

Volitelný logický atribut.

Pokud je hodnota true, stdout a stderr pro proces zadaný v processPath jsou přesměrovány na soubor zadaný v stdoutLogFile.

 false
stdoutLogFile

Volitelný atribut řetězce.

Určuje relativní nebo absolutní cestu k souboru, pro kterou jsou protokolovány stdout a stderr z procesu zadaného v processPath . Relativní cesty jsou relativní vzhledem ke kořenovému adresáři webu. Každá cesta začínající . na kořen webu je relativní a všechny ostatní cesty se považují za absolutní cesty. Aby modul mohl vytvořit soubor protokolu, musí existovat všechny složky zadané v cestě. Použití oddělovačů podtržítka, časového razítka, ID procesu a přípony souboru (.log) se přidají do posledního segmentu cesty stdoutLogFile . Pokud .\logs\stdout je zadána jako hodnota, příklad protokolu stdout je uložen jako stdout_20180205194132_1934.log ve složce protokolů při uložení 2. 5. 2018 v 19:41:32 s ID procesu 1934.

 aspnetcore-stdout

Nastavení proměnných prostředí

Proměnné prostředí lze zadat pro proces v atributu processPath . Zadejte proměnnou prostředí s <environmentVariable> podřízeným prvkem <environmentVariables> elementu kolekce.

Upozornění

Proměnné prostředí nastavené v této části jsou v konfliktu se systémovými proměnnými prostředí nastavenými se stejným názvem. Pokud je proměnná prostředí nastavená v souboru web.config i na úrovni systému ve Windows, připojí se hodnota ze souboru web.config k hodnotě proměnné systémového prostředí (například ASPNETCORE_ENVIRONMENT: Development;Development), která brání spuštění aplikace.

Následující příklad nastaví dvě proměnné prostředí. ASPNETCORE_ENVIRONMENT nakonfiguruje prostředí aplikace na Development. Vývojář může tuto hodnotu dočasně nastavit v souboru web.config , aby se při ladění výjimky aplikace načetla stránka výjimky vývojáře. CONFIG_DIR je příkladem uživatelem definované proměnné prostředí, kde vývojář napsal kód, který čte hodnotu při spuštění, aby vytvořil cestu pro načtení konfiguračního souboru aplikace.

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

Upozornění

Proměnnou ASPNETCORE_ENVIRONMENT prostředí nastavte jenom na Development přípravných a testovacích serverech, které nejsou přístupné nedůvěryhodným sítím, jako je například internet.

app_offline.htm

Pokud se v kořenovém adresáři aplikace zjistí soubor s názvem app_offline.htm , pokusí se ASP.NET Core Module aplikaci řádně vypnout a zastavit zpracování příchozích požadavků. Pokud aplikace stále běží po počtu sekund definovaných v shutdownTimeLimitmodulu ASP.NET Core proces spuštění ukonče.

V době, kdy app_offline.htm je soubor k dispozici, ASP.NET Core Module reaguje na požadavky odesláním obsahu app_offline.htm souboru. app_offline.htm Když se soubor odebere, spustí se další požadavek.

Úvodní chybová stránka

Pokud se ASP.NET core module nepodaří spustit proces back-endu nebo se spustí proces back-endu, ale na nakonfigurovaný port se nepodaří naslouchat, zobrazí se stránka se stavovým kódem selhání procesu 502.5. Chcete-li tuto stránku potlačit a vrátit se na výchozí stavovou stránku služby IIS 502, použijte disableStartUpErrorPage atribut. Další informace o konfiguraci vlastních chybových zpráv naleznete v tématu Chyby HTTP httpErrors<>.

Vytvoření a přesměrování protokolu

Modul ASP.NET Core přesměruje výstup konzoly stdout a stderr na disk, pokud stdoutLogEnabled jsou nastaveny atributy stdoutLogFile elementu aspNetCore . Všechny složky v cestě stdoutLogFile vytvoří modul při vytvoření souboru protokolu. Fond aplikací musí mít přístup k zápisu do umístění, kde se protokoly zapisují (slouží IIS AppPool\<app_pool_name> k poskytnutí oprávnění k zápisu).

Protokoly se nestřídají, pokud nedojde k recyklaci nebo restartování procesu. Je zodpovědností hostitele omezit místo na disku, které protokoly spotřebovávají.

Použití protokolu stdout se doporučuje pouze při řešení potíží se spuštěním aplikace při hostování ve službě IIS nebo při použití podpory doby vývoje pro službu IIS se sadou Visual Studio, nikoli při místním ladění a spuštění aplikace pomocí služby IIS Express.

Nepoužívejte protokol stdout pro obecné účely protokolování aplikace. Pro rutinní protokolování v aplikaci ASP.NET Core použijte knihovnu protokolování, která omezuje velikost souboru protokolu a obměňuje protokoly. Další informace najdete v tématu Zprostředkovatelé protokolování třetích stran.

Při vytváření souboru protokolu se automaticky přidají časové razítko a přípona souboru. Název souboru protokolu se skládá připojením časového razítka, ID procesu a přípony souboru (.log) k poslednímu stdoutLogFile segmentu cesty (obvykle stdout) odděleným podtržítky. stdoutLogFile Pokud cesta končí stdoutem, protokol aplikace s PID 1934 vytvořený 2. 5. 2018 v 19:42:32 má název souboru stdout_20180205194132_1934.log.

Následující ukázkový aspNetCore element nakonfiguruje protokolování stdout v relativní cestě .\log\. Ověřte, že identita uživatele AppPool má oprávnění k zápisu do zadané cesty.

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

Při publikování aplikace pro nasazení služby Aplikace Azure Service nastaví stdoutLogFile webová sada SDK hodnotu na \\?\%home%\LogFiles\stdouthodnotu . Proměnná %home prostředí je předdefinovaná pro aplikace hostované službou Aplikace Azure Service.

Pokud chcete vytvořit pravidla filtru protokolování, přečtěte si část Kód pravidla filtru protokolu v dokumentaci k protokolování ASP.NET Core.

Další informace o formátech cest naleznete v tématu Formáty cesty k souborům v systémech Windows.

Konfigurace proxy serveru používá protokol HTTP a párovací token.

Proxy server vytvořený mezi modulem ASP.NET Core a Kestrel používá protokol HTTP. Neexistuje žádné riziko odposlouchávání provozu mezi modulem a Kestrel z umístění mimo server.

Párovací token se používá k zajištění toho, že žádosti přijaté službou Kestrel IIS byly zasílané službou IIS a nepřišly z jiného zdroje. Token párování se vytvoří a nastaví do proměnné prostředí (ASPNETCORE_TOKEN) modulu. Token párování se také nastaví do hlavičky (MS-ASPNETCORE-TOKEN) pro každý požadavek naxied. Middleware služby IIS kontroluje každý požadavek, který obdrží, a ověří, že hodnota hlavičky spárujícího tokenu odpovídá hodnotě proměnné prostředí. Pokud se hodnoty tokenu neshodují, požadavek se zaprotokoluje a odmítne. Proměnná prostředí párovacího tokenu a provoz mezi modulem a Kestrel nejsou přístupné z umístění mimo server. Bez znalosti hodnoty párového tokenu nemůže cyberattacker odesílat žádosti, které obcházejí kontrolu v middlewaru služby IIS.

základní modul ASP.NET se sdílenou konfigurací služby IIS

Instalační program ASP.NET Core Module běží s oprávněními účtu TrustedInstaller . Vzhledem k tomu, že místní systémový účet nemá oprávnění ke změně cesty ke sdílené složce používané sdílenou konfigurací služby IIS, instalační program vyvolá chybu odepření přístupu při pokusu o konfiguraci nastavení modulu v souboru applicationHost.config ve sdílené složce.

Při použití sdílené konfigurace služby IIS postupujte takto:

  1. Zakažte sdílenou konfiguraci služby IIS.
  2. Spusťte instalační program.
  3. Exportujte aktualizovaný soubor applicationHost.config do sdílené složky.
  4. Znovu povolte sdílenou konfiguraci služby IIS.

Protokoly instalačního programu modulu a hostitelské sady

Určení verze nainstalovaného modulu ASP.NET Core:

  1. V hostitelském systému přejděte na %windir%\System32\inetsrv.
  2. Vyhledejte soubor aspnetcore.dll.
  3. Klikněte pravým tlačítkem myši na soubor a v místní nabídce vyberte Vlastnosti .
  4. Vyberte kartu Podrobnosti. Verze souboru a verze produktu představují nainstalovanou verzi modulu.

Protokoly instalačního programu sady hostingu pro modul najdete v umístění C:\Users\%UserName%\AppData\Local\Temp. Soubor má název dd_DotNetCoreWinSvrHosting__<timestamp>_000_AspNetCoreModule_x64.log.

Umístění modulů, schémat a konfiguračních souborů

Modul

IIS (x86/amd64):

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

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

IIS Express (x86/amd64):

  • %ProgramFiles%\IIS Express\aspnetcore.dll

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

Schéma

IIS

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

IIS Express

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

Konfigurace

IIS

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

IIS Express

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

  • iisexpress.exe CLI: %USERPROFILE%\Documents\IISExpress\config\applicationhost.config

Soubory lze najít vyhledáním aspnetcore v souboru applicationHost.config .

Další materiály