Bagikan melalui

ASP.NET Core Module (ANCM) untuk IIS

  • Artikel

Catatan

Ini bukan versi terbaru dari artikel ini. Untuk rilis saat ini, lihat versi .NET 8 dari artikel ini.

Peringatan

Versi ASP.NET Core ini tidak lagi didukung. Untuk informasi selengkapnya, lihat Kebijakan Dukungan .NET dan .NET Core. Untuk rilis saat ini, lihat versi .NET 8 dari artikel ini.

Penting

Informasi ini berkaitan dengan produk pra-rilis yang mungkin dimodifikasi secara substansial sebelum dirilis secara komersial. Microsoft tidak memberikan jaminan, tersirat maupun tersurat, sehubungan dengan informasi yang diberikan di sini.

Untuk rilis saat ini, lihat versi .NET 8 dari artikel ini.

Modul ASP.NET Core (ANCM) adalah modul IIS asli yang dicolokkan ke alur IIS, memungkinkan aplikasi ASP.NET Core bekerja dengan IIS. Jalankan aplikasi ASP.NET Core dengan IIS dengan:

  • Hosting aplikasi ASP.NET Core di dalam proses pekerja IIS (w3wp.exe), yang disebut model hosting dalam proses.
  • Meneruskan permintaan web ke backend ASP.NET aplikasi Core yang Kestrel menjalankan server, yang disebut model hosting di luar proses.

Ada trade-off antara masing-masing model hosting. Secara default, model hosting dalam proses digunakan karena performa dan diagnostik yang lebih baik.

Untuk informasi lebih lanjut dan panduan konfigurasi, lihat topik berikut:

Menginstal Modul Inti ASP.NET (ANCM)

Modul ASP.NET Core (ANCM) diinstal dengan .NET Core Runtime dari .NET Core Hosting Bundle. Modul ASP.NET Core kompatibel maju dan mundur dengan rilis .NET dalam dukungan.

Perubahan yang melanggar dan saran keamanan dilaporkan pada repositori Pengumuman. Pengumuman dapat dibatasi pada versi tertentu dengan memilih filter Label .

Unduh alat penginstal menggunakan tautan berikut:

Alat penginstal .NET Core Hosting Bundle saat ini (unduh langsung)

Untuk informasi selengkapnya, termasuk menginstal versi modul yang lebih lama, lihat Bundel Hosting.

Untuk pengalaman tutorial tentang menerbitkan aplikasi ASP.NET Core ke server IIS, lihat Menerbitkan aplikasi ASP.NET Core ke IIS.

Modul ASP.NET Core (ANCM) adalah modul IIS asli yang dicolokkan ke alur IIS untuk:

Versi Windows yang didukung:

  • Windows 7 atau yang lebih baru
  • Windows Server 2012 R2 atau versi lebih baru

Saat menghosting dalam proses, modul menggunakan implementasi server dalam proses untuk IIS, yang disebut IIS HTTP Server (IISHttpServer).

Saat menghosting di luar proses, modul hanya berfungsi dengan Kestrel. Modul tidak berfungsi dengan HTTP.sys.

Model Hosting

Model hosting dalam proses

ASP.NET Aplikasi inti default ke model hosting dalam proses.

Karakteristik berikut berlaku saat menghosting dalam proses:

  • Server HTTP IIS (IISHttpServer) digunakan alih-alih Kestrel server. Untuk prosesnya, CreateDefaultBuilder memanggil UseIIS ke:

    • Daftarkan IISHttpServer.
    • Konfigurasikan port dan jalur dasar yang harus didengarkan server saat berjalan di belakang Modul Inti ASP.NET.
    • Konfigurasikan host untuk menangkap kesalahan startup.

  • Atribut requestTimeout tidak berlaku untuk hosting dalam proses.

  • Berbagi kumpulan aplikasi di antara aplikasi tidak didukung. Gunakan satu kumpulan aplikasi per aplikasi.

  • Saat menggunakan Web Deploy atau menempatkan app_offline.htm file secara manual dalam penyebaran, aplikasi mungkin tidak segera dimatikan jika ada koneksi terbuka. Misalnya, koneksi WebSocket dapat menunda aplikasi dimatikan.

  • Arsitektur (bitness) aplikasi dan runtime yang diinstal (x64 atau x86) harus cocok dengan arsitektur kumpulan aplikasi.

  • Pemutusan sambungan klien terdeteksi. Token HttpContext.RequestAborted pembatalan dibatalkan ketika klien terputus.

  • Di ASP.NET Core 2.2.1 atau yang lebih lama, GetCurrentDirectory mengembalikan direktori pekerja dari proses yang dimulai oleh IIS daripada direktori aplikasi (misalnya, C:\Windows\System32\inetsrv untuk w3wp.exe).

    Untuk kode sampel yang mengatur direktori aplikasi saat ini, lihat CurrentDirectoryHelpers kelas . Panggil SetCurrentDirectory metode. Panggilan berikutnya untuk GetCurrentDirectory menyediakan direktori aplikasi.

  • Saat menghosting dalam proses, AuthenticateAsync tidak dipanggil secara internal untuk menginisialisasi pengguna. Oleh karena itu, implementasi yang IClaimsTransformation digunakan untuk mengubah klaim setelah setiap autentikasi tidak diaktifkan secara default. Saat mengubah klaim dengan IClaimsTransformation implementasi, panggil AddAuthentication untuk menambahkan layanan autentikasi:

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

public void Configure(IApplicationBuilder app)
{
    app.UseAuthentication();
}
    • Penyebaran Paket Web (file tunggal) tidak didukung.

Model hosting di luar proses

Untuk mengonfigurasi aplikasi untuk hosting di luar proses, atur nilai <AspNetCoreHostingModel> properti ke OutOfProcess dalam file proyek (.csproj):

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

Hosting dalam proses diatur dengan InProcess, yang merupakan nilai default.

Nilai <AspNetCoreHostingModel> tidak peka huruf besar/kecil, jadi inprocess dan outofprocess merupakan nilai yang valid.

Kestrel server digunakan alih-alih Server HTTP IIS (IISHttpServer).

Untuk di luar proses, CreateDefaultBuilder panggilan UseIISIntegration ke:

  • Konfigurasikan port dan jalur dasar yang harus didengarkan server saat berjalan di belakang Modul Inti ASP.NET.
  • Konfigurasikan host untuk menangkap kesalahan startup.

Perubahan model hosting

hostingModel Jika pengaturan diubah dalam web.config file (dijelaskan di bagian Konfigurasi denganweb.config), modul akan mendaur ulang proses pekerja untuk IIS.

Untuk IIS Express, modul tidak mendaur ulang proses pekerja tetapi sebaliknya memicu pematian yang lancar dari proses IIS Express saat ini. Permintaan berikutnya ke aplikasi menghasilkan proses IIS Express baru.

Nama proses

Process.GetCurrentProcess().ProcessNamew3wpiisexpress/laporan (dalam proses) atau dotnet (di luar proses).

Banyak modul asli, seperti Autentikasi Windows, tetap aktif. Untuk mempelajari selengkapnya tentang modul IIS yang aktif dengan modul ASP.NET Core, lihat Modul IIS dengan ASP.NET Core.

Modul ASP.NET Core juga dapat:

  • Atur variabel lingkungan untuk proses pekerja.
  • Log output stdout ke penyimpanan file untuk memecahkan masalah startup.
  • Teruskan token autentikasi Windows.

Cara menginstal dan menggunakan ASP.NET Core Module (ANCM)

Untuk petunjuk tentang cara menginstal Modul ASP.NET Core, lihat Menginstal .NET Core Hosting Bundle. Modul ASP.NET Core kompatibel maju dan mundur dengan rilis .NET dalam dukungan.

Perubahan yang melanggar dan saran keamanan dilaporkan pada repositori Pengumuman. Pengumuman dapat dibatasi pada versi tertentu dengan memilih filter Label .

Konfigurasi dengan web.config

Modul ASP.NET Core dikonfigurasi dengan aspNetCore bagian simpul system.webServer dalam file web.config situs.

