How to install ASP.NET 1.1 with IIS7 on Vista and Windows 2008

Overview

You can use the Web Platform Installer (Web PI) to easily install IIS, and applications that run on IIS. The Web PI is a free, lightweight tool that lets you install IIS and related technologies such as ASP.NET, SQL Server Express, Visual Web Developer, other popular Web applications, and more. Because the Web PI references and links to the latest versions of available Web Platform offerings, with just a few simple clicks you can download and install any new tools or updates. To learn more about the Web PI, see Learn more and install the Web PI.

You can also install ASP.NET 2.0 (3.0 and 3.5) using the Windows Vista and Windows 2008 user interface — just install the ASP.NET component located under IIS->Word Wide Web Services->Application Development Features. You can find this set of components in Windows 2008 by clicking Start, and click Server Manager. Expand the left-hand treeview in Server Manager and click Manage Roles, and then Web Server (IIS). In the right-hand pane look for an option that says Add Role Services. If you’re on Windows Vista, click Start, click Control Panel, click Programs, and then Windows Features. Look for the following tree of features under Internet Information Services (IIS):

ASP.NET 1.1 is not included in Windows Vista or Windows 2008 and must be downloaded and installed manually. This post shows you how:

Step 1: Install «IIS Metabase Compatibility»

The IIS «Metabase compatibility» component is required to successfully install ASP.NET 1.1.

To install it on Windows 2008 Server, click Start, and click Server Manager. Expand the left-hand treeview in Server Manager and click Manage Roles, and then Web Server (IIS). In the right-hand pane look for an option that says Add Role Services. This takes you to wizard where you can install «IIS Metabase Compatibility».

If you’re on Windows Vista, click Start, click Control Panel, click Programs, and then Windows Features. Look for Internet Information Services (IIS) and install «IIS Metabase Compatibility».

Step 2: Install the .NET Framework v1.1 and .NET Framework v1.1 SP1

Install Framework v1.1, SP1, and ASP.NET’s security update to SP1:

When you install .NET Framework Version 1.1, and SP1 for .NET Framework Version 1.1, you’ll see the following dialog. Click Run program.

If you do not install Framework v1.1 SP1, you may run into Data Execution Prevention errors with messages like «IIS Worker Process has stopped working». This is expected. Installing .NET Framework v1.1 SP1 will fix this.

Step 3: Enable ASP.NET v1.1 ISAPI Extension

Enable ASP.NET v1.1 ISAPI as an allowed ISAPI extension. To do this, open «IIS Manager» administration tool. In the features view, click on the «ISAPI and CGI Restrictions» feature. In the actions pane, click «add»

Extension: C:\Windows\Microsoft.NET\Framework\v1.1.4322\aspnet\_isapi.dll (Note: change drive if your system drive is not C:) Description: ASP.NET v1.1

You can also do by running the following command line:

Using a C# Windows DLL in ASP.Net

I have a VS2012 Express (Desktop) MVVM project, where the Model (EF5 Code First) classes are stored in an independent C# DLL.

I am now planning on accessing parts of the same database over the internet using ASP.NET (with which I have much less experience than with programming for Windows). I am therefore creating an ASP.NET View which will use the same Model and VM.

Can I simply use the same DLL in my ASP.NET project, or am I more limited with the code that will run in ASP.NET compared with a Windows DLL?

2 Answers 2

Unless you’re running in Medium Trust (which is highly discouraged), code running in ASP.Net can load any DLL it wants. (including P/Invoke)
It’s all the same .Net; the only difference is whether it’s running in an interactive session or in IIS.

Note that running UI code will break things.

Using the same DLL from ASP.Net should not be a problem, But Im wondering how can you use the VideModel code in ASP.Net, None of the property change notification mechanism of ViewModel (Implementation of INotifyPropertyChanged) will not be supported in your ASP page.

Not the answer you’re looking for? Browse other questions tagged c# asp.net dll mvvm or ask your own question.

Linked

Related

Hot Network Questions

Subscribe to RSS

To subscribe to this RSS feed, copy and paste this URL into your RSS reader.

site design / logo © 2021 Stack Exchange Inc; user contributions licensed under cc by-sa. rev 2021.4.16.39093

By clicking “Accept all cookies”, you agree Stack Exchange can store cookies on your device and disclose information in accordance with our Cookie Policy.

Attach DLL to ASP.NET Site

How do you attach a dll to a asp.net site? I want to be able to debug and edit the dll without having to keep replacing the reference in my asp.net site. I checked attach to process but didn’t see the worker process. I am using asp.net, iis 7.

4 Answers 4

Just put it into /bin folder of your web application.

Add reference to this .dll by right clicking on References > Add Reference > Browse > Select your .dll file and lick OK.

Then set it’s «Copy Local» property to «True». This way .dll will be copied into /Bin folder each time you build application.

Using Visual Studio you should create a Solution that has your website as a project and the DLL (code) as another project. Make a reference in the Website project to the DLL project and it should update it automatically.

If you are not using the Web Application model and just the Website model you could just have your DLL project output to your website’s /bin directory directly. That will update the DLL in the website/bin folder whenever you build your DLL project.

If I could suggest, because I still use it, go to LearnVisualStudio.com and check out the free video’s.

If you want to edit the dll, open that project up in a second instance of Visual Studio and treat it like you would for any other project.

Set the reference in your /bin folder to the debug dll that the second Visual Studio creates.

I’m assuming you have Visual Studio.

If you’re just trying to add a dll, you can add a reference to it by right clicking on your website node and choosing «Add Reference. » . You will be able to debug the dll if you have its pdb along with it (to load the symbols from). You will NOT be able to edit the dll.

If the dll is in fact another project you have the source code for, just add the project to your solution, and from your website project add a reference from the «projects» tab. VS should add a reference and dependency so that it keeps the dll updated when you change code in your dll project.

Not the answer you’re looking for? Browse other questions tagged asp.net iis dll iis-7 or ask your own question.

Linked

Related

Hot Network Questions

Subscribe to RSS

To subscribe to this RSS feed, copy and paste this URL into your RSS reader.

