ASP.NET Core Module (ANCM) cho IIS

ASP.NET Core Module (ANCM) là một native IIS module được tích hợp vào IIS pipeline, cho phép các ứng dụng ASP.NET Core hoạt động với IIS. Chạy các ứng dụng ASP.NET Core với IIS bằng cách:

• Host một ứng dụng ASP.NET Core bên trong IIS worker process (w3wp.exe), được gọi là mô hình hosting in-process.
• Chuyển tiếp các web request đến backend ASP.NET Core app chạy Kestrel server, được gọi là mô hình hosting out-of-process.

Có sự đánh đổi giữa mỗi mô hình hosting. Theo mặc định, mô hình hosting in-process được sử dụng do hiệu suất và chẩn đoán tốt hơn.

Cài đặt ASP.NET Core Module (ANCM)

ASP.NET Core Module (ANCM) được cài đặt cùng với .NET Core Runtime từ .NET Core Hosting Bundle. ASP.NET Core Module tương thích tiến và lùi với các phiên bản .NET được hỗ trợ.

Tải xuống installer bằng liên kết sau:

Installer .NET Core Hosting Bundle hiện tại (tải trực tiếp)

Cấu hình với web.config

ASP.NET Core Module được cấu hình với section aspNetCore của node system.webServer trong file web.config của site.

File web.config sau được publish cho framework-dependent deployment và cấu hình ASP.NET Core Module để xử lý các request của site:

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

File web.config sau được publish cho self-contained deployment:

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

Thuộc tính của phần tử aspNetCore

Đặt biến môi trường

Biến môi trường có thể được chỉ định cho process trong thuộc tính processPath. Chỉ định biến môi trường với phần tử con <environmentVariable> của phần tử collection <environmentVariables>. Biến môi trường được đặt trong section này có độ ưu tiên cao hơn biến môi trường hệ thống.

Ví dụ sau đặt hai biến môi trường trong web.config. ASPNETCORE_ENVIRONMENT cấu hình môi trường ứng dụng thành Development. Một developer có thể đặt tạm thời giá trị này trong file web.config để buộc Developer Exception Page tải khi debug exception của ứng dụng.

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

app_offline.htm

Nếu phát hiện file có tên app_offline.htm trong thư mục root của ứng dụng, ASP.NET Core Module sẽ cố gắng tắt gracefully ứng dụng và ngừng xử lý các request đến. Nếu ứng dụng vẫn đang chạy sau số giây được định nghĩa trong shutdownTimeLimit, ASP.NET Core Module sẽ kill running process.

Trong khi file app_offline.htm hiện diện, ASP.NET Core Module phản hồi các request bằng cách gửi lại nội dung của file app_offline.htm. Khi file app_offline.htm được xóa, request tiếp theo sẽ khởi động ứng dụng.

Trang lỗi khởi động

Cả in-process và out-of-process hosting đều tạo các trang lỗi tùy chỉnh khi chúng không thể khởi động ứng dụng.

• Nếu ASP.NET Core Module không tìm thấy request handler, trang mã trạng thái 500.0 - In-Process/Out-Of-Process Handler Load Failure xuất hiện.
• Đối với in-process hosting, nếu ASP.NET Core Module không khởi động được ứng dụng, trang 500.30 - Start Failure xuất hiện.
• Đối với out-of-process hosting, nếu module không thể khởi chạy backend process, trang 502.5 - Process Failure xuất hiện.

Tạo và chuyển hướng log

ASP.NET Core Module chuyển hướng stdout và stderr console output đến đĩa nếu các thuộc tính stdoutLogEnabled và stdoutLogFile của phần tử aspNetCore được đặt.

Chỉ khuyến khích sử dụng stdout log để khắc phục sự cố khởi động ứng dụng khi hosting trên IIS hoặc khi sử dụng development-time support cho IIS với Visual Studio.

Không sử dụng stdout log cho mục đích logging ứng dụng chung. Để logging định kỳ trong ứng dụng ASP.NET Core, hãy sử dụng thư viện logging giới hạn kích thước file log và xoay vòng log.

Enhanced diagnostic logs (Log chẩn đoán nâng cao)

ASP.NET Core Module có thể cấu hình để cung cấp enhanced diagnostic logs (log chẩn đoán nâng cao). Thêm phần tử <handlerSettings> vào phần tử <aspNetCore> trong web.config. Đặt debugLevel thành TRACE để hiển thị thông tin chẩn đoán với độ chính xác cao hơn:

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

Sửa đổi stack size

Chỉ áp dụng khi sử dụng mô hình hosting in-process.

Cấu hình managed stack size bằng cài đặt stackSize tính bằng byte trong web.config. Kích thước mặc định là 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>

Cấu hình proxy sử dụng giao thức HTTP và pairing token

Chỉ áp dụng cho out-of-process hosting.

Proxy được tạo giữa ASP.NET Core Module và Kestrel sử dụng giao thức HTTP. Không có rủi ro nghe lén lưu lượng giữa module và Kestrel từ vị trí bên ngoài server.

Một pairing token (mã ghép cặp) được sử dụng để đảm bảo rằng IIS đã proxy các request nhận được bởi Kestrel và không đến từ nguồn khác.

ASP.NET Core Module với IIS Shared Configuration

Installer ASP.NET Core Module chạy với đặc quyền của tài khoản TrustedInstaller. Vì tài khoản hệ thống local không có quyền sửa đổi cho share path được sử dụng bởi IIS Shared Configuration, installer ném lỗi access denied khi cố gắng cấu hình module settings trong file applicationHost.config trên share.

Khi sử dụng IIS Shared Configuration trên cùng máy với cài đặt IIS, chạy ASP.NET Core Hosting Bundle installer với tham số OPT_NO_SHARED_CONFIG_CHECK được đặt thành 1:

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

Vị trí file module, schema và cấu hình

Module

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

Schema

IIS

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

IIS Express

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

Cấu hình

IIS

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

IIS Express

• Visual Studio: {APPLICATION ROOT}\.vs\config\applicationHost.config
• CLI iisexpress.exe: %USERPROFILE%\Documents\IISExpress\config\applicationhost.config