File berikut web.config diterbitkan untuk penyebaran yang bergantung pada kerangka kerja dan mengonfigurasi Modul inti ASP.NET untuk menangani permintaan situs:

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

Web.config berikut diterbitkan untuk penyebaran mandiri:

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

Properti InheritInChildApplications diatur ke false untuk menunjukkan bahwa pengaturan yang ditentukan dalam <location> elemen tidak diwariskan oleh aplikasi yang berada di subdirektori aplikasi.

Saat aplikasi disebarkan ke Azure App Service, stdoutLogFile jalur diatur ke \\?\%home%\LogFiles\stdout. Jalur menyimpan log stdout ke LogFiles folder, yang merupakan lokasi yang secara otomatis dibuat oleh layanan.

Untuk informasi tentang konfigurasi sub-aplikasi IIS, lihat Host ASP.NET Core di Windows dengan IIS.

Atribut elemen aspNetCore

Atribut Deskripsi Default
arguments

Atribut string opsional.

Argumen ke executable yang ditentukan dalam processPath.
disableStartUpErrorPage

Atribut Boolean opsional.

Jika true, halaman 502.5 - Kegagalan Proses ditekan, dan halaman kode status 502 yang dikonfigurasi di web.config lebih diutamakan.

 false
forwardWindowsAuthToken

Atribut Boolean opsional.

Jika true, token diteruskan ke proses turunan yang mendengarkan %ASPNETCORE_PORT% sebagai header 'MS-ASPNETCORE-WINAUTHTOKEN' per permintaan. Ini adalah tanggung jawab proses itu untuk memanggil CloseHandle pada token ini per permintaan.

 true
hostingModel

Atribut string opsional.

Menentukan model hosting sebagai dalam proses (InProcess/inprocess) atau di luar proses ().OutOfProcess/outofprocess

 InProcess
inprocess
processesPerApplication

Atribut bilangan bulat opsional.

Menentukan jumlah instans proses yang ditentukan dalam pengaturan processPath yang dapat dipisahkan per aplikasi.

†Untuk hosting dalam proses, nilainya terbatas pada 1.

Pengaturan processesPerApplication tidak disarankan. Atribut ini akan dihapus dalam rilis mendatang.

 Default: 1
Min: 1
Maks: 100†
processPath

Atribut string yang diperlukan.

Jalur ke executable yang meluncurkan proses mendengarkan permintaan HTTP. Jalur relatif didukung. Jika jalur dimulai dengan ., jalur dianggap relatif terhadap akar situs.
rapidFailsPerMinute

Atribut bilangan bulat opsional.

Menentukan berapa kali proses yang ditentukan dalam processPath diizinkan untuk crash per menit. Jika batas ini terlampaui, modul berhenti meluncurkan proses selama sisa menit.

Tidak didukung dengan hosting dalam proses.

 Default: 10
Min: 0
Maks: 100
requestTimeout

Atribut rentang waktu opsional.

Menentukan durasi di mana Modul ASP.NET Core menunggu respons dari proses yang mendengarkan pada %ASPNETCORE_PORT%.

Dalam versi Modul ASP.NET Core yang dikirim dengan rilis ASP.NET Core 2.1 atau yang lebih baru, requestTimeout ditentukan dalam jam, menit, dan detik.

Tidak berlaku untuk hosting dalam proses. Untuk hosting dalam proses, modul menunggu aplikasi memproses permintaan.

Nilai yang valid untuk segmen menit dan detik dari string berada dalam rentang 0-59. Penggunaan 60 dalam nilai untuk menit atau detik menghasilkan 500 - Kesalahan Server Internal.

 Default: 00:02:00
Min: 00:00:00
Maks: 360:00:00
shutdownTimeLimit

Atribut bilangan bulat opsional.

Durasi dalam hitungan detik bahwa modul menunggu executable dimatikan dengan lancar saat app_offline.htm file terdeteksi.

 Default: 10
Min: 0
Maks: 600
startupTimeLimit

Atribut bilangan bulat opsional.

Durasi dalam detik bahwa modul menunggu executable untuk memulai proses yang mendengarkan pada port. Jika batas waktu ini terlampaui, modul akan mematikan proses.

Saat menghosting dalam proses: Proses tidak dimulai ulang dan tidak menggunakan pengaturan rapidFailsPerMinute.

Saat menghosting di luar proses: Modul mencoba meluncurkan kembali proses ketika menerima permintaan baru dan terus mencoba memulai ulang proses pada permintaan masuk berikutnya kecuali aplikasi gagal memulai rapidFailsPerMinute beberapa kali dalam menit bergulir terakhir.

Nilai 0 (nol) tidak dianggap sebagai batas waktu tak terbatas.

 Default: 120
Min: 0
Maks: 3600
stdoutLogEnabled

Atribut Boolean opsional.

Jika true, stdout dan stderr untuk proses yang ditentukan dalam processPath dialihkan ke file yang ditentukan dalam stdoutLogFile.

 false
stdoutLogFile

Atribut string opsional.

Menentukan jalur file relatif atau absolut tempat stdout dan stderr dari proses yang ditentukan dalam processPath dicatat. Jalur relatif relatif terhadap akar situs. Jalur apa pun yang dimulai . relatif terhadap akar situs dan semua jalur lainnya diperlakukan sebagai jalur absolut. Folder apa pun yang disediakan di jalur dibuat oleh modul saat file log dibuat. Menggunakan pemisah garis bawah, tanda waktu, ID proses, dan ekstensi file (.log) ditambahkan ke segmen terakhir jalur stdoutLogFile . Jika .\logs\stdout disediakan sebagai nilai, contoh log stdout disimpan seperti stdout_20180205194132_1934.log di logs folder saat disimpan pada 2/5/2018 pukul 19:41:32 dengan ID proses 1934.

 aspnetcore-stdout

Atur variabel lingkungan

Variabel lingkungan dapat ditentukan untuk proses dalam processPath atribut . Tentukan variabel lingkungan dengan <environmentVariable> elemen turunan dari <environmentVariables> elemen koleksi. Variabel lingkungan yang ditetapkan di bagian ini lebih diutamakan daripada variabel lingkungan sistem.

Contoh berikut menetapkan dua variabel lingkungan di web.config. ASPNETCORE_ENVIRONMENT mengonfigurasi lingkungan aplikasi ke Development. Pengembang dapat mengatur sementara nilai ini dalam web.config file untuk memaksa Halaman Pengecualian Pengembang dimuat saat menelusuri kesalahan pengecualian aplikasi. CONFIG_DIR adalah contoh variabel lingkungan yang ditentukan pengguna, di mana pengembang telah menulis kode yang membaca nilai pada startup untuk membentuk jalur untuk memuat file konfigurasi aplikasi.

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

Catatan

Alternatif untuk mengatur lingkungan secara langsung web.config adalah menyertakan <EnvironmentName> properti dalam profil penerbitan (.pubxml) atau file proyek. Pendekatan ini mengatur lingkungan saat web.config proyek diterbitkan:

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

Peringatan

Hanya atur ASPNETCORE_ENVIRONMENT variabel lingkungan ke Development pada pementasan dan pengujian server yang tidak dapat diakses oleh jaringan yang tidak tepercaya, seperti Internet.

app_offline.htm

Jika file dengan nama app_offline.htm terdeteksi di direktori akar aplikasi, modul ASP.NET Core mencoba mematikan aplikasi dengan lancar dan berhenti memproses permintaan masuk. Jika aplikasi masih berjalan setelah jumlah detik yang ditentukan dalam shutdownTimeLimit, Modul ASP.NET Core akan mematikan proses yang sedang berjalan.

app_offline.htm Saat file ada, ASP.NET Core Module merespons permintaan dengan mengirim kembali konten app_offline.htm file. app_offline.htm Saat file dihapus, permintaan berikutnya memulai aplikasi.

Saat menggunakan model hosting di luar proses, aplikasi mungkin tidak segera dimatikan jika ada koneksi terbuka. Misalnya, koneksi WebSocket dapat menunda aplikasi dimatikan.

Halaman kesalahan start-up

Hosting dalam proses dan di luar proses menghasilkan halaman kesalahan kustom ketika mereka gagal memulai aplikasi.