site design / logo © 2021 Stack Exchange Inc; user contributions licensed under cc by-sa. rev 2021.4.16.39093

By clicking “Accept all cookies”, you agree Stack Exchange can store cookies on your device and disclose information in accordance with our Cookie Policy.

ASP.NET Core Module

The ASP.NET Core Module is a native IIS module that plugs into the IIS pipeline, allowing ASP.NET Core applications to work with IIS. Run ASP.NET Core apps with IIS by either:

• Hosting an ASP.NET Core app inside of the IIS worker process ( w3wp.exe ), called the in-process hosting model.
• Forwarding web requests to a backend ASP.NET Core app running the Kestrel server, called the out-of-process hosting model.

There are trade-offs between each of the hosting models. By default, the in-process hosting model is used due to better performance and diagnostics.

Install ASP.NET Core Module

The ASP.NET Core Module is installed with the .NET Core Runtime from the .NET Core Hosting Bundle. The ASP.NET Core Module is forward and backward compatible with LTS releases of .NET.

Breaking changes and security advisories are reported on the Announcements repo. Announcements can be limited to a specific version by selecting a Label filter.

Download the installer using the following link:

For more information, including installing an earlier version of the module, see Hosting Bundle.

For a tutorial experience on publishing an ASP.NET Core app to an IIS server, see Publish an ASP.NET Core app to IIS.

The ASP.NET Core Module is a native IIS module that plugs into the IIS pipeline to either:

• Host an ASP.NET Core app inside of the IIS worker process ( w3wp.exe ), called the in-process hosting model.
• Forward web requests to a backend ASP.NET Core app running the Kestrel server, called the out-of-process hosting model.

Supported Windows versions:

• Windows 7 or later
• Windows Server 2012 R2 or later

When hosting in-process, the module uses an in-process server implementation for IIS, called IIS HTTP Server ( IISHttpServer ).

When hosting out-of-process, the module only works with Kestrel. The module doesn’t function with HTTP.sys.

Hosting models

In-process hosting model

ASP.NET Core apps default to the in-process hosting model.

The following characteristics apply when hosting in-process:

IIS HTTP Server ( IISHttpServer ) is used instead of Kestrel server. For in-process, CreateDefaultBuilder calls UseIIS to:

• Register the IISHttpServer .
• Configure the port and base path the server should listen on when running behind the ASP.NET Core Module.
• Configure the host to capture startup errors.

The requestTimeout attribute doesn’t apply to in-process hosting.

Sharing an app pool among apps isn’t supported. Use one app pool per app.

When using Web Deploy or manually placing an app_offline.htm file in the deployment, the app might not shut down immediately if there’s an open connection. For example, a WebSocket connection may delay app shut down.

The architecture (bitness) of the app and installed runtime (x64 or x86) must match the architecture of the app pool.

Client disconnects are detected. The HttpContext.RequestAborted cancellation token is cancelled when the client disconnects.

In ASP.NET Core 2.2.1 or earlier, GetCurrentDirectory returns the worker directory of the process started by IIS rather than the app’s directory (for example, C:\Windows\System32\inetsrv for w3wp.exe ).

For sample code that sets the app’s current directory, see the CurrentDirectoryHelpers class. Call the SetCurrentDirectory method. Subsequent calls to GetCurrentDirectory provide the app’s directory.

When hosting in-process, AuthenticateAsync isn’t called internally to initialize a user. Therefore, an IClaimsTransformation implementation used to transform claims after every authentication isn’t activated by default. When transforming claims with an IClaimsTransformation implementation, call AddAuthentication to add authentication services:

Out-of-process hosting model

To configure an app for out-of-process hosting, set the value of the property to OutOfProcess in the project file ( .csproj ):

In-process hosting is set with InProcess , which is the default value.

Kestrel server is used instead of IIS HTTP Server ( IISHttpServer ).

• Configure the port and base path the server should listen on when running behind the ASP.NET Core Module.
• Configure the host to capture startup errors.

Hosting model changes

If the hostingModel setting is changed in the web.config file (explained in the Configuration with web.config section), the module recycles the worker process for IIS.

For IIS Express, the module doesn’t recycle the worker process but instead triggers a graceful shutdown of the current IIS Express process. The next request to the app spawns a new IIS Express process.

Process name

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

Many native modules, such as Windows Authentication, remain active. To learn more about IIS modules active with the ASP.NET Core Module, see IIS modules with ASP.NET Core.

The ASP.NET Core Module can also:

• Set environment variables for the worker process.
• Log stdout output to file storage for troubleshooting startup issues.
• Forward Windows authentication tokens.

How to install and use the ASP.NET Core Module

For instructions on how to install the ASP.NET Core Module, see Install the .NET Core Hosting Bundle. The ASP.NET Core Module is forward and backward compatible with LTS releases of .NET.

Breaking changes and security advisories are reported on the Announcements repo. Announcements can be limited to a specific version by selecting a Label filter.

Configuration with web.config

The ASP.NET Core Module is configured with the aspNetCore section of the system.webServer node in the site’s web.config file.

The following web.config file is published for a framework-dependent deployment and configures the ASP.NET Core Module to handle site requests:

The following web.config is published for a self-contained deployment:

The InheritInChildApplications property is set to false to indicate that the settings specified within the element aren’t inherited by apps that reside in a subdirectory of the app.

When an app is deployed to Azure App Service, the stdoutLogFile path is set to \\?\%home%\LogFiles\stdout . The path saves stdout logs to the LogFiles folder, which is a location automatically created by the service.

For information on IIS sub-application configuration, see Host ASP.NET Core on Windows with IIS.

Attributes of the aspNetCore element

Optional string attribute.

Arguments to the executable specified in processPath.

Optional Boolean attribute.

If true, the 502.5 — Process Failure page is suppressed, and the 502 status code page configured in the web.config takes precedence.

Optional Boolean attribute.

If true, the token is forwarded to the child process listening on %ASPNETCORE_PORT% as a header ‘MS-ASPNETCORE-WINAUTHTOKEN’ per request. It’s the responsibility of that process to call CloseHandle on this token per request.

Optional string attribute.

Specifies the hosting model as in-process ( InProcess / inprocess ) or out-of-process ( OutOfProcess / outofprocess ).