Jika Modul inti ASP.NET gagal menemukan penangan permintaan dalam proses atau di luar proses, kode status Kegagalan Beban Handler Dalam Proses/Di Luar Proses akan muncul.

Untuk hosting dalam proses jika Modul inti ASP.NET gagal memulai aplikasi, halaman kode status Kegagalan 500.30 - Mulai muncul.

Untuk hosting di luar proses jika Modul Inti ASP.NET gagal meluncurkan proses backend atau proses backend dimulai tetapi gagal mendengarkan port yang dikonfigurasi, halaman kode status Kegagalan Proses 502.5 muncul.

Untuk menekan halaman ini dan kembali ke halaman kode status IIS 5xx default, gunakan disableStartUpErrorPage atribut . Untuk informasi selengkapnya tentang mengonfigurasi pesan kesalahan kustom, lihat Kesalahan <httpErrors>HTTP .

Pembuatan dan pengalihan log

Modul ASP.NET Core mengalihkan output konsol stdout dan stderr ke disk jika stdoutLogEnabled atribut aspNetCore dan stdoutLogFile elemen diatur. Folder apa pun di stdoutLogFile jalur dibuat oleh modul saat file log dibuat. Kumpulan aplikasi harus memiliki akses tulis ke lokasi tempat log ditulis (gunakan IIS AppPool\<app_pool_name> untuk memberikan izin tulis).

Log tidak diputar, kecuali terjadi daur ulang/mulai ulang proses. Ini adalah tanggung jawab hoster untuk membatasi ruang disk yang digunakan log.

Menggunakan log stdout hanya disarankan untuk memecahkan masalah pengaktifan aplikasi saat menghosting di IIS atau saat menggunakan dukungan waktu pengembangan untuk IIS dengan Visual Studio, bukan saat men-debug secara lokal dan menjalankan aplikasi dengan IIS Express.

Jangan gunakan log stdout untuk tujuan pengelogan aplikasi umum. Untuk pengelogan rutin di aplikasi ASP.NET Core, gunakan pustaka pengelogan yang membatasi ukuran file log dan memutar log. Untuk informasi selengkapnya, lihat penyedia pengelogan pihak ketiga.

Tanda waktu dan ekstensi file ditambahkan secara otomatis saat file log dibuat. Nama file log terdiri dengan menambahkan tanda waktu, ID proses, dan ekstensi file (.log) ke segmen stdoutLogFile terakhir jalur (biasanya stdout) yang dibatasi oleh garis bawah. stdoutLogFile Jika jalur berakhir dengan stdout, log untuk aplikasi dengan PID 1934 yang dibuat pada 2/5/2018 pukul 19:42:32 memiliki nama stdout_20180205194132_1934.logfile .

Jika stdoutLogEnabled salah, kesalahan yang terjadi pada startup aplikasi diambil dan dipancarkan ke log peristiwa hingga 30 KB. Setelah startup, semua log tambahan dibuang.

Elemen sampel aspNetCore berikut mengonfigurasi pengelogan stdout di jalur .\log\relatif . Konfirmasikan bahwa pengguna identity AppPool memiliki izin untuk menulis ke jalur yang disediakan.

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

Saat menerbitkan aplikasi untuk penyebaran Azure App Service, Web SDK mengatur nilai ke stdoutLogFile \\?\%home%\LogFiles\stdout. Variabel %home lingkungan telah ditentukan sebelumnya untuk aplikasi yang dihosting oleh Azure App Service.

Untuk membuat aturan filter pengelogan, lihat bagian Terapkan aturan filter log di bagian kode dari dokumentasi pengelogan ASP.NET Core.

Untuk informasi selengkapnya tentang format jalur, lihat Format jalur file pada sistem Windows.

Log diagnostik yang ditingkatkan

Modul ASP.NET Core dapat dikonfigurasi untuk menyediakan log diagnostik yang ditingkatkan. <handlerSettings> Tambahkan elemen ke <aspNetCore> elemen di web.config. debugLevel Mengatur untuk mengekspos keakuratan TRACE informasi diagnostik yang lebih tinggi:

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

Folder apa pun di jalur (logs dalam contoh sebelumnya) dibuat oleh modul saat file log dibuat. Kumpulan aplikasi harus memiliki akses tulis ke lokasi tempat log ditulis (gunakan IIS AppPool\{APP POOL NAME}, di mana tempat penampung {APP POOL NAME} adalah nama kumpulan aplikasi, untuk memberikan izin tulis).

Nilai tingkat debug (debugLevel) dapat mencakup tingkat dan lokasi.

Tingkat (secara berurutan dari paling sedikit hingga paling verbose):

  • KESALAHAN
  • PERINGATAN
  • INFO
  • TRACE

Lokasi (beberapa lokasi diizinkan):

  • KONSOL
  • EVENTLOG
  • FILE

Pengaturan handler juga dapat disediakan melalui variabel lingkungan:

  • ASPNETCORE_MODULE_DEBUG_FILE: Jalur ke file log debug. (Default: aspnetcore-debug.log)
  • ASPNETCORE_MODULE_DEBUG: Pengaturan tingkat debug.

Peringatan

Jangan biarkan pengelogan debug diaktifkan dalam penyebaran lebih lama dari yang diperlukan untuk memecahkan masalah. Ukuran log tidak terbatas. Membiarkan log debug diaktifkan dapat menghabiskan ruang disk yang tersedia dan crash server atau layanan aplikasi.

Lihat Konfigurasi dengan web.config untuk contoh aspNetCore elemen dalam web.config file.

Mengubah ukuran tumpukan

Hanya berlaku saat menggunakan model hosting dalam proses.

Konfigurasikan ukuran tumpukan terkelola menggunakan stackSize pengaturan dalam byte di web.config. Ukuran defaultnya adalah 1.048.576 byte (1 MB).

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

Konfigurasi proksi menggunakan protokol HTTP dan token pemasangan

Hanya berlaku untuk hosting di luar proses.

Proksi yang dibuat antara Modul ASP.NET Core dan Kestrel menggunakan protokol HTTP. Tidak ada risiko menguping lalu lintas antara modul dan Kestrel dari lokasi di luar server.

Token pemasangan digunakan untuk menjamin bahwa permintaan yang diterima oleh Kestrel diproksi oleh IIS dan tidak berasal dari beberapa sumber lain. Token pemasangan dibuat dan diatur ke dalam variabel lingkungan (ASPNETCORE_TOKEN) oleh modul. Token pemasangan juga diatur ke header (MS-ASPNETCORE-TOKEN) pada setiap permintaan yang diproksi. Middleware IIS memeriksa setiap permintaan yang diterimanya untuk mengonfirmasi bahwa nilai header token pemasangan cocok dengan nilai variabel lingkungan. Jika nilai token tidak cocok, permintaan dicatat dan ditolak. Variabel lingkungan token pemasangan dan lalu lintas antara modul dan Kestrel tidak dapat diakses dari lokasi di luar server. Tanpa mengetahui nilai token pemasangan, cyberattacker tidak dapat mengirimkan permintaan yang melewati pemeriksaan di Middleware IIS.

ASP.NET Modul Inti dengan Konfigurasi Bersama IIS

Alat penginstal Modul Inti ASP.NET berjalan dengan hak istimewa akun TrustedInstaller . Karena akun sistem lokal tidak memiliki izin modifikasi untuk jalur berbagi yang digunakan oleh Konfigurasi Bersama IIS, penginstal melemparkan kesalahan akses yang ditolak saat mencoba mengonfigurasi pengaturan modul dalam applicationHost.config file pada berbagi.

Saat menggunakan Konfigurasi Bersama IIS pada komputer yang sama dengan penginstalan IIS, jalankan penginstal Bundel Hosting Inti ASP.NET dengan parameter yang OPT_NO_SHARED_CONFIG_CHECK diatur ke 1:

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

Saat jalur ke konfigurasi bersama tidak berada di komputer yang sama dengan penginstalan IIS, ikuti langkah-langkah berikut:

  1. Nonaktifkan Konfigurasi Bersama IIS.
  2. Jalankan alat penginstal.
  3. Ekspor file yang diperbarui applicationHost.config ke berbagi.
  4. Aktifkan kembali Konfigurasi Bersama IIS.