Optional integer attribute.

Specifies the number of instances of the process specified in the processPath setting that can be spun up per app.

†For in-process hosting, the value is limited to 1 .

Setting processesPerApplication is discouraged. This attribute will be removed in a future release.

Required string attribute.

Path to the executable that launches a process listening for HTTP requests. Relative paths are supported. If the path begins with . , the path is considered to be relative to the site root.

Optional integer attribute.

Specifies the number of times the process specified in processPath is allowed to crash per minute. If this limit is exceeded, the module stops launching the process for the remainder of the minute.

Not supported with in-process hosting.

Optional timespan attribute.

Specifies the duration for which the ASP.NET Core Module waits for a response from the process listening on %ASPNETCORE_PORT%.

In versions of the ASP.NET Core Module that shipped with the release of ASP.NET Core 2.1 or later, the requestTimeout is specified in hours, minutes, and seconds.

Doesn’t apply to in-process hosting. For in-process hosting, the module waits for the app to process the request.

Valid values for minutes and seconds segments of the string are in the range 0-59. Use of 60 in the value for minutes or seconds results in a 500 — Internal Server Error.

Optional integer attribute.

Duration in seconds that the module waits for the executable to gracefully shutdown when the app_offline.htm file is detected.

Optional integer attribute.

Duration in seconds that the module waits for the executable to start a process listening on the port. If this time limit is exceeded, the module kills the process.

When hosting in-process: The process is not restarted and does not use the rapidFailsPerMinute setting.

When hosting out-of-process: The module attempts to relaunch the process when it receives a new request and continues to attempt to restart the process on subsequent incoming requests unless the app fails to start rapidFailsPerMinute number of times in the last rolling minute.

A value of 0 (zero) is not considered an infinite timeout.

Optional Boolean attribute.

If true, stdout and stderr for the process specified in processPath are redirected to the file specified in stdoutLogFile.

Optional string attribute.

Specifies the relative or absolute file path for which stdout and stderr from the process specified in processPath are logged. Relative paths are relative to the root of the site. Any path starting with . are relative to the site root and all other paths are treated as absolute paths. Any folders provided in the path are created by the module when the log file is created. Using underscore delimiters, a timestamp, process ID, and file extension ( .log ) are added to the last segment of the stdoutLogFile path. If .\logs\stdout is supplied as a value, an example stdout log is saved as stdout_20180205194132_1934.log in the logs folder when saved on 2/5/2018 at 19:41:32 with a process ID of 1934.

Attribute	Description	Default
arguments	false
forwardWindowsAuthToken	InProcess inprocess
processesPerApplication	Default: 1 Min: 1 Max: 100 вЂ
processPath	Default: 10 Min: 0 Max: 100
requestTimeout	Default: 00:02:00 Min: 00:00:00 Max: 360:00:00
shutdownTimeLimit	Default: 10 Min: 0 Max: 600
startupTimeLimit	Default: 120 Min: 0 Max: 3600
stdoutLogEnabled	aspnetcore-stdout

Set environment variables

Environment variables can be specified for the process in the processPath attribute. Specify an environment variable with the child element of an collection element. Environment variables set in this section take precedence over system environment variables.

The following example sets two environment variables in web.config . ASPNETCORE_ENVIRONMENT configures the app’s environment to Development . A developer may temporarily set this value in the web.config file in order to force the Developer Exception Page to load when debugging an app exception. CONFIG_DIR is an example of a user-defined environment variable, where the developer has written code that reads the value on startup to form a path for loading the app’s configuration file.

An alternative to setting the environment directly in web.config is to include the property in the publish profile ( .pubxml ) or project file. This approach sets the environment in web.config when the project is published:

Only set the ASPNETCORE_ENVIRONMENT environment variable to Development on staging and testing servers that aren’t accessible to untrusted networks, such as the Internet.

app_offline.htm

If a file with the name app_offline.htm is detected in the root directory of an app, the ASP.NET Core Module attempts to gracefully shutdown the app and stop processing incoming requests. If the app is still running after the number of seconds defined in shutdownTimeLimit , the ASP.NET Core Module kills the running process.

While the app_offline.htm file is present, the ASP.NET Core Module responds to requests by sending back the contents of the app_offline.htm file. When the app_offline.htm file is removed, the next request starts the app.

When using the out-of-process hosting model, the app might not shut down immediately if there’s an open connection. For example, a WebSocket connection may delay app shut down.

Start-up error page

Both in-process and out-of-process hosting produce custom error pages when they fail to start the app.

If the ASP.NET Core Module fails to find either the in-process or out-of-process request handler, a 500.0 — In-Process/Out-Of-Process Handler Load Failure status code page appears.

For in-process hosting if the ASP.NET Core Module fails to start the app, a 500.30 — Start Failure status code page appears.

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

To suppress this page and revert to the default IIS 5xx status code page, use the disableStartUpErrorPage attribute. For more information on configuring custom error messages, see HTTP Errors .

Log creation and redirection

The ASP.NET Core Module redirects stdout and stderr console output to disk if the stdoutLogEnabled and stdoutLogFile attributes of the aspNetCore element are set. Any folders in the stdoutLogFile path are created by the module when the log file is created. The app pool must have write access to the location where the logs are written (use IIS AppPool\ to provide write permission).

Logs aren’t rotated, unless process recycling/restart occurs. It’s the responsibility of the hoster to limit the disk space the logs consume.

Using the stdout log is only recommended for troubleshooting app startup issues when hosting on IIS or when using development-time support for IIS with Visual Studio, not while debugging locally and running the app with IIS Express.

Don’t use the stdout log for general app logging purposes. For routine logging in an ASP.NET Core app, use a logging library that limits log file size and rotates logs. For more information, see third-party logging providers.

A timestamp and file extension are added automatically when the log file is created. The log file name is composed by appending the timestamp, process ID, and file extension ( .log ) to the last segment of the stdoutLogFile path (typically stdout ) delimited by underscores. If the stdoutLogFile path ends with stdout , a log for an app with a PID of 1934 created on 2/5/2018 at 19:42:32 has the file name stdout_20180205194132_1934.log .