Versi modul dan log penginstal Bundel Hosting

Untuk menentukan versi Modul Inti ASP.NET yang diinstal:

  1. Pada sistem hosting, navigasikan ke %windir%\System32\inetsrv.
  2. aspnetcore.dll Temukan file.
  3. Klik kanan file dan pilih Properti dari menu kontekstual.
  4. Pilih tab Detail. Versi file dan Versi produk mewakili versi modul yang diinstal.

Log penginstal Bundel Hosting untuk modul ditemukan di C:\Users\%UserName%\AppData\Local\Temp. File diberi nama dd_DotNetCoreWinSvrHosting__{TIMESTAMP}_000_AspNetCoreModule_x64.log.

Modul, skema, dan lokasi file konfigurasi

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

Skema

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

Konfigurasi

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

File dapat ditemukan dengan mencari aspnetcore dalam applicationHost.config file.

Modul ASP.NET Core (ANCM) adalah modul IIS asli yang dicolokkan ke alur IIS untuk:

Versi Windows yang didukung:

  • Windows 7 atau yang lebih baru
  • Windows Server 2008 R2 atau yang lebih baru

Saat menghosting dalam proses, modul menggunakan implementasi server dalam proses untuk IIS, yang disebut IIS HTTP Server (IISHttpServer).

Saat menghosting di luar proses, modul hanya berfungsi dengan Kestrel. Modul tidak berfungsi dengan HTTP.sys.

Model Hosting

Model hosting dalam proses

Untuk mengonfigurasi aplikasi untuk hosting dalam proses, tambahkan <AspNetCoreHostingModel> properti ke file proyek aplikasi dengan nilai InProcess (hosting di luar proses diatur dengan OutOfProcess):

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

Model hosting dalam proses tidak didukung untuk aplikasi ASP.NET Core yang menargetkan .NET Framework.

Nilai <AspNetCoreHostingModel> tidak peka huruf besar/kecil, jadi inprocess dan outofprocess merupakan nilai yang valid.

<AspNetCoreHostingModel> Jika properti tidak ada dalam file, nilai defaultnya adalah OutOfProcess.

Karakteristik berikut berlaku saat menghosting dalam proses:

  • Server HTTP IIS (IISHttpServer) digunakan alih-alih Kestrel server. Untuk prosesnya, CreateDefaultBuilder memanggil UseIIS ke:

    • Daftarkan IISHttpServer.
    • Konfigurasikan port dan jalur dasar yang harus didengarkan server saat berjalan di belakang Modul Inti ASP.NET.
    • Konfigurasikan host untuk menangkap kesalahan startup.

  • Atribut requestTimeout tidak berlaku untuk hosting dalam proses.

  • Berbagi kumpulan aplikasi di antara aplikasi tidak didukung. Gunakan satu kumpulan aplikasi per aplikasi.

  • Saat menggunakan Web Deploy atau menempatkan file app_offline.htm secara manual dalam penyebaran, aplikasi mungkin tidak segera dimatikan jika ada koneksi terbuka. Misalnya, koneksi websocket dapat menunda aplikasi dimatikan.

  • Arsitektur (bitness) aplikasi dan runtime yang diinstal (x64 atau x86) harus cocok dengan arsitektur kumpulan aplikasi.

  • Pemutusan sambungan klien terdeteksi. Token pembatalan HttpContext.RequestAborted dibatalkan ketika klien terputus.

  • Di ASP.NET Core 2.2.1 atau yang lebih lama, GetCurrentDirectory mengembalikan direktori pekerja dari proses yang dimulai oleh IIS daripada direktori aplikasi (misalnya, C:\Windows\System32\inetsrv untuk w3wp.exe).

    Untuk kode sampel yang mengatur direktori aplikasi saat ini, lihat kelas CurrentDirectoryHelpers. Panggil SetCurrentDirectory metode. Panggilan berikutnya untuk GetCurrentDirectory menyediakan direktori aplikasi.

  • Saat menghosting dalam proses, AuthenticateAsync tidak dipanggil secara internal untuk menginisialisasi pengguna. Oleh karena itu, implementasi yang IClaimsTransformation digunakan untuk mengubah klaim setelah setiap autentikasi tidak diaktifkan secara default. Saat mengubah klaim dengan IClaimsTransformation implementasi, panggil AddAuthentication untuk menambahkan layanan autentikasi:

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

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

Model hosting di luar proses

Untuk mengonfigurasi aplikasi untuk hosting di luar proses, gunakan salah satu pendekatan berikut dalam file proyek:

  • Jangan tentukan <AspNetCoreHostingModel> properti . <AspNetCoreHostingModel> Jika properti tidak ada dalam file, nilai defaultnya adalah OutOfProcess.
  • Atur nilai properti ke <AspNetCoreHostingModel> OutOfProcess (hosting dalam proses diatur dengan InProcess):
<PropertyGroup>
  <AspNetCoreHostingModel>OutOfProcess</AspNetCoreHostingModel>
</PropertyGroup>

Nilainya tidak peka huruf besar/kecil, jadi inprocess dan outofprocess merupakan nilai yang valid.

Kestrel server digunakan alih-alih Server HTTP IIS (IISHttpServer).

Untuk di luar proses, CreateDefaultBuilder memanggil UseIISIntegration ke:

  • Konfigurasikan port dan jalur dasar yang harus didengarkan server saat berjalan di belakang Modul Inti ASP.NET.
  • Konfigurasikan host untuk menangkap kesalahan startup.

Perubahan model hosting

hostingModel Jika pengaturan diubah dalam file web.config (dijelaskan di bagian Konfigurasi dengan web.config), modul akan mendaur ulang proses pekerja untuk IIS.

Untuk IIS Express, modul tidak mendaur ulang proses pekerja tetapi sebaliknya memicu pematian yang lancar dari proses IIS Express saat ini. Permintaan berikutnya ke aplikasi menghasilkan proses IIS Express baru.

Nama proses

Process.GetCurrentProcess().ProcessNamew3wpiisexpress/laporan (dalam proses) atau dotnet (di luar proses).

Banyak modul asli, seperti Autentikasi Windows, tetap aktif. Untuk mempelajari selengkapnya tentang modul IIS yang aktif dengan modul ASP.NET Core, lihat Modul IIS dengan ASP.NET Core.

Modul ASP.NET Core juga dapat:

  • Atur variabel lingkungan untuk proses pekerja.
  • Log output stdout ke penyimpanan file untuk memecahkan masalah startup.
  • Teruskan token autentikasi Windows.

Cara menginstal dan menggunakan ASP.NET Core Module (ANCM)

Untuk petunjuk tentang cara menginstal Modul ASP.NET Core, lihat Menginstal .NET Core Hosting Bundle. Modul ASP.NET Core kompatibel maju dan mundur dengan rilis .NET dalam dukungan.

Perubahan yang melanggar dan saran keamanan dilaporkan pada repositori Pengumuman. Pengumuman dapat dibatasi pada versi tertentu dengan memilih filter Label .

Konfigurasi dengan web.config

Modul ASP.NET Core dikonfigurasi dengan aspNetCore bagian simpul system.webServer dalam file web.config situs.

File web.config berikut diterbitkan untuk penyebaran yang bergantung pada kerangka kerja dan mengonfigurasi Modul Inti ASP.NET untuk menangani permintaan situs:

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

Web.config berikut diterbitkan untuk penyebaran mandiri:

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

Properti InheritInChildApplications diatur ke false untuk menunjukkan bahwa pengaturan yang ditentukan dalam <elemen lokasi> tidak diwariskan oleh aplikasi yang berada di subdirektori aplikasi.

Saat aplikasi disebarkan ke Azure App Service, stdoutLogFile jalur diatur ke \\?\%home%\LogFiles\stdout. Jalur menyimpan log stdout ke folder LogFiles , yang merupakan lokasi yang dibuat secara otomatis oleh layanan.

Untuk informasi tentang konfigurasi sub-aplikasi IIS, lihat Host ASP.NET Core di Windows dengan IIS.

Atribut elemen aspNetCore

Atribut Deskripsi Default
arguments

Atribut string opsional.

Argumen ke executable yang ditentukan dalam processPath.
disableStartUpErrorPage

Atribut Boolean opsional.

Jika true, halaman 502.5 - Kegagalan Proses ditekan, dan halaman kode status 502 yang dikonfigurasi di web.config lebih diutamakan.

 false
forwardWindowsAuthToken

Atribut Boolean opsional.

Jika true, token diteruskan ke proses turunan yang mendengarkan pada %ASPNETCORE_PORT% sebagai header 'MS-ASPNETCORE-WINAUTHTOKEN' per permintaan. Ini adalah tanggung jawab proses itu untuk memanggil CloseHandle pada token ini per permintaan.

 true
hostingModel

Atribut string opsional.

Menentukan model hosting sebagai dalam proses (InProcess/inprocess) atau di luar proses ().OutOfProcess/outofprocess

 OutOfProcess
outofprocess
processesPerApplication

Atribut bilangan bulat opsional.

Menentukan jumlah instans proses yang ditentukan dalam processPath pengaturan yang dapat dipisahkan per aplikasi.

†Untuk hosting dalam proses, nilainya terbatas pada 1.

Pengaturan processesPerApplication tidak disarankan. Atribut ini akan dihapus dalam rilis mendatang.

 Default: 1
Min: 1
Maks: 100†
processPath

Atribut string yang diperlukan.

Jalur ke executable yang meluncurkan proses mendengarkan permintaan HTTP. Jalur relatif didukung. Jika jalur dimulai dengan ., jalur dianggap relatif terhadap akar situs.
rapidFailsPerMinute

Atribut bilangan bulat opsional.

Menentukan berapa kali proses yang ditentukan di processPath diizinkan untuk crash per menit. Jika batas ini terlampaui, modul berhenti meluncurkan proses selama sisa menit.

Tidak didukung dengan hosting dalam proses.

 Default: 10
Min: 0
Maks: 100
requestTimeout

Atribut rentang waktu opsional.

Menentukan durasi di mana Modul ASP.NET Core menunggu respons dari proses yang mendengarkan pada %ASPNETCORE_PORT%.

Dalam versi Modul ASP.NET Core yang dikirim dengan rilis ASP.NET Core 2.1 atau yang lebih baru, requestTimeout ditentukan dalam jam, menit, dan detik.

Tidak berlaku untuk hosting dalam proses. Untuk hosting dalam proses, modul menunggu aplikasi memproses permintaan.

Nilai yang valid untuk segmen menit dan detik dari string berada dalam rentang 0-59. Penggunaan 60 dalam nilai untuk menit atau detik menghasilkan 500 - Kesalahan Server Internal.

 Default: 00:02:00
Min: 00:00:00
Maks: 360:00:00
shutdownTimeLimit

Atribut bilangan bulat opsional.

Durasi dalam hitungan detik bahwa modul menunggu executable dimatikan dengan lancar saat app_offline.htm file terdeteksi.

 Default: 10
Min: 0
Maks: 600
startupTimeLimit

Atribut bilangan bulat opsional.

Durasi dalam detik bahwa modul menunggu executable untuk memulai proses yang mendengarkan pada port. Jika batas waktu ini terlampaui, modul akan mematikan proses.

Saat menghosting dalam proses: Proses tidak dimulai ulang dan tidak menggunakan rapidFailsPerMinute pengaturan.

Saat menghosting di luar proses: Modul mencoba meluncurkan kembali proses ketika menerima permintaan baru dan terus mencoba memulai ulang proses pada permintaan masuk berikutnya kecuali aplikasi gagal memulai rapidFailsPerMinute berapa kali dalam menit bergulir terakhir.

Nilai 0 (nol) tidak dianggap sebagai batas waktu tak terbatas.

 Default: 120
Min: 0
Maks: 3600
stdoutLogEnabled

Atribut Boolean opsional.

Jika true, stdout dan stderr untuk proses yang ditentukan di processPath dialihkan ke file yang ditentukan dalam stdoutLogFile.

 false
stdoutLogFile

Atribut string opsional.

Menentukan jalur file relatif atau absolut yang stdout dan stderr dari proses yang ditentukan masuk processPath . Jalur relatif relatif terhadap akar situs. Jalur apa pun yang dimulai . relatif terhadap akar situs dan semua jalur lainnya diperlakukan sebagai jalur absolut. Folder apa pun yang disediakan di jalur dibuat oleh modul saat file log dibuat. Menggunakan pemisah garis bawah, tanda waktu, ID proses, dan ekstensi file (.log) ditambahkan ke segmen stdoutLogFile terakhir jalur. Jika .\logs\stdout disediakan sebagai nilai, contoh log stdout disimpan seperti stdout_20180205194132_1934.log di logs folder saat disimpan pada 2/5/2018 pukul 19:41:32 dengan ID proses 1934.

 aspnetcore-stdout

Pengaturan variabel lingkungan

Variabel lingkungan dapat ditentukan untuk proses dalam processPath atribut . Tentukan variabel lingkungan dengan <environmentVariable> elemen turunan dari <environmentVariables> elemen koleksi. Variabel lingkungan yang ditetapkan di bagian ini lebih diutamakan daripada variabel lingkungan sistem.

Contoh berikut menetapkan dua variabel lingkungan. ASPNETCORE_ENVIRONMENT mengonfigurasi lingkungan aplikasi ke Development. Pengembang dapat mengatur sementara nilai ini dalam web.config file untuk memaksa Halaman Pengecualian Pengembang dimuat saat menelusuri kesalahan pengecualian aplikasi. CONFIG_DIR adalah contoh variabel lingkungan yang ditentukan pengguna, di mana pengembang telah menulis kode yang membaca nilai pada startup untuk membentuk jalur untuk memuat file konfigurasi aplikasi.

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

Catatan

Alternatif untuk mengatur lingkungan secara langsung web.config adalah menyertakan <EnvironmentName> properti dalam profil penerbitan (.pubxml) atau file proyek. Pendekatan ini mengatur lingkungan saat web.config proyek diterbitkan:

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

Peringatan

Hanya atur ASPNETCORE_ENVIRONMENT variabel lingkungan ke Development pada pementasan dan pengujian server yang tidak dapat diakses oleh jaringan yang tidak tepercaya, seperti Internet.

app_offline.htm

Jika file dengan nama app_offline.htm terdeteksi di direktori akar aplikasi, modul ASP.NET Core mencoba mematikan aplikasi dengan lancar dan berhenti memproses permintaan masuk. Jika aplikasi masih berjalan setelah jumlah detik yang ditentukan dalam shutdownTimeLimit, Modul ASP.NET Core akan mematikan proses yang sedang berjalan.

app_offline.htm Saat file ada, ASP.NET Core Module merespons permintaan dengan mengirim kembali konten app_offline.htm file. app_offline.htm Saat file dihapus, permintaan berikutnya memulai aplikasi.

Saat menggunakan model hosting di luar proses, aplikasi mungkin tidak segera dimatikan jika ada koneksi terbuka. Misalnya, koneksi websocket dapat menunda aplikasi dimatikan.

Halaman kesalahan start-up

Hosting dalam proses dan di luar proses menghasilkan halaman kesalahan kustom ketika mereka gagal memulai aplikasi.

Jika Modul inti ASP.NET gagal menemukan penangan permintaan dalam proses atau di luar proses, kode status Kegagalan Beban Handler Dalam Proses/Di Luar Proses akan muncul.

Untuk hosting dalam proses jika Modul inti ASP.NET gagal memulai aplikasi, halaman kode status Kegagalan 500.30 - Mulai muncul.

Untuk hosting di luar proses jika Modul Inti ASP.NET gagal meluncurkan proses backend atau proses backend dimulai tetapi gagal mendengarkan port yang dikonfigurasi, halaman kode status Kegagalan Proses 502.5 muncul.

Untuk menekan halaman ini dan kembali ke halaman kode status IIS 5xx default, gunakan disableStartUpErrorPage atribut . Untuk informasi selengkapnya tentang mengonfigurasi pesan kesalahan kustom, lihat Kesalahan HTTP httpErrors><.