If stdoutLogEnabled is false, errors that occur on app startup are captured and emitted to the event log up to 30 KB. After startup, all additional logs are discarded.

The following sample aspNetCore element configures stdout logging at the relative path .\log\ . Confirm that the AppPool user identity has permission to write to the path provided.

When publishing an app for Azure App Service deployment, the Web SDK sets the stdoutLogFile value to \\?\%home%\LogFiles\stdout . The %home environment variable is predefined for apps hosted by Azure App Service.

To create logging filter rules, see the Configuration and Log filtering sections of the ASP.NET Core logging documentation.

For more information on path formats, see File path formats on Windows systems.

Enhanced diagnostic logs

The ASP.NET Core Module is configurable to provide enhanced diagnostics logs. Add the element to the element in web.config . Setting the debugLevel to TRACE exposes a higher fidelity of diagnostic information:

Any folders in the path ( logs in the preceding example) are created by the module when the log file is created. The app pool must have write access to the location where the logs are written (use IIS AppPool\ , where the placeholder is the app pool name, to provide write permission).

Debug level ( debugLevel ) values can include both the level and the location.

Levels (in order from least to most verbose):

Locations (multiple locations are permitted):

The handler settings can also be provided via environment variables:

• ASPNETCORE_MODULE_DEBUG_FILE : Path to the debug log file. (Default: aspnetcore-debug.log )
• ASPNETCORE_MODULE_DEBUG : Debug level setting.

Do not leave debug logging enabled in the deployment for longer than required to troubleshoot an issue. The size of the log isn’t limited. Leaving the debug log enabled can exhaust the available disk space and crash the server or app service.

See Configuration with web.config for an example of the aspNetCore element in the web.config file.

Modify the stack size

Only applies when using the in-process hosting model.

Configure the managed stack size using the stackSize setting in bytes in web.config . The default size is 1,048,576 bytes (1 MB).

Proxy configuration uses HTTP protocol and a pairing token

Only applies to out-of-process hosting.

The proxy created between the ASP.NET Core Module and Kestrel uses the HTTP protocol. There’s no risk of eavesdropping the traffic between the module and Kestrel from a location off of the server.

A pairing token is used to guarantee that the requests received by Kestrel were proxied by IIS and didn’t come from some other source. The pairing token is created and set into an environment variable ( ASPNETCORE_TOKEN ) by the module. The pairing token is also set into a header ( MS-ASPNETCORE-TOKEN ) on every proxied request. IIS Middleware checks each request it receives to confirm that the pairing token header value matches the environment variable value. If the token values are mismatched, the request is logged and rejected. The pairing token environment variable and the traffic between the module and Kestrel aren’t accessible from a location off of the server. Without knowing the pairing token value, an attacker can’t submit requests that bypass the check in the IIS Middleware.

ASP.NET Core Module with an IIS Shared Configuration

The ASP.NET Core Module installer runs with the privileges of the TrustedInstaller account. Because the local system account doesn’t have modify permission for the share path used by the IIS Shared Configuration, the installer throws an access denied error when attempting to configure the module settings in the applicationHost.config file on the share.

When using an IIS Shared Configuration on the same machine as the IIS installation, run the ASP.NET Core Hosting Bundle installer with the OPT_NO_SHARED_CONFIG_CHECK parameter set to 1 :

When the path to the shared configuration isn’t on the same machine as the IIS installation, follow these steps:

1. Disable the IIS Shared Configuration.
2. Run the installer.
3. Export the updated applicationHost.config file to the share.
4. Re-enable the IIS Shared Configuration.

Module version and Hosting Bundle installer logs

To determine the version of the installed ASP.NET Core Module:

1. On the hosting system, navigate to %windir%\System32\inetsrv .
2. Locate the aspnetcore.dll file.
3. Right-click the file and select Properties from the contextual menu.
4. Select the Details tab. The File version and Product version represent the installed version of the module.

The Hosting Bundle installer logs for the module are found at C:\Users\%UserName%\AppData\Local\Temp . The file is named dd_DotNetCoreWinSvrHosting___000_AspNetCoreModule_x64.log .

Module, schema, and configuration file locations

Module

IIS (x86/amd64):

%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\Asp.Net Core Module\V2\aspnetcorev2.dll

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

Schema

IIS

IIS Express

Configuration

IIS

IIS Express

Visual Studio: \.vs\config\applicationHost.config

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

The files can be found by searching for aspnetcore in the applicationHost.config file.

The ASP.NET Core Module is a native IIS module that plugs into the IIS pipeline to either:

• Host an ASP.NET Core app inside of the IIS worker process ( w3wp.exe ), called the in-process hosting model.
• Forward web requests to a backend ASP.NET Core app running the Kestrel server, called the out-of-process hosting model.

Supported Windows versions:

• Windows 7 or later
• Windows Server 2008 R2 or later

When hosting in-process, the module uses an in-process server implementation for IIS, called IIS HTTP Server ( IISHttpServer ).

When hosting out-of-process, the module only works with Kestrel. The module doesn’t function with HTTP.sys.

Hosting models

In-process hosting model

The in-process hosting model isn’t supported for ASP.NET Core apps that target the .NET Framework.

The following characteristics apply when hosting in-process:

IIS HTTP Server ( IISHttpServer ) is used instead of Kestrel server. For in-process, CreateDefaultBuilder calls UseIIS to:

• Register the IISHttpServer .
• Configure the port and base path the server should listen on when running behind the ASP.NET Core Module.
• Configure the host to capture startup errors.

The requestTimeout attribute doesn’t apply to in-process hosting.

Sharing an app pool among apps isn’t supported. Use one app pool per app.

When using Web Deploy or manually placing an app_offline.htm file in the deployment, the app might not shut down immediately if there’s an open connection. For example, a websocket connection may delay app shut down.

The architecture (bitness) of the app and installed runtime (x64 or x86) must match the architecture of the app pool.

Client disconnects are detected. The HttpContext.RequestAborted cancellation token is cancelled when the client disconnects.

In ASP.NET Core 2.2.1 or earlier, GetCurrentDirectory returns the worker directory of the process started by IIS rather than the app’s directory (for example, C:\Windows\System32\inetsrv for w3wp.exe).

For sample code that sets the app’s current directory, see the CurrentDirectoryHelpers class. Call the SetCurrentDirectory method. Subsequent calls to GetCurrentDirectory provide the app’s directory.

When hosting in-process, AuthenticateAsync isn’t called internally to initialize a user. Therefore, an IClaimsTransformation implementation used to transform claims after every authentication isn’t activated by default. When transforming claims with an IClaimsTransformation implementation, call AddAuthentication to add authentication services:

Out-of-process hosting model

To configure an app for out-of-process hosting, use either of the following approaches in the project file:

The value is case insensitive, so inprocess and outofprocess are valid values.

Kestrel server is used instead of IIS HTTP Server ( IISHttpServer ).

• Configure the port and base path the server should listen on when running behind the ASP.NET Core Module.
• Configure the host to capture startup errors.

Hosting model changes

If the hostingModel setting is changed in the web.config file (explained in the Configuration with web.config section), the module recycles the worker process for IIS.

For IIS Express, the module doesn’t recycle the worker process but instead triggers a graceful shutdown of the current IIS Express process. The next request to the app spawns a new IIS Express process.

Process name

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

Many native modules, such as Windows Authentication, remain active. To learn more about IIS modules active with the ASP.NET Core Module, see IIS modules with ASP.NET Core.

The ASP.NET Core Module can also:

• Set environment variables for the worker process.
• Log stdout output to file storage for troubleshooting startup issues.
• Forward Windows authentication tokens.

How to install and use the ASP.NET Core Module

For instructions on how to install the ASP.NET Core Module, see Install the .NET Core Hosting Bundle. The ASP.NET Core Module is forward and backward compatible with LTS releases of .NET.

Breaking changes and security advisories are reported on the Announcements repo. Announcements can be limited to a specific version by selecting a Label filter.

Configuration with web.config

The ASP.NET Core Module is configured with the aspNetCore section of the system.webServer node in the site’s web.config file.

The following web.config file is published for a framework-dependent deployment and configures the ASP.NET Core Module to handle site requests:

The following web.config is published for a self-contained deployment:

The InheritInChildApplications property is set to false to indicate that the settings specified within the element aren’t inherited by apps that reside in a subdirectory of the app.

When an app is deployed to Azure App Service, the stdoutLogFile path is set to \\?\%home%\LogFiles\stdout . The path saves stdout logs to the LogFiles folder, which is a location automatically created by the service.

For information on IIS sub-application configuration, see Host ASP.NET Core on Windows with IIS.

Attributes of the aspNetCore element

Optional string attribute.

Arguments to the executable specified in processPath .

Optional Boolean attribute.

If true, the 502.5 — Process Failure page is suppressed, and the 502 status code page configured in the web.config takes precedence.

Optional Boolean attribute.

If true, the token is forwarded to the child process listening on %ASPNETCORE_PORT% as a header ‘MS-ASPNETCORE-WINAUTHTOKEN’ per request. It’s the responsibility of that process to call CloseHandle on this token per request.

Optional string attribute.

Specifies the hosting model as in-process ( InProcess / inprocess ) or out-of-process ( OutOfProcess / outofprocess ).

Optional integer attribute.

Specifies the number of instances of the process specified in the processPath setting that can be spun up per app.

†For in-process hosting, the value is limited to 1 .

Setting processesPerApplication is discouraged. This attribute will be removed in a future release.

Required string attribute.

Path to the executable that launches a process listening for HTTP requests. Relative paths are supported. If the path begins with . , the path is considered to be relative to the site root.

Optional integer attribute.

Specifies the number of times the process specified in processPath is allowed to crash per minute. If this limit is exceeded, the module stops launching the process for the remainder of the minute.

Not supported with in-process hosting.

Optional timespan attribute.

Specifies the duration for which the ASP.NET Core Module waits for a response from the process listening on %ASPNETCORE_PORT%.

In versions of the ASP.NET Core Module that shipped with the release of ASP.NET Core 2.1 or later, the requestTimeout is specified in hours, minutes, and seconds.

Doesn’t apply to in-process hosting. For in-process hosting, the module waits for the app to process the request.

Valid values for minutes and seconds segments of the string are in the range 0-59. Use of 60 in the value for minutes or seconds results in a 500 — Internal Server Error.

Optional integer attribute.

Duration in seconds that the module waits for the executable to gracefully shutdown when the app_offline.htm file is detected.

Optional integer attribute.

Duration in seconds that the module waits for the executable to start a process listening on the port. If this time limit is exceeded, the module kills the process.

When hosting in-process: The process is not restarted and does not use the rapidFailsPerMinute setting.

When hosting out-of-process: The module attempts to relaunch the process when it receives a new request and continues to attempt to restart the process on subsequent incoming requests unless the app fails to start rapidFailsPerMinute number of times in the last rolling minute.

A value of 0 (zero) is not considered an infinite timeout.

Optional Boolean attribute.

If true, stdout and stderr for the process specified in processPath are redirected to the file specified in stdoutLogFile.

Optional string attribute.

Specifies the relative or absolute file path for which stdout and stderr from the process specified in processPath are logged. Relative paths are relative to the root of the site. Any path starting with . are relative to the site root and all other paths are treated as absolute paths. Any folders provided in the path are created by the module when the log file is created. Using underscore delimiters, a timestamp, process ID, and file extension ( .log ) are added to the last segment of the stdoutLogFile path. If .\logs\stdout is supplied as a value, an example stdout log is saved as stdout_20180205194132_1934.log in the logs folder when saved on 2/5/2018 at 19:41:32 with a process ID of 1934.

Attribute	Description	Default
arguments	false
forwardWindowsAuthToken	OutOfProcess outofprocess
processesPerApplication	Default: 1 Min: 1 Max: 100 вЂ
processPath	Default: 10 Min: 0 Max: 100
requestTimeout	Default: 00:02:00 Min: 00:00:00 Max: 360:00:00
shutdownTimeLimit	Default: 10 Min: 0 Max: 600
startupTimeLimit	Default: 120 Min: 0 Max: 3600
stdoutLogEnabled	aspnetcore-stdout