Pembuatan dan pengalihan log

Modul ASP.NET Core mengalihkan output konsol stdout dan stderr ke disk jika stdoutLogEnabled atribut aspNetCore dan stdoutLogFile elemen diatur. Folder apa pun di stdoutLogFile jalur dibuat oleh modul saat file log dibuat. Kumpulan aplikasi harus memiliki akses tulis ke lokasi tempat log ditulis (gunakan IIS AppPool\{APP POOL NAME} untuk memberikan izin tulis, di mana tempat penampung {APP POOL NAME} adalah nama kumpulan aplikasi).

Log tidak diputar, kecuali terjadi daur ulang/mulai ulang proses. Ini adalah tanggung jawab hoster untuk membatasi ruang disk yang digunakan log.

Menggunakan log stdout hanya disarankan untuk memecahkan masalah pengaktifan aplikasi saat menghosting di IIS atau saat menggunakan dukungan waktu pengembangan untuk IIS dengan Visual Studio, bukan saat men-debug secara lokal dan menjalankan aplikasi dengan IIS Express.

Jangan gunakan log stdout untuk tujuan pengelogan aplikasi umum. Untuk pengelogan rutin di aplikasi ASP.NET Core, gunakan pustaka pengelogan yang membatasi ukuran file log dan memutar log. Untuk informasi selengkapnya, lihat penyedia pengelogan pihak ketiga.

Tanda waktu dan ekstensi file ditambahkan secara otomatis saat file log dibuat. Nama file log terdiri dengan menambahkan tanda waktu, ID proses, dan ekstensi file (.log) ke segmen stdoutLogFile terakhir jalur (biasanya stdout) yang dibatasi oleh garis bawah. stdoutLogFile Jika jalur berakhir dengan stdout, log untuk aplikasi dengan PID 1934 yang dibuat pada 2/5/2018 pukul 19:42:32 memiliki nama stdout_20180205194132_1934.logfile .

Jika stdoutLogEnabled salah, kesalahan yang terjadi pada startup aplikasi diambil dan dipancarkan ke log peristiwa hingga 30 KB. Setelah startup, semua log tambahan dibuang.

Elemen sampel aspNetCore berikut mengonfigurasi pengelogan stdout di jalur .\log\relatif . Konfirmasikan bahwa pengguna identity kumpulan aplikasi memiliki izin untuk menulis ke jalur yang disediakan.

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

Saat menerbitkan aplikasi untuk penyebaran Azure App Service, Web SDK mengatur nilai ke stdoutLogFile \\?\%home%\LogFiles\stdout. Variabel %home lingkungan telah ditentukan sebelumnya untuk aplikasi yang dihosting oleh Azure App Service.

Untuk informasi selengkapnya tentang format jalur, lihat Format jalur file pada sistem Windows.

Log diagnostik yang ditingkatkan

Modul ASP.NET Core dapat dikonfigurasi untuk menyediakan log diagnostik yang ditingkatkan. <handlerSettings> Tambahkan elemen ke <aspNetCore> elemen di web.config. debugLevel Mengatur untuk mengekspos keakuratan TRACE informasi diagnostik yang lebih tinggi:

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

Folder di jalur yang disediakan untuk <handlerSetting> nilai (logs dalam contoh sebelumnya) tidak dibuat oleh modul secara otomatis dan harus ada sebelumnya dalam penyebaran. Kumpulan aplikasi harus memiliki akses tulis ke lokasi tempat log ditulis (gunakan IIS AppPool\{APP POOL NAME} untuk memberikan izin tulis, di mana tempat penampung {APP POOL NAME} adalah nama kumpulan aplikasi).

Nilai tingkat debug (debugLevel) dapat mencakup tingkat dan lokasi.

Tingkat (secara berurutan dari paling sedikit hingga paling verbose):

  • KESALAHAN
  • PERINGATAN
  • INFO
  • TRACE

Lokasi (beberapa lokasi diizinkan):

  • KONSOL
  • EVENTLOG
  • FILE

Pengaturan handler juga dapat disediakan melalui variabel lingkungan:

  • ASPNETCORE_MODULE_DEBUG_FILE: Jalur ke file log debug. (Default: aspnetcore-debug.log)
  • ASPNETCORE_MODULE_DEBUG: Pengaturan tingkat debug.

Peringatan

Jangan biarkan pengelogan debug diaktifkan dalam penyebaran lebih lama dari yang diperlukan untuk memecahkan masalah. Ukuran log tidak terbatas. Membiarkan log debug diaktifkan dapat menghabiskan ruang disk yang tersedia dan crash server atau layanan aplikasi.

Lihat Konfigurasi dengan web.config untuk contoh aspNetCore elemen dalam web.config file.

Konfigurasi proksi menggunakan protokol HTTP dan token pemasangan

Hanya berlaku untuk hosting di luar proses.

Proksi yang dibuat antara Modul ASP.NET Core dan Kestrel menggunakan protokol HTTP. Tidak ada risiko menguping lalu lintas antara modul dan Kestrel dari lokasi di luar server.

Token pemasangan digunakan untuk menjamin bahwa permintaan yang diterima oleh Kestrel diproksi oleh IIS dan tidak berasal dari beberapa sumber lain. Token pemasangan dibuat dan diatur ke dalam variabel lingkungan (ASPNETCORE_TOKEN) oleh modul. Token pemasangan juga diatur ke header (MS-ASPNETCORE-TOKEN) pada setiap permintaan yang diproksi. Middleware IIS memeriksa setiap permintaan yang diterimanya untuk mengonfirmasi bahwa nilai header token pemasangan cocok dengan nilai variabel lingkungan. Jika nilai token tidak cocok, permintaan dicatat dan ditolak. Variabel lingkungan token pemasangan dan lalu lintas antara modul dan Kestrel tidak dapat diakses dari lokasi di luar server. Tanpa mengetahui nilai token pemasangan, cyberattacker tidak dapat mengirimkan permintaan yang melewati pemeriksaan di Middleware IIS.

ASP.NET Modul Inti dengan Konfigurasi Bersama IIS

Penginstal Modul ASP.NET Core berjalan dengan hak istimewa TrustedInstaller akun. Karena akun sistem lokal tidak memiliki izin modifikasi untuk jalur berbagi yang digunakan oleh Konfigurasi Bersama IIS, penginstal melemparkan kesalahan akses yang ditolak saat mencoba mengonfigurasi pengaturan modul dalam applicationHost.config file pada berbagi.

Saat menggunakan Konfigurasi Bersama IIS pada komputer yang sama dengan penginstalan IIS, jalankan penginstal Bundel Hosting Inti ASP.NET dengan parameter yang OPT_NO_SHARED_CONFIG_CHECK diatur ke 1:

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

Saat jalur ke konfigurasi bersama tidak berada di komputer yang sama dengan penginstalan IIS, ikuti langkah-langkah berikut:

  1. Nonaktifkan Konfigurasi Bersama IIS.
  2. Jalankan alat penginstal.
  3. Ekspor file yang diperbarui applicationHost.config ke berbagi.
  4. Aktifkan kembali Konfigurasi Bersama IIS.

Versi modul dan log penginstal Bundel Hosting

Untuk menentukan versi Modul Inti ASP.NET yang diinstal:

  1. Pada sistem hosting, navigasikan ke %windir%\System32\inetsrv.
  2. aspnetcore.dll Temukan file.
  3. Klik kanan file dan pilih Properti dari menu kontekstual.
  4. Pilih tab Detail. Versi file dan Versi produk mewakili versi modul yang diinstal.

Log penginstal Bundel Hosting untuk modul ditemukan di C:\\Users\\%UserName%\\AppData\\Local\\Temp. File diberi nama dd_DotNetCoreWinSvrHosting__\{TIMESTAMP}_000_AspNetCoreModule_x64.log, di mana tempat penampung {TIMESTAMP} adalah tanda waktu.

Modul, skema, dan lokasi file konfigurasi

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

Skema

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

Konfigurasi

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

File dapat ditemukan dengan mencari aspnetcore dalam applicationHost.config file.