Setting environment variables

Environment variables can be specified for the process in the processPath attribute. Specify an environment variable with the child element of an collection element. Environment variables set in this section take precedence over system environment variables.

The following example sets two environment variables. ASPNETCORE_ENVIRONMENT configures the app’s environment to Development . A developer may temporarily set this value in the web.config file in order to force the Developer Exception Page to load when debugging an app exception. CONFIG_DIR is an example of a user-defined environment variable, where the developer has written code that reads the value on startup to form a path for loading the app’s configuration file.

An alternative to setting the environment directly in web.config is to include the property in the publish profile (.pubxml) or project file. This approach sets the environment in web.config when the project is published:

Only set the ASPNETCORE_ENVIRONMENT environment variable to Development on staging and testing servers that aren’t accessible to untrusted networks, such as the Internet.

app_offline.htm

If a file with the name app_offline.htm is detected in the root directory of an app, the ASP.NET Core Module attempts to gracefully shutdown the app and stop processing incoming requests. If the app is still running after the number of seconds defined in shutdownTimeLimit , the ASP.NET Core Module kills the running process.

While the app_offline.htm file is present, the ASP.NET Core Module responds to requests by sending back the contents of the app_offline.htm file. When the app_offline.htm file is removed, the next request starts the app.

When using the out-of-process hosting model, the app might not shut down immediately if there’s an open connection. For example, a websocket connection may delay app shut down.

Start-up error page

Both in-process and out-of-process hosting produce custom error pages when they fail to start the app.

If the ASP.NET Core Module fails to find either the in-process or out-of-process request handler, a 500.0 — In-Process/Out-Of-Process Handler Load Failure status code page appears.

For in-process hosting if the ASP.NET Core Module fails to start the app, a 500.30 — Start Failure status code page appears.

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

To suppress this page and revert to the default IIS 5xx status code page, use the disableStartUpErrorPage attribute. For more information on configuring custom error messages, see HTTP Errors .

Log creation and redirection

The ASP.NET Core Module redirects stdout and stderr console output to disk if the stdoutLogEnabled and stdoutLogFile attributes of the aspNetCore element are set. Any folders in the stdoutLogFile path are created by the module when the log file is created. The app pool must have write access to the location where the logs are written (use IIS AppPool\ to provide write permission, where the placeholder is the app pool name).

Logs aren’t rotated, unless process recycling/restart occurs. It’s the responsibility of the hoster to limit the disk space the logs consume.

Using the stdout log is only recommended for troubleshooting app startup issues when hosting on IIS or when using development-time support for IIS with Visual Studio, not while debugging locally and running the app with IIS Express.

Don’t use the stdout log for general app logging purposes. For routine logging in an ASP.NET Core app, use a logging library that limits log file size and rotates logs. For more information, see third-party logging providers.

A timestamp and file extension are added automatically when the log file is created. The log file name is composed by appending the timestamp, process ID, and file extension ( .log ) to the last segment of the stdoutLogFile path (typically stdout ) delimited by underscores. If the stdoutLogFile path ends with stdout , a log for an app with a PID of 1934 created on 2/5/2018 at 19:42:32 has the file name stdout_20180205194132_1934.log .

If stdoutLogEnabled is false, errors that occur on app startup are captured and emitted to the event log up to 30 KB. After startup, all additional logs are discarded.

The following sample aspNetCore element configures stdout logging at the relative path .\log\ . Confirm that the app pool user identity has permission to write to the path provided.

When publishing an app for Azure App Service deployment, the Web SDK sets the stdoutLogFile value to \\?\%home%\LogFiles\stdout . The %home environment variable is predefined for apps hosted by Azure App Service.

For more information on path formats, see File path formats on Windows systems.

Enhanced diagnostic logs

The ASP.NET Core Module is configurable to provide enhanced diagnostics logs. Add the element to the element in web.config . Setting the debugLevel to TRACE exposes a higher fidelity of diagnostic information:

Folders in the path provided to the value ( logs in the preceding example) aren’t created by the module automatically and should pre-exist in the deployment. The app pool must have write access to the location where the logs are written (use IIS AppPool\ to provide write permission, where the placeholder is the app pool name).

Debug level ( debugLevel ) values can include both the level and the location.

Levels (in order from least to most verbose):

Locations (multiple locations are permitted):

The handler settings can also be provided via environment variables:

• ASPNETCORE_MODULE_DEBUG_FILE : Path to the debug log file. (Default: aspnetcore-debug.log )
• ASPNETCORE_MODULE_DEBUG : Debug level setting.

Do not leave debug logging enabled in the deployment for longer than required to troubleshoot an issue. The size of the log isn’t limited. Leaving the debug log enabled can exhaust the available disk space and crash the server or app service.

See Configuration with web.config for an example of the aspNetCore element in the web.config file.

Proxy configuration uses HTTP protocol and a pairing token

Only applies to out-of-process hosting.

The proxy created between the ASP.NET Core Module and Kestrel uses the HTTP protocol. There’s no risk of eavesdropping the traffic between the module and Kestrel from a location off of the server.

A pairing token is used to guarantee that the requests received by Kestrel were proxied by IIS and didn’t come from some other source. The pairing token is created and set into an environment variable ( ASPNETCORE_TOKEN ) by the module. The pairing token is also set into a header ( MS-ASPNETCORE-TOKEN ) on every proxied request. IIS Middleware checks each request it receives to confirm that the pairing token header value matches the environment variable value. If the token values are mismatched, the request is logged and rejected. The pairing token environment variable and the traffic between the module and Kestrel aren’t accessible from a location off of the server. Without knowing the pairing token value, an attacker can’t submit requests that bypass the check in the IIS Middleware.

ASP.NET Core Module with an IIS Shared Configuration

The ASP.NET Core Module installer runs with the privileges of the TrustedInstaller account. Because the local system account doesn’t have modify permission for the share path used by the IIS Shared Configuration, the installer throws an access denied error when attempting to configure the module settings in the applicationHost.config file on the share.