Modul ASP.NET Core (ANCM) adalah modul IIS asli yang dicolokkan ke alur IIS untuk meneruskan permintaan web ke backend ASP.NET aplikasi Core.

Versi Windows yang didukung:

  • Windows 7 atau yang lebih baru
  • Windows Server 2008 R2 atau yang lebih baru

Modul hanya berfungsi dengan Kestrel. Modul ini tidak kompatibel dengan HTTP.sys.

Karena aplikasi ASP.NET Core berjalan dalam proses yang terpisah dari proses pekerja IIS, modul juga menangani manajemen proses. Modul memulai proses untuk aplikasi ASP.NET Core saat permintaan pertama tiba dan memulai ulang aplikasi jika mengalami crash. Ini pada dasarnya adalah perilaku yang sama seperti yang terlihat dengan aplikasi ASP.NET 4.x yang berjalan dalam proses di IIS yang dikelola oleh Layanan Aktivasi Proses Windows (WAS).

Diagram berikut mengilustrasikan hubungan antara IIS, Modul Inti ASP.NET, dan aplikasi:

ASP.NET Core Module v2 13.1.19331.0

Permintaan datang dari web ke driver HTTP.sys mode kernel. Driver merutekan permintaan ke IIS pada port situs web yang dikonfigurasi, biasanya 80 (HTTP) atau 443 (HTTPS). Modul meneruskan permintaan ke Kestrel pada port acak untuk aplikasi, yang bukan port 80 atau 443.

Modul menentukan port melalui variabel lingkungan saat startup, dan Middleware Integrasi IIS mengonfigurasi server yang akan didengarkan di http://localhost:{port}. Pemeriksaan tambahan dilakukan, dan permintaan yang tidak berasal dari modul ditolak. Modul tidak mendukung penerusan HTTPS, jadi permintaan diteruskan melalui HTTP meskipun diterima oleh IIS melalui HTTPS.

Setelah Kestrel mengambil permintaan dari modul, permintaan didorong ke dalam alur middleware ASP.NET Core. Alur middleware menangani permintaan dan meneruskannya sebagai instans HttpContext ke logika aplikasi. Middleware yang ditambahkan oleh Integrasi IIS memperbarui skema, IP jarak jauh, dan basis jalur ke akun untuk meneruskan permintaan ke Kestrel. Respons aplikasi diteruskan kembali ke IIS, yang mendorongnya kembali ke klien HTTP yang menginisiasi permintaan.

Banyak modul asli, seperti Autentikasi Windows, tetap aktif. Untuk mempelajari selengkapnya tentang modul IIS yang aktif dengan modul ASP.NET Core, lihat Modul IIS dengan ASP.NET Core.

Modul ASP.NET Core juga dapat:

  • Atur variabel lingkungan untuk proses pekerja.
  • Log output stdout ke penyimpanan file untuk memecahkan masalah startup.
  • Teruskan token autentikasi Windows.

Cara menginstal dan menggunakan ASP.NET Core Module (ANCM)

Untuk petunjuk tentang cara menginstal Modul ASP.NET Core, lihat Menginstal .NET Core Hosting Bundle.

Konfigurasi dengan web.config

Modul ASP.NET Core dikonfigurasi dengan aspNetCore bagian simpul system.webServer dalam file web.config situs.

File web.config berikut diterbitkan untuk penyebaran yang bergantung pada kerangka kerja dan mengonfigurasi Modul Inti ASP.NET untuk menangani permintaan situs:

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

Web.config berikut diterbitkan untuk penyebaran mandiri:

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

Saat aplikasi disebarkan ke Azure App Service, stdoutLogFile jalur diatur ke \\?\%home%\LogFiles\stdout. Jalur menyimpan log stdout ke folder LogFiles , yang merupakan lokasi yang dibuat secara otomatis oleh layanan.

Untuk informasi tentang konfigurasi sub-aplikasi IIS, lihat Host ASP.NET Core di Windows dengan IIS.

Atribut elemen aspNetCore

Atribut Deskripsi Default
arguments

Atribut string opsional.

Argumen ke executable yang ditentukan dalam processPath.
disableStartUpErrorPage

Atribut Boolean opsional.

Jika true, halaman 502.5 - Kegagalan Proses ditekan, dan halaman kode status 502 yang dikonfigurasi di web.config lebih diutamakan.

 false
forwardWindowsAuthToken

Atribut Boolean opsional.

Jika true, token diteruskan ke proses turunan yang mendengarkan pada %ASPNETCORE_PORT% sebagai header 'MS-ASPNETCORE-WINAUTHTOKEN' per permintaan. Ini adalah tanggung jawab proses itu untuk memanggil CloseHandle pada token ini per permintaan.

 true
processesPerApplication

Atribut bilangan bulat opsional.

Menentukan jumlah instans proses yang ditentukan dalam pengaturan processPath yang dapat dipisahkan per aplikasi.

Pengaturan processesPerApplication tidak disarankan. Atribut ini akan dihapus dalam rilis mendatang.

 Default: 1
Min: 1
Maks: 100
processPath

Atribut string yang diperlukan.

Jalur ke executable yang meluncurkan proses mendengarkan permintaan HTTP. Jalur relatif didukung. Jika jalur dimulai dengan ., jalur dianggap relatif terhadap akar situs.
rapidFailsPerMinute

Atribut bilangan bulat opsional.

Menentukan berapa kali proses yang ditentukan dalam processPath diizinkan untuk crash per menit. Jika batas ini terlampaui, modul berhenti meluncurkan proses selama sisa menit.

 Default: 10
Min: 0
Maks: 100
requestTimeout

Atribut rentang waktu opsional.

Menentukan durasi di mana Modul ASP.NET Core menunggu respons dari proses yang mendengarkan pada %ASPNETCORE_PORT%.

Dalam versi Modul ASP.NET Core yang dikirim dengan rilis ASP.NET Core 2.1 atau yang lebih baru, requestTimeout ditentukan dalam jam, menit, dan detik.

 Default: 00:02:00
Min: 00:00:00
Maks: 360:00:00
shutdownTimeLimit

Atribut bilangan bulat opsional.

Durasi dalam hitungan detik bahwa modul menunggu executable dimatikan dengan lancar saat app_offline.htm file terdeteksi.

 Default: 10
Min: 0
Maks: 600
startupTimeLimit

Atribut bilangan bulat opsional.

Durasi dalam detik bahwa modul menunggu executable untuk memulai proses yang mendengarkan pada port. Jika batas waktu ini terlampaui, modul akan mematikan proses. Modul mencoba untuk meluncurkan kembali proses ketika menerima permintaan baru dan terus mencoba memulai ulang proses pada permintaan masuk berikutnya kecuali aplikasi gagal memulai rapidFailsPerMinute beberapa kali dalam menit bergulir terakhir.

Nilai 0 (nol) tidak dianggap sebagai batas waktu tak terbatas.

 Default: 120
Min: 0
Maks: 3600
stdoutLogEnabled

Atribut Boolean opsional.

Jika true, stdout dan stderr untuk proses yang ditentukan dalam processPath dialihkan ke file yang ditentukan dalam stdoutLogFile.

 false
stdoutLogFile

Atribut string opsional.

Menentukan jalur file relatif atau absolut tempat stdout dan stderr dari proses yang ditentukan dalam processPath dicatat. Jalur relatif relatif terhadap akar situs. Jalur apa pun yang dimulai . relatif terhadap akar situs dan semua jalur lainnya diperlakukan sebagai jalur absolut. Folder apa pun yang disediakan di jalur harus ada agar modul dapat membuat file log. Menggunakan pemisah garis bawah, tanda waktu, ID proses, dan ekstensi file (.log) ditambahkan ke segmen terakhir jalur stdoutLogFile . Jika .\logs\stdout disediakan sebagai nilai, contoh log stdout disimpan sebagai stdout_20180205194132_1934.log di folder log saat disimpan pada 2/5/2018 pukul 19:41:32 dengan ID proses 1934.

 aspnetcore-stdout

Pengaturan variabel lingkungan