When using an IIS Shared Configuration on the same machine as the IIS installation, run the ASP.NET Core Hosting Bundle installer with the OPT_NO_SHARED_CONFIG_CHECK parameter set to 1 :

When the path to the shared configuration isn’t on the same machine as the IIS installation, follow these steps:

1. Disable the IIS Shared Configuration.
2. Run the installer.
3. Export the updated applicationHost.config file to the share.
4. Re-enable the IIS Shared Configuration.

Module version and Hosting Bundle installer logs

To determine the version of the installed ASP.NET Core Module:

1. On the hosting system, navigate to %windir%\System32\inetsrv .
2. Locate the aspnetcore.dll file.
3. Right-click the file and select Properties from the contextual menu.
4. Select the Details tab. The File version and Product version represent the installed version of the module.

The Hosting Bundle installer logs for the module are found at C:\\Users\\%UserName%\\AppData\\Local\\Temp . The file is named dd_DotNetCoreWinSvrHosting__\_000_AspNetCoreModule_x64.log , where the placeholder is the timestamp.

Module, schema, and configuration file locations

Module

IIS (x86/amd64):

%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\Asp.Net Core Module\V2\aspnetcorev2.dll

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

Schema

IIS

IIS Express

Configuration

IIS

IIS Express

Visual Studio: \.vs\config\applicationHost.config

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

The files can be found by searching for aspnetcore in the applicationHost.config file.

The ASP.NET Core Module is a native IIS module that plugs into the IIS pipeline to forward web requests to backend ASP.NET Core apps.

Supported Windows versions:

• Windows 7 or later
• Windows Server 2008 R2 or later

The module only works with Kestrel. The module is incompatible with HTTP.sys.

Because ASP.NET Core apps run in a process separate from the IIS worker process, the module also handles process management. The module starts the process for the ASP.NET Core app when the first request arrives and restarts the app if it crashes. This is essentially the same behavior as seen with ASP.NET 4.x apps that run in-process in IIS that are managed by the Windows Process Activation Service (WAS).

The following diagram illustrates the relationship between IIS, the ASP.NET Core Module, and an app:

Requests arrive from the web to the kernel-mode HTTP.sys driver. The driver routes the requests to IIS on the website’s configured port, usually 80 (HTTP) or 443 (HTTPS). The module forwards the requests to Kestrel on a random port for the app, which isn’t port 80 or 443.

The module specifies the port via an environment variable at startup, and the IIS Integration Middleware configures the server to listen on http://localhost: . Additional checks are performed, and requests that don’t originate from the module are rejected. The module doesn’t support HTTPS forwarding, so requests are forwarded over HTTP even if received by IIS over HTTPS.

After Kestrel picks up the request from the module, the request is pushed into the ASP.NET Core middleware pipeline. The middleware pipeline handles the request and passes it on as an HttpContext instance to the app’s logic. Middleware added by IIS Integration updates the scheme, remote IP, and pathbase to account for forwarding the request to Kestrel. The app’s response is passed back to IIS, which pushes it back out to the HTTP client that initiated the request.

Many native modules, such as Windows Authentication, remain active. To learn more about IIS modules active with the ASP.NET Core Module, see IIS modules with ASP.NET Core.

The ASP.NET Core Module can also:

• Set environment variables for the worker process.
• Log stdout output to file storage for troubleshooting startup issues.
• Forward Windows authentication tokens.

How to install and use the ASP.NET Core Module

For instructions on how to install the ASP.NET Core Module, see Install the .NET Core Hosting Bundle.

Configuration with web.config

The ASP.NET Core Module is configured with the aspNetCore section of the system.webServer node in the site’s web.config file.

The following web.config file is published for a framework-dependent deployment and configures the ASP.NET Core Module to handle site requests:

The following web.config is published for a self-contained deployment:

When an app is deployed to Azure App Service, the stdoutLogFile path is set to \\?\%home%\LogFiles\stdout . The path saves stdout logs to the LogFiles folder, which is a location automatically created by the service.

For information on IIS sub-application configuration, see Host ASP.NET Core on Windows with IIS.

Attributes of the aspNetCore element

Optional string attribute.

Arguments to the executable specified in processPath.

Optional Boolean attribute.

If true, the 502.5 — Process Failure page is suppressed, and the 502 status code page configured in the web.config takes precedence.

Optional Boolean attribute.

If true, the token is forwarded to the child process listening on %ASPNETCORE_PORT% as a header ‘MS-ASPNETCORE-WINAUTHTOKEN’ per request. It’s the responsibility of that process to call CloseHandle on this token per request.

Optional integer attribute.

Specifies the number of instances of the process specified in the processPath setting that can be spun up per app.

Setting processesPerApplication is discouraged. This attribute will be removed in a future release.

Required string attribute.

Path to the executable that launches a process listening for HTTP requests. Relative paths are supported. If the path begins with . , the path is considered to be relative to the site root.

Optional integer attribute.

Specifies the number of times the process specified in processPath is allowed to crash per minute. If this limit is exceeded, the module stops launching the process for the remainder of the minute.

Optional timespan attribute.

Specifies the duration for which the ASP.NET Core Module waits for a response from the process listening on %ASPNETCORE_PORT%.

In versions of the ASP.NET Core Module that shipped with the release of ASP.NET Core 2.1 or later, the requestTimeout is specified in hours, minutes, and seconds.

Optional integer attribute.

Duration in seconds that the module waits for the executable to gracefully shutdown when the app_offline.htm file is detected.

Optional integer attribute.

Duration in seconds that the module waits for the executable to start a process listening on the port. If this time limit is exceeded, the module kills the process. The module attempts to relaunch the process when it receives a new request and continues to attempt to restart the process on subsequent incoming requests unless the app fails to start rapidFailsPerMinute number of times in the last rolling minute.

A value of 0 (zero) is not considered an infinite timeout.

Optional Boolean attribute.

If true, stdout and stderr for the process specified in processPath are redirected to the file specified in stdoutLogFile.

Optional string attribute.

Specifies the relative or absolute file path for which stdout and stderr from the process specified in processPath are logged. Relative paths are relative to the root of the site. Any path starting with . are relative to the site root and all other paths are treated as absolute paths. Any folders provided in the path must exist in order for the module to create the log file. Using underscore delimiters, a timestamp, process ID, and file extension (.log) are added to the last segment of the stdoutLogFile path. If .\logs\stdout is supplied as a value, an example stdout log is saved as stdout_20180205194132_1934.log in the logs folder when saved on 2/5/2018 at 19:41:32 with a process ID of 1934.

Attribute	Description	Default
arguments	false
forwardWindowsAuthToken	true
processesPerApplication	Default: 1 Min: 1 Max: 100
processPath	Default: 10 Min: 0 Max: 100
requestTimeout	Default: 00:02:00 Min: 00:00:00 Max: 360:00:00
shutdownTimeLimit	Default: 10 Min: 0 Max: 600
startupTimeLimit	Default: 120 Min: 0 Max: 3600
stdoutLogEnabled	aspnetcore-stdout

Setting environment variables

Environment variables can be specified for the process in the processPath attribute. Specify an environment variable with the child element of an collection element.

Environment variables set in this section conflict with system environment variables set with the same name. If an environment variable is set in both the web.config file and at the system level in Windows, the value from the web.config file becomes appended to the system environment variable value (for example, ASPNETCORE_ENVIRONMENT: Development;Development ), which prevents the app from starting.

The following example sets two environment variables. ASPNETCORE_ENVIRONMENT configures the app’s environment to Development . A developer may temporarily set this value in the web.config file in order to force the Developer Exception Page to load when debugging an app exception. CONFIG_DIR is an example of a user-defined environment variable, where the developer has written code that reads the value on startup to form a path for loading the app’s configuration file.

Only set the ASPNETCORE_ENVIRONMENT environment variable to Development on staging and testing servers that aren’t accessible to untrusted networks, such as the Internet.

app_offline.htm

If a file with the name app_offline.htm is detected in the root directory of an app, the ASP.NET Core Module attempts to gracefully shutdown the app and stop processing incoming requests. If the app is still running after the number of seconds defined in shutdownTimeLimit , the ASP.NET Core Module kills the running process.

While the app_offline.htm file is present, the ASP.NET Core Module responds to requests by sending back the contents of the app_offline.htm file. When the app_offline.htm file is removed, the next request starts the app.

Start-up error page

If the ASP.NET Core Module fails to launch the backend process or the backend process starts but fails to listen on the configured port, a 502.5 — Process Failure status code page appears. To suppress this page and revert to the default IIS 502 status code page, use the disableStartUpErrorPage attribute. For more information on configuring custom error messages, see HTTP Errors .

Log creation and redirection

The ASP.NET Core Module redirects stdout and stderr console output to disk if the stdoutLogEnabled and stdoutLogFile attributes of the aspNetCore element are set. Any folders in the stdoutLogFile path are created by the module when the log file is created. The app pool must have write access to the location where the logs are written (use IIS AppPool\ to provide write permission).

Logs aren’t rotated, unless process recycling/restart occurs. It’s the responsibility of the hoster to limit the disk space the logs consume.

Using the stdout log is only recommended for troubleshooting app startup issues when hosting on IIS or when using development-time support for IIS with Visual Studio, not while debugging locally and running the app with IIS Express.

Don’t use the stdout log for general app logging purposes. For routine logging in an ASP.NET Core app, use a logging library that limits log file size and rotates logs. For more information, see third-party logging providers.

A timestamp and file extension are added automatically when the log file is created. The log file name is composed by appending the timestamp, process ID, and file extension (.log) to the last segment of the stdoutLogFile path (typically stdout) delimited by underscores. If the stdoutLogFile path ends with stdout, a log for an app with a PID of 1934 created on 2/5/2018 at 19:42:32 has the file name stdout_20180205194132_1934.log.

The following sample aspNetCore element configures stdout logging at the relative path .\log\ . Confirm that the AppPool user identity has permission to write to the path provided.

When publishing an app for Azure App Service deployment, the Web SDK sets the stdoutLogFile value to \\?\%home%\LogFiles\stdout . The %home environment variable is predefined for apps hosted by Azure App Service.

To create logging filter rules, see the Configuration and Log filtering sections of the ASP.NET Core logging documentation.

For more information on path formats, see File path formats on Windows systems.

Proxy configuration uses HTTP protocol and a pairing token

The proxy created between the ASP.NET Core Module and Kestrel uses the HTTP protocol. There’s no risk of eavesdropping the traffic between the module and Kestrel from a location off of the server.

A pairing token is used to guarantee that the requests received by Kestrel were proxied by IIS and didn’t come from some other source. The pairing token is created and set into an environment variable ( ASPNETCORE_TOKEN ) by the module. The pairing token is also set into a header ( MS-ASPNETCORE-TOKEN ) on every proxied request. IIS Middleware checks each request it receives to confirm that the pairing token header value matches the environment variable value. If the token values are mismatched, the request is logged and rejected. The pairing token environment variable and the traffic between the module and Kestrel aren’t accessible from a location off of the server. Without knowing the pairing token value, an attacker can’t submit requests that bypass the check in the IIS Middleware.

ASP.NET Core Module with an IIS Shared Configuration

The ASP.NET Core Module installer runs with the privileges of the TrustedInstaller account. Because the local system account doesn’t have modify permission for the share path used by the IIS Shared Configuration, the installer throws an access denied error when attempting to configure the module settings in the applicationHost.config file on the share.

When using an IIS Shared Configuration, follow these steps:

1. Disable the IIS Shared Configuration.
2. Run the installer.
3. Export the updated applicationHost.config file to the share.
4. Re-enable the IIS Shared Configuration.

Module version and Hosting Bundle installer logs

To determine the version of the installed ASP.NET Core Module:

1. On the hosting system, navigate to %windir%\System32\inetsrv.
2. Locate the aspnetcore.dll file.
3. Right-click the file and select Properties from the contextual menu.
4. Select the Details tab. The File version and Product version represent the installed version of the module.

The Hosting Bundle installer logs for the module are found at C:\Users\%UserName%\AppData\Local\Temp. The file is named dd_DotNetCoreWinSvrHosting__ _000_AspNetCoreModule_x64.log.