Variabel lingkungan dapat ditentukan untuk proses dalam processPath atribut . Tentukan variabel lingkungan dengan <environmentVariable> elemen turunan dari <environmentVariables> elemen koleksi.

Peringatan

Variabel lingkungan yang diatur di bagian ini berkonflik dengan variabel lingkungan sistem yang diatur dengan nama yang sama. Jika variabel lingkungan diatur dalam file web.config dan pada tingkat sistem di Windows, nilai dari file web.config menjadi ditambahkan ke nilai variabel lingkungan sistem (misalnya, ASPNETCORE_ENVIRONMENT: Development;Development), yang mencegah aplikasi dimulai.

Contoh berikut menetapkan dua variabel lingkungan. ASPNETCORE_ENVIRONMENT mengonfigurasi lingkungan aplikasi ke Development. Pengembang dapat mengatur sementara nilai ini dalam file web.config untuk memaksa Halaman Pengecualian Pengembang dimuat saat men-debug pengecualian aplikasi. CONFIG_DIR adalah contoh variabel lingkungan yang ditentukan pengguna, di mana pengembang telah menulis kode yang membaca nilai pada startup untuk membentuk jalur untuk memuat file konfigurasi aplikasi.

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

Peringatan

Hanya atur ASPNETCORE_ENVIRONMENT variabel lingkungan ke Development pada pementasan dan pengujian server yang tidak dapat diakses oleh jaringan yang tidak tepercaya, seperti Internet.

app_offline.htm

Jika file dengan nama app_offline.htm terdeteksi di direktori akar aplikasi, modul ASP.NET Core mencoba mematikan aplikasi dengan lancar dan berhenti memproses permintaan masuk. Jika aplikasi masih berjalan setelah jumlah detik yang ditentukan dalam shutdownTimeLimit, Modul ASP.NET Core akan mematikan proses yang sedang berjalan.

app_offline.htm Saat file ada, ASP.NET Core Module merespons permintaan dengan mengirim kembali konten app_offline.htm file. app_offline.htm Saat file dihapus, permintaan berikutnya memulai aplikasi.

Halaman kesalahan start-up

Jika Modul ASP.NET Core gagal meluncurkan proses backend atau proses backend dimulai tetapi gagal mendengarkan port yang dikonfigurasi, halaman kode status Kegagalan Proses 502.5 muncul. Untuk menekan halaman ini dan kembali ke halaman kode status IIS 502 default, gunakan disableStartUpErrorPage atribut . Untuk informasi selengkapnya tentang mengonfigurasi pesan kesalahan kustom, lihat Kesalahan HTTP httpErrors><.

Pembuatan dan pengalihan log

Modul ASP.NET Core mengalihkan output konsol stdout dan stderr ke disk jika stdoutLogEnabled atribut aspNetCore dan stdoutLogFile elemen diatur. Folder apa pun di stdoutLogFile jalur dibuat oleh modul saat file log dibuat. Kumpulan aplikasi harus memiliki akses tulis ke lokasi tempat log ditulis (gunakan IIS AppPool\<app_pool_name> untuk memberikan izin tulis).

Log tidak diputar, kecuali terjadi daur ulang/mulai ulang proses. Ini adalah tanggung jawab hoster untuk membatasi ruang disk yang digunakan log.

Menggunakan log stdout hanya disarankan untuk memecahkan masalah pengaktifan aplikasi saat menghosting di IIS atau saat menggunakan dukungan waktu pengembangan untuk IIS dengan Visual Studio, bukan saat men-debug secara lokal dan menjalankan aplikasi dengan IIS Express.

Jangan gunakan log stdout untuk tujuan pengelogan aplikasi umum. Untuk pengelogan rutin di aplikasi ASP.NET Core, gunakan pustaka pengelogan yang membatasi ukuran file log dan memutar log. Untuk informasi selengkapnya, lihat penyedia pengelogan pihak ketiga.

Tanda waktu dan ekstensi file ditambahkan secara otomatis saat file log dibuat. Nama file log terdiri dengan menambahkan tanda waktu, ID proses, dan ekstensi file (.log) ke segmen stdoutLogFile terakhir jalur (biasanya stdout) yang dibatasi oleh garis bawah. stdoutLogFile Jika jalur berakhir dengan stdout, log untuk aplikasi dengan PID 1934 yang dibuat pada 2/5/2018 pukul 19:42:32 memiliki nama file stdout_20180205194132_1934.log.

Elemen sampel aspNetCore berikut mengonfigurasi pengelogan stdout di jalur .\log\relatif . Konfirmasikan bahwa pengguna identity AppPool memiliki izin untuk menulis ke jalur yang disediakan.

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

Saat menerbitkan aplikasi untuk penyebaran Azure App Service, Web SDK mengatur nilai ke stdoutLogFile \\?\%home%\LogFiles\stdout. Variabel %home lingkungan telah ditentukan sebelumnya untuk aplikasi yang dihosting oleh Azure App Service.

Untuk membuat aturan filter pengelogan, lihat bagian Terapkan aturan filter log di bagian kode dari dokumentasi pengelogan ASP.NET Core.

Untuk informasi selengkapnya tentang format jalur, lihat Format jalur file pada sistem Windows.

Konfigurasi proksi menggunakan protokol HTTP dan token pemasangan

Proksi yang dibuat antara Modul ASP.NET Core dan Kestrel menggunakan protokol HTTP. Tidak ada risiko menguping lalu lintas antara modul dan Kestrel dari lokasi di luar server.

Token pemasangan digunakan untuk menjamin bahwa permintaan yang diterima oleh Kestrel diproksi oleh IIS dan tidak berasal dari beberapa sumber lain. Token pemasangan dibuat dan diatur ke dalam variabel lingkungan (ASPNETCORE_TOKEN) oleh modul. Token pemasangan juga diatur ke header (MS-ASPNETCORE-TOKEN) pada setiap permintaan yang diproksi. Middleware IIS memeriksa setiap permintaan yang diterimanya untuk mengonfirmasi bahwa nilai header token pemasangan cocok dengan nilai variabel lingkungan. Jika nilai token tidak cocok, permintaan dicatat dan ditolak. Variabel lingkungan token pemasangan dan lalu lintas antara modul dan Kestrel tidak dapat diakses dari lokasi di luar server. Tanpa mengetahui nilai token pemasangan, cyberattacker tidak dapat mengirimkan permintaan yang melewati pemeriksaan di Middleware IIS.

ASP.NET Modul Inti dengan Konfigurasi Bersama IIS

Alat penginstal Modul Inti ASP.NET berjalan dengan hak istimewa akun TrustedInstaller . Karena akun sistem lokal tidak memiliki izin modifikasi untuk jalur berbagi yang digunakan oleh Konfigurasi Bersama IIS, alat penginstal melemparkan kesalahan akses yang ditolak saat mencoba mengonfigurasi pengaturan modul dalam file applicationHost.config pada berbagi.

Saat menggunakan Konfigurasi Bersama IIS, ikuti langkah-langkah berikut:

  1. Nonaktifkan Konfigurasi Bersama IIS.
  2. Jalankan alat penginstal.
  3. Ekspor file applicationHost.config yang diperbarui ke berbagi.
  4. Aktifkan kembali Konfigurasi Bersama IIS.

Versi modul dan log penginstal Bundel Hosting

Untuk menentukan versi Modul Inti ASP.NET yang diinstal:

  1. Pada sistem hosting, navigasikan ke %windir%\System32\inetsrv.
  2. Temukan file aspnetcore.dll.
  3. Klik kanan file dan pilih Properti dari menu kontekstual.
  4. Pilih tab Detail. Versi file dan Versi produk mewakili versi modul yang diinstal.

Log penginstal Bundel Hosting untuk modul ditemukan di C:\Users\%UserName%\AppData\Local\Temp. File diberi nama dd_DotNetCoreWinSvrHosting__<timestamp>_000_AspNetCoreModule_x64.log.

Modul, skema, dan lokasi file konfigurasi

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

Skema

IIS

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

IIS Express

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

Konfigurasi

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

File dapat ditemukan dengan mencari aspnetcore dalam file applicationHost.config .

Sumber Daya Tambahan: