.NET Core Workers as Windows Services

March 29th, 2019

In .NET Core 3.0 we are introducing a new type of application template called Worker Service. This template is intended to give you a starting point for writing long running services in .NET Core. In this walkthrough we will create a worker and run it as a Windows Service.

Create a worker

Preview Note: In our preview releases the worker template is in the same menu as the Web templates. This will change in a future release. We intend to place the Worker Service template directly inside the create new project wizard.

Create a Worker in Visual Studio

Create a Worker on the command line

Run dotnet new worker

Run as a Windows Service

In order to run as a Windows Service we need our worker to listen for start and stop signals from ServiceBase the .NET type that exposes the Windows Service systems to .NET applications. To do this we want to:

Add the Microsoft.Extensions.Hosting.WindowsServices NuGet package

Add the UseServiceBaseLifetime call to the HostBuilder in our Program.cs

This method does a couple of things. First, it checks whether or not the application is actually running as a Windows Service, if it isn’t then it noops which makes this method safe to be called when running locally or when running as a Windows Service. You don’t need to add guard clauses to it and can just run the app normally when not installed as a Windows Service.

Secondly, it configures your host to use a ServiceBaseLifetime . ServiceBaseLifetime works with ServiceBase to help control the lifetime of your app when run as a Windows Service. This overrides the default ConsoleLifetime that handles signals like CTL+C.

Install the Worker

Once we have our worker using the ServiceBaseLifetime we then need to install it:

First, lets publish the application. We will install the Windows Service in-place, meaning the exe will be locked whenever the service is running. The publish step is a nice way to make sure all the files I need to run the service are in one place and ready to be installed.

Then we can use the sc utility in an admin command prompt

Security note: This command has the service run as local system, which isn’t something you will generally want to do. Instead you should create a service account and run the windows service as that account. We will not talk about that here, but there is some documentation on the ASP.NET docs talking about it here: https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy/windows-service?view=aspnetcore-2.2

Logging

The logging system has an Event Log provider that can send log message directly to the Windows Event Log. To log to the event log you can add the Microsoft.Extensions.Logging.EventLog package and then modify your Program.cs :

Future Work

In upcoming previews we plan to improve the experience of using Workers with Windows Services by:

1. Rename UseWindowsServiceBaseLifetime to UseWindowsService
2. Add automatic and improved integration with the Event Log when running as a Windows Service.

Conclusion

We hope you try out this new template and want you to let us know how it goes, you can file any bugs or suggestions here.

Running ASP.NET Core application as Windows service

ASP.NET Core 2.1 introduces new application host for Windows services. We can now run ASP.NET Core applications as Windows services with minimal effort. This blog post introduces how it is done and how to build and run Windows services on ASP.NET Core without any need for dirty hacks.

Creating default web application

We start with new default ASP.NET Core 2.1 web application.

I don’t configure HTTPS at this moment as this is sample application and it does nothing important.

By deafult Program class looks like this.

Now we have working default application and it’s time to focus to Windows service.

Running ASP.NET Core application as Windows service

Running application as Windows service takes some effort before we can open browser and see it running under service. First we have to specify runtime for our application as ASP.NET Core supports also operating systems and architectures where Windows services doesn’t run. For this we have to modify project file.

Next add reference to NuGet package Microsoft.AspNetCore.Hosting.WindowsServices. This package has everything needed to run ASP.NET Core application as Windows service.

NB! For me newest version 2.1.1 of Microsoft.AspNetCore.Hosting.WindowsServices conflicted with ASP.NET Core 2.1.0 and I webt with version 2.1.0 instead.

We have to modify also Main() method of Program class. In its simplest form Main() method looks like this.

All we have to do now is to publish our application, register it as a Windows service and start the service.

Running application as service or on console

Those who have built Windows services before know very well that debugging of services can be pain in one specific anatomic area as after building the service one has to deplpy new version of it, attach debugger etc. There is simple way around – we make our Windows service run also as a console application that is easy to run on debugger from Visual Studio.

We can apply the same trick also with ASP.NET Core application that is running as Windows service.

The code shown may seem a little tricky. Here are my explanations:

• To run application on console from Visual Studio we control if debugger is attached. If we want to run application as console application outside from Visual Studio we can use –console argument.
• When application runs as web application under web server we must use current directory as content root. But when application runs as a service we need executable path as content root.
• We remove –console argument as ASP.NET Core expects all arguments to be name-value pairs.

Now try to run application from Visual Studio. It starts as a usual web application.

Making application run as Windows service

To make application run as Windows service we need some additional steps.

1. Publish application to some folder
2. Open command line in administrative permissions
3. Register application as Windows service using command (space after “binPath=“ is mandatory)

sc create AspNetWindowsService binPath= “path to my application exe”

Start service

sc start AspNetWindowsService

When service starts open browser and navigate to http://localhost:5000 to see web application running.

Before releasing new version of service the current running instance must be stopped. For this we can use command sc stop AspNetWindowsService. To remove service run the following command: sc delete AspNetWindowsService.

How to Host ASP.NET Core 3.1 Web Applications as Windows Service

In this article, we will be discussing how to deploy & host ASP.NET Core 3.1 Web API as a Windows Service. You may have one question in mind like why to host applications as windows service and why not on IIS. So in this article, we will see reasons behind hosting applications as windows service and we will be creating a Web API & host it as windows service. Let’s grab a cup of coffee and start coding.

What is Windows Service?

Microsoft Windows services, formerly known as NT services, enable you to create long-running executable applications that run in their own Windows sessions. These services can be automatically started when the computer boots, can be paused and restarted, and do not show any user interface. These features make services ideal for use on a server or whenever you need long-running functionality that does not interfere with other users who are working on the same computer. You can also run services in the security context of a specific user account that is different from the logged-on user or the default computer account.

In most of the scenarios where we have to make application long-running then Windows service is the best option. Windows services require an exe i.e executable of our application.

Why to deploy Applications as Windows Service

When we create an application we have to host it somewhere so that users can access it. We can either host it on IIS or as windows service. So below are the few reasons for hosting application as Windows service are:

• Sometimes we host application on IIS but we don’t utilize full features of IIS.
• If the machine where we are hosting web application does not have IIS enabled or if it IIS enabled but not configure to host .NET Core application.

We have already discussed we require executable for hosting application as Windows service. So to do this .NET Core provides one deployment mode called Self-contained deployment (SCD). When we published our app as SCD then it will provide the executable of our app along with .NET Core runtime DLLs. If you don’t know about the different hosting and deployment models in .NET Core then you can check out my below articles:

Hosting ASP.NET Core as Windows service

As I get it in RC2 there’s a support for hosting applications within Windows Services. I tried to test it on a simple web api project (using .NET Framework 4.6.1).

Here’s my Program.cs code:

All the other stuff are basically from .NET Core template (though I changed framework to net461 and added some dependencies in project.json).

After publishing it with dotnet publish and creating Windows Service with sc create I can succesfully start my service, but I can’t reach any of my controllers (ports are not listeting). I assume I’m doing something wrong.

So I guess the main question is how to make self hosted web api and run it as Windows Service. All found solutions don’t work after RC2 update.

7 Answers 7

You’ve got a couple of options here — use Microsoft’s WebHostService class, inherit WebHostService or write your own. The reason for the latter being that using Microsoft’s implementation, we cannot write a generic extension method with a type parameter inheriting WebHostService since this class does not contain a parameterless constructor nor can we access the service locator.

Using WebHostService

In this example, I’m going to create a Console Application that uses Microsoft.DotNet.Web.targets, outputs an .exe and operates as a MVC app (Views, Controllers, etc). I assume that creating the Console Application, changing the targets in the .xproj and modifying the project.json to have proper publish options and copying the Views, Controllers and webroot from the standard .NET Core web app template — is trivial.

Now the essential part:

Get this package and make sure your framework in project.json file is net451 (or newer)

Make sure the content root in the entry point is properly set to the publish directory of the application .exe file and that the RunAsService() extension method is called. E.g:

The .exe can now easily be installed using the following command

Once the service is started, the web application is hosted and successfully finds and renders its Views.

Inherit WebHostService

One major benefit of this approach is that this lets us override the OnStopping, OnStarting and OnStarted methods.

Let’s assume that the following is our custom class that inherits WebHostService

Following the steps above, we have to write down our own extension method that runs the host using our custom class:

The only line that remains to be changed from the previous example of the entry point is the else statement in the end, it has to call the proper extension method

Finally, installing the service using the same steps as above.

Host ASP.NET Core in a Windows Service

An ASP.NET Core app can be hosted on Windows as a Windows Service without using IIS. When hosted as a Windows Service, the app automatically starts after server reboots.

Prerequisites

Worker Service template

The ASP.NET Core Worker Service template provides a starting point for writing long running service apps. To use the template as a basis for a Windows Service app:

1. Create a Worker Service app from the .NET Core template.
2. Follow the guidance in the App configuration section to update the Worker Service app so that it can run as a Windows Service.

• Visual Studio
• Visual Studio for Mac
• .NET Core CLI

1. Create a new project.
2. Select Worker Service. Select Next.
3. Provide a project name in the Project name field or accept the default project name. Select Create.
4. In the Create a new Worker service dialog, select Create.

1. Create a new project.
2. Select App under .NET Core in the sidebar.
3. Select Worker under ASP.NET Core. Select Next.
4. Select .NET Core 3.0 or later for the Target Framework. Select Next.
5. Provide a name in the Project Name field. Select Create.

Use the Worker Service ( worker ) template with the dotnet new command from a command shell. In the following example, a Worker Service app is created named ContosoWorker . A folder for the ContosoWorker app is created automatically when the command is executed.

App configuration

IHostBuilder.UseWindowsService is called when building the host. If the app is running as a Windows Service, the method:

• Sets the host lifetime to WindowsServiceLifetime .
• Sets the content root to AppContext.BaseDirectory. For more information, see the Current directory and content root section.
• Enables logging to the event log:
  • The application name is used as the default source name.
  • The default log level is Warning or higher for an app based on an ASP.NET Core template that calls CreateDefaultBuilder to build the host.
  • Override the default log level with the Logging:EventLog:LogLevel:Default key in appsettings.json/appsettings..json or other configuration provider.
  • Only administrators can create new event sources. When an event source can’t be created using the application name, a warning is logged to the Application source and event logs are disabled.

In CreateHostBuilder of Program.cs:

The following sample apps accompany this topic:

• Background Worker Service Sample: A non-web app sample based on the Worker Service template that uses hosted services for background tasks.
• Web App Service Sample: A Razor Pages web app sample that runs as a Windows Service with hosted services for background tasks.

Deployment type

For information and advice on deployment scenarios, see .NET Core application deployment.

For a web app-based service that uses the Razor Pages or MVC frameworks, specify the Web SDK in the project file:

If the service only executes background tasks (for example, hosted services), specify the Worker SDK in the project file:

Framework-dependent deployment (FDD)

Framework-dependent deployment (FDD) relies on the presence of a shared system-wide version of .NET Core on the target system. When the FDD scenario is adopted following the guidance in this article, the SDK produces an executable (.exe), called a framework-dependent executable.

If using the Web SDK, a web.config file, which is normally produced when publishing an ASP.NET Core app, is unnecessary for a Windows Services app. To disable the creation of the web.config file, add the property set to true .

Self-contained deployment (SCD)

Self-contained deployment (SCD) doesn’t rely on the presence of a shared framework on the host system. The runtime and the app’s dependencies are deployed with the app.

A Windows Runtime Identifier (RID) is included in the

that contains the target framework:

To publish for multiple RIDs:

• Provide the RIDs in a semicolon-delimited list.
• Use the property name (plural).

For more information, see .NET Core RID Catalog.

Service user account

To create a user account for a service, use the New-LocalUser cmdlet from an administrative PowerShell 6 command shell.

On Windows 10 October 2018 Update (version 1809/build 10.0.17763) or later:

On Windows OS earlier than the Windows 10 October 2018 Update (version 1809/build 10.0.17763):

Provide a strong password when prompted.

Unless the -AccountExpires parameter is supplied to the New-LocalUser cmdlet with an expiration DateTime, the account doesn’t expire.

An alternative approach to managing users when using Active Directory is to use Managed Service Accounts. For more information, see Group Managed Service Accounts Overview.

Log on as a service rights

To establish Log on as a service rights for a service user account:

1. Open the Local Security Policy editor by running secpol.msc.
2. Expand the Local Policies node and select User Rights Assignment.
3. Open the Log on as a service policy.
4. Select Add User or Group.
5. Provide the object name (user account) using either of the following approaches:
   1. Type the user account ( ) in the object name field and select OK to add the user to the policy.
   2. Select Advanced. Select Find Now. Select the user account from the list. Select OK. Select OK again to add the user to the policy.
6. Select OK or Apply to accept the changes.

Create and manage the Windows Service

Create a service

Use PowerShell commands to register a service. From an administrative PowerShell 6 command shell, execute the following commands:

• : Path to the app’s folder on the host (for example, d:\myservice ). Don’t include the app’s executable in the path. A trailing slash isn’t required.
• : Service user account (for example, Contoso\ServiceUser ).
• : Service name (for example, MyService ).
• : The app’s executable path (for example, d:\myservice\myservice.exe ). Include the executable’s file name with extension.
• : Service description (for example, My sample service ).
• : Service display name (for example, My Service ).

Start a service

Start a service with the following PowerShell 6 command:

The command takes a few seconds to start the service.

Determine a service’s status

To check the status of a service, use the following PowerShell 6 command:

The status is reported as one of the following values:

Stop a service

Stop a service with the following Powershell 6 command:

Remove a service

After a short delay to stop a service, remove a service with the following Powershell 6 command:

Proxy server and load balancer scenarios

Services that interact with requests from the Internet or a corporate network and are behind a proxy or load balancer might require additional configuration. For more information, see Configure ASP.NET Core to work with proxy servers and load balancers.

Configure endpoints

By default, ASP.NET Core binds to http://localhost:5000 . Configure the URL and port by setting the ASPNETCORE_URLS environment variable.

For additional URL and port configuration approaches, see the relevant server article:

The preceding guidance covers support for HTTPS endpoints. For example, configure the app for HTTPS when authentication is used with a Windows Service.

Use of the ASP.NET Core HTTPS development certificate to secure a service endpoint isn’t supported.

Current directory and content root

The current working directory returned by calling GetCurrentDirectory for a Windows Service is the C:\WINDOWS\system32 folder. The system32 folder isn’t a suitable location to store a service’s files (for example, settings files). Use one of the following approaches to maintain and access a service’s assets and settings files.

Use ContentRootPath or ContentRootFileProvider

The app’s default settings files, appsettings.json and appsettings..json, are loaded from the app’s content root by calling CreateDefaultBuilder during host construction.

For other settings files loaded by developer code in ConfigureAppConfiguration, there’s no need to call SetBasePath. In the following example, the custom_settings.json file exists in the app’s content root and is loaded without explicitly setting a base path:

Don’t attempt to use GetCurrentDirectory to obtain a resource path because a Windows Service app returns the C:\WINDOWS\system32 folder as its current directory.

Store a service’s files in a suitable location on disk

Specify an absolute path with SetBasePath when using an IConfigurationBuilder to the folder containing the files.

Troubleshoot

Common errors

• An old or pre-release version of PowerShell is in use.
• The registered service doesn’t use the app’s published output from the dotnet publish command. Output of the dotnet build command isn’t supported for app deployment. Published assets are found in either of the following folders depending on the deployment type:
  • bin/Release//publish (FDD)
  • bin/Release///publish (SCD)
• The service isn’t in the RUNNING state.
• The paths to resources that the app uses (for example, certificates) are incorrect. The base path of a Windows Service is c:\Windows\System32.
• The user doesn’t have Log on as a service rights.
• The user’s password is expired or incorrectly passed when executing the New-Service PowerShell command.
• The app requires ASP.NET Core authentication but isn’t configured for secure connections (HTTPS).
• The request URL port is incorrect or not configured correctly in the app.

System and Application Event Logs

Access the System and Application Event Logs:

1. Open the Start menu, search for Event Viewer, and select the Event Viewer app.
2. In Event Viewer, open the Windows Logs node.
3. Select System to open the System Event Log. Select Application to open the Application Event Log.
4. Search for errors associated with the failing app.

Run the app at a command prompt

Many startup errors don’t produce useful information in the event logs. You can find the cause of some errors by running the app at a command prompt on the hosting system. To log additional detail from the app, lower the log level or run the app in the Development environment.

Clear package caches

A functioning app may fail immediately after upgrading either the .NET Core SDK on the development machine or changing package versions within the app. In some cases, incoherent packages may break an app when performing major upgrades. Most of these issues can be fixed by following these instructions:

Delete the bin and obj folders.

Clear the package caches by executing dotnet nuget locals all —clear from a command shell.

Clearing package caches can also be accomplished with the nuget.exe tool and executing the command nuget locals all -clear . nuget.exe isn’t a bundled install with the Windows desktop operating system and must be obtained separately from the NuGet website.

Restore and rebuild the project.

Delete all of the files in the deployment folder on the server prior to redeploying the app.

Slow or hanging app

A crash dump is a snapshot of the system’s memory and can help determine the cause of an app crash, startup failure, or slow app.

App crashes or encounters an exception

Obtain and analyze a dump from Windows Error Reporting (WER):

Create a folder to hold crash dump files at c:\dumps .

Run the EnableDumps PowerShell script with the application executable name:

Run the app under the conditions that cause the crash to occur.

After the crash has occurred, run the DisableDumps PowerShell script:

After an app crashes and dump collection is complete, the app is allowed to terminate normally. The PowerShell script configures WER to collect up to five dumps per app.

Crash dumps might take up a large amount of disk space (up to several gigabytes each).

App hangs, fails during startup, or runs normally

When an app hangs (stops responding but doesn’t crash), fails during startup, or runs normally, see User-Mode Dump Files: Choosing the Best Tool to select an appropriate tool to produce the dump.

Analyze the dump

A dump can be analyzed using several approaches. For more information, see Analyzing a User-Mode Dump File.

Additional resources

• Kestrel endpoint configuration (includes HTTPS configuration and SNI support)

• Kestrel endpoint configuration (includes HTTPS configuration and SNI support)

An ASP.NET Core app can be hosted on Windows as a Windows Service without using IIS. When hosted as a Windows Service, the app automatically starts after server reboots.

Prerequisites

App configuration

To test and debug when running outside of a service, add code to determine if the app is running as a service or a console app. Inspect if the debugger is attached or a —console switch is present. If either condition is true (the app isn’t run as a service), call Run. If the conditions are false (the app is run as a service):

• Call SetCurrentDirectory and use a path to the app’s published location. Don’t call GetCurrentDirectory to obtain the path because a Windows Service app returns the C:\WINDOWS\system32 folder when GetCurrentDirectory is called. For more information, see the Current directory and content root section. This step is performed before the app is configured in CreateWebHostBuilder .
• Call RunAsService to run the app as a service.

Because the Command-line Configuration Provider requires name-value pairs for command-line arguments, the —console switch is removed from the arguments before CreateDefaultBuilder receives the arguments.

To write to the Windows Event Log, add the EventLog provider to ConfigureLogging. Set the logging level with the Logging:LogLevel:Default key in the appsettings.Production.json file.

In the following example from the sample app, RunAsCustomService is called instead of RunAsService in order to handle lifetime events within the app. For more information, see the Handle starting and stopping events section.

Deployment type

For information and advice on deployment scenarios, see .NET Core application deployment.

For a web app-based service that uses the Razor Pages or MVC frameworks, specify the Web SDK in the project file:

If the service only executes background tasks (for example, hosted services), specify the Worker SDK in the project file:

Framework-dependent deployment (FDD)

Framework-dependent deployment (FDD) relies on the presence of a shared system-wide version of .NET Core on the target system. When the FDD scenario is adopted following the guidance in this article, the SDK produces an executable (.exe), called a framework-dependent executable.

The Windows Runtime Identifier (RID) ( ) contains the target framework. In the following example, the RID is set to win7-x64 . The property is set to false . These properties instruct the SDK to generate an executable (.exe) file for Windows and an app that depends on the shared .NET Core framework.

A web.config file, which is normally produced when publishing an ASP.NET Core app, is unnecessary for a Windows Services app. To disable the creation of the web.config file, add the property set to true .

Self-contained deployment (SCD)

Self-contained deployment (SCD) doesn’t rely on the presence of a shared framework on the host system. The runtime and the app’s dependencies are deployed with the app.

A Windows Runtime Identifier (RID) is included in the

that contains the target framework:

To publish for multiple RIDs:

• Provide the RIDs in a semicolon-delimited list.
• Use the property name (plural).

For more information, see .NET Core RID Catalog.

A property is set to true :

Service user account

To create a user account for a service, use the New-LocalUser cmdlet from an administrative PowerShell 6 command shell.

On Windows 10 October 2018 Update (version 1809/build 10.0.17763) or later:

On Windows OS earlier than the Windows 10 October 2018 Update (version 1809/build 10.0.17763):

Provide a strong password when prompted.

Unless the -AccountExpires parameter is supplied to the New-LocalUser cmdlet with an expiration DateTime, the account doesn’t expire.

An alternative approach to managing users when using Active Directory is to use Managed Service Accounts. For more information, see Group Managed Service Accounts Overview.

Log on as a service rights

To establish Log on as a service rights for a service user account:

1. Open the Local Security Policy editor by running secpol.msc.
2. Expand the Local Policies node and select User Rights Assignment.
3. Open the Log on as a service policy.
4. Select Add User or Group.
5. Provide the object name (user account) using either of the following approaches:
   1. Type the user account ( ) in the object name field and select OK to add the user to the policy.
   2. Select Advanced. Select Find Now. Select the user account from the list. Select OK. Select OK again to add the user to the policy.
6. Select OK or Apply to accept the changes.

Create and manage the Windows Service

Create a service

Use PowerShell commands to register a service. From an administrative PowerShell 6 command shell, execute the following commands:

• : Path to the app’s folder on the host (for example, d:\myservice ). Don’t include the app’s executable in the path. A trailing slash isn’t required.
• : Service user account (for example, Contoso\ServiceUser ).
• : Service name (for example, MyService ).
• : The app’s executable path (for example, d:\myservice\myservice.exe ). Include the executable’s file name with extension.
• : Service description (for example, My sample service ).
• : Service display name (for example, My Service ).

Start a service

Start a service with the following PowerShell 6 command:

The command takes a few seconds to start the service.

Determine a service’s status

To check the status of a service, use the following PowerShell 6 command:

The status is reported as one of the following values:

Stop a service

Stop a service with the following Powershell 6 command:

Remove a service

After a short delay to stop a service, remove a service with the following Powershell 6 command:

Handle starting and stopping events

Create a class that derives from WebHostService with the OnStarting , OnStarted , and OnStopping methods:

Create an extension method for IWebHost that passes the CustomWebHostService to Run:

In Program.Main , call the RunAsCustomService extension method instead of RunAsService:

To see the location of RunAsService in Program.Main , refer to the code sample shown in the Deployment type section.

Proxy server and load balancer scenarios

Services that interact with requests from the Internet or a corporate network and are behind a proxy or load balancer might require additional configuration. For more information, see Configure ASP.NET Core to work with proxy servers and load balancers.

Configure endpoints

By default, ASP.NET Core binds to http://localhost:5000 . Configure the URL and port by setting the ASPNETCORE_URLS environment variable.

For additional URL and port configuration approaches, see the relevant server article:

The preceding guidance covers support for HTTPS endpoints. For example, configure the app for HTTPS when authentication is used with a Windows Service.

Use of the ASP.NET Core HTTPS development certificate to secure a service endpoint isn’t supported.

Current directory and content root

The current working directory returned by calling GetCurrentDirectory for a Windows Service is the C:\WINDOWS\system32 folder. The system32 folder isn’t a suitable location to store a service’s files (for example, settings files). Use one of the following approaches to maintain and access a service’s assets and settings files.

Set the content root path to the app’s folder

The ContentRootPath is the same path provided to the binPath argument when a service is created. Instead of calling GetCurrentDirectory to create paths to settings files, call SetCurrentDirectory with the path to the app’s content root.

In Program.Main , determine the path to the folder of the service’s executable and use the path to establish the app’s content root:

Store a service’s files in a suitable location on disk

Specify an absolute path with SetBasePath when using an IConfigurationBuilder to the folder containing the files.

Troubleshoot

Common errors

• An old or pre-release version of PowerShell is in use.
• The registered service doesn’t use the app’s published output from the dotnet publish command. Output of the dotnet build command isn’t supported for app deployment. Published assets are found in either of the following folders depending on the deployment type:
  • bin/Release//publish (FDD)
  • bin/Release///publish (SCD)
• The service isn’t in the RUNNING state.
• The paths to resources that the app uses (for example, certificates) are incorrect. The base path of a Windows Service is c:\Windows\System32.
• The user doesn’t have Log on as a service rights.
• The user’s password is expired or incorrectly passed when executing the New-Service PowerShell command.
• The app requires ASP.NET Core authentication but isn’t configured for secure connections (HTTPS).
• The request URL port is incorrect or not configured correctly in the app.

System and Application Event Logs

Access the System and Application Event Logs:

1. Open the Start menu, search for Event Viewer, and select the Event Viewer app.
2. In Event Viewer, open the Windows Logs node.
3. Select System to open the System Event Log. Select Application to open the Application Event Log.
4. Search for errors associated with the failing app.

Run the app at a command prompt

Many startup errors don’t produce useful information in the event logs. You can find the cause of some errors by running the app at a command prompt on the hosting system. To log additional detail from the app, lower the log level or run the app in the Development environment.

Clear package caches

A functioning app may fail immediately after upgrading either the .NET Core SDK on the development machine or changing package versions within the app. In some cases, incoherent packages may break an app when performing major upgrades. Most of these issues can be fixed by following these instructions:

Delete the bin and obj folders.

Clear the package caches by executing dotnet nuget locals all —clear from a command shell.

Clearing package caches can also be accomplished with the nuget.exe tool and executing the command nuget locals all -clear . nuget.exe isn’t a bundled install with the Windows desktop operating system and must be obtained separately from the NuGet website.

Restore and rebuild the project.

Delete all of the files in the deployment folder on the server prior to redeploying the app.

Slow or hanging app

A crash dump is a snapshot of the system’s memory and can help determine the cause of an app crash, startup failure, or slow app.

App crashes or encounters an exception

Obtain and analyze a dump from Windows Error Reporting (WER):

Create a folder to hold crash dump files at c:\dumps .

Run the EnableDumps PowerShell script with the application executable name:

Run the app under the conditions that cause the crash to occur.

After the crash has occurred, run the DisableDumps PowerShell script:

After an app crashes and dump collection is complete, the app is allowed to terminate normally. The PowerShell script configures WER to collect up to five dumps per app.

Crash dumps might take up a large amount of disk space (up to several gigabytes each).

App hangs, fails during startup, or runs normally

When an app hangs (stops responding but doesn’t crash), fails during startup, or runs normally, see User-Mode Dump Files: Choosing the Best Tool to select an appropriate tool to produce the dump.

Analyze the dump

A dump can be analyzed using several approaches. For more information, see Analyzing a User-Mode Dump File.

Additional resources

• Kestrel endpoint configuration (includes HTTPS configuration and SNI support)
• ASP.NET Core Web Host
• Troubleshoot and debug ASP.NET Core projects

An ASP.NET Core app can be hosted on Windows as a Windows Service without using IIS. When hosted as a Windows Service, the app automatically starts after server reboots.

Prerequisites

App configuration

To test and debug when running outside of a service, add code to determine if the app is running as a service or a console app. Inspect if the debugger is attached or a —console switch is present. If either condition is true (the app isn’t run as a service), call Run. If the conditions are false (the app is run as a service):

• Call SetCurrentDirectory and use a path to the app’s published location. Don’t call GetCurrentDirectory to obtain the path because a Windows Service app returns the C:\WINDOWS\system32 folder when GetCurrentDirectory is called. For more information, see the Current directory and content root section. This step is performed before the app is configured in CreateWebHostBuilder .
• Call RunAsService to run the app as a service.

Because the Command-line Configuration Provider requires name-value pairs for command-line arguments, the —console switch is removed from the arguments before CreateDefaultBuilder receives the arguments.

To write to the Windows Event Log, add the EventLog provider to ConfigureLogging. Set the logging level with the Logging:LogLevel:Default key in the appsettings.Production.json file.

In the following example from the sample app, RunAsCustomService is called instead of RunAsService in order to handle lifetime events within the app. For more information, see the Handle starting and stopping events section.

Deployment type

For information and advice on deployment scenarios, see .NET Core application deployment.

For a web app-based service that uses the Razor Pages or MVC frameworks, specify the Web SDK in the project file:

If the service only executes background tasks (for example, hosted services), specify the Worker SDK in the project file:

Framework-dependent deployment (FDD)

Framework-dependent deployment (FDD) relies on the presence of a shared system-wide version of .NET Core on the target system. When the FDD scenario is adopted following the guidance in this article, the SDK produces an executable (.exe), called a framework-dependent executable.

The Windows Runtime Identifier (RID) ( ) contains the target framework. In the following example, the RID is set to win7-x64 . The property is set to false . These properties instruct the SDK to generate an executable (.exe) file for Windows and an app that depends on the shared .NET Core framework.

The property is set to true . This property provides the service with an activation path (an executable, .exe) for an FDD.

A web.config file, which is normally produced when publishing an ASP.NET Core app, is unnecessary for a Windows Services app. To disable the creation of the web.config file, add the property set to true .

Self-contained deployment (SCD)

Self-contained deployment (SCD) doesn’t rely on the presence of a shared framework on the host system. The runtime and the app’s dependencies are deployed with the app.

A Windows Runtime Identifier (RID) is included in the

that contains the target framework:

To publish for multiple RIDs:

• Provide the RIDs in a semicolon-delimited list.
• Use the property name (plural).

For more information, see .NET Core RID Catalog.

A property is set to true :

Service user account

To create a user account for a service, use the New-LocalUser cmdlet from an administrative PowerShell 6 command shell.

On Windows 10 October 2018 Update (version 1809/build 10.0.17763) or later:

On Windows OS earlier than the Windows 10 October 2018 Update (version 1809/build 10.0.17763):

Provide a strong password when prompted.

Unless the -AccountExpires parameter is supplied to the New-LocalUser cmdlet with an expiration DateTime, the account doesn’t expire.

An alternative approach to managing users when using Active Directory is to use Managed Service Accounts. For more information, see Group Managed Service Accounts Overview.

Log on as a service rights

To establish Log on as a service rights for a service user account:

1. Open the Local Security Policy editor by running secpol.msc.
2. Expand the Local Policies node and select User Rights Assignment.
3. Open the Log on as a service policy.
4. Select Add User or Group.
5. Provide the object name (user account) using either of the following approaches:
   1. Type the user account ( ) in the object name field and select OK to add the user to the policy.
   2. Select Advanced. Select Find Now. Select the user account from the list. Select OK. Select OK again to add the user to the policy.
6. Select OK or Apply to accept the changes.

Create and manage the Windows Service

Create a service

Use PowerShell commands to register a service. From an administrative PowerShell 6 command shell, execute the following commands:

• : Path to the app’s folder on the host (for example, d:\myservice ). Don’t include the app’s executable in the path. A trailing slash isn’t required.
• : Service user account (for example, Contoso\ServiceUser ).
• : Service name (for example, MyService ).
• : The app’s executable path (for example, d:\myservice\myservice.exe ). Include the executable’s file name with extension.
• : Service description (for example, My sample service ).
• : Service display name (for example, My Service ).

Start a service

Start a service with the following PowerShell 6 command:

The command takes a few seconds to start the service.

Determine a service’s status

To check the status of a service, use the following PowerShell 6 command:

The status is reported as one of the following values:

Stop a service

Stop a service with the following Powershell 6 command:

Remove a service

After a short delay to stop a service, remove a service with the following Powershell 6 command:

Handle starting and stopping events

Create a class that derives from WebHostService with the OnStarting , OnStarted , and OnStopping methods:

Create an extension method for IWebHost that passes the CustomWebHostService to Run:

In Program.Main , call the RunAsCustomService extension method instead of RunAsService:

To see the location of RunAsService in Program.Main , refer to the code sample shown in the Deployment type section.

Proxy server and load balancer scenarios

Services that interact with requests from the Internet or a corporate network and are behind a proxy or load balancer might require additional configuration. For more information, see Configure ASP.NET Core to work with proxy servers and load balancers.

Configure endpoints

By default, ASP.NET Core binds to http://localhost:5000 . Configure the URL and port by setting the ASPNETCORE_URLS environment variable.

For additional URL and port configuration approaches, see the relevant server article:

The preceding guidance covers support for HTTPS endpoints. For example, configure the app for HTTPS when authentication is used with a Windows Service.

Use of the ASP.NET Core HTTPS development certificate to secure a service endpoint isn’t supported.

Current directory and content root

The current working directory returned by calling GetCurrentDirectory for a Windows Service is the C:\WINDOWS\system32 folder. The system32 folder isn’t a suitable location to store a service’s files (for example, settings files). Use one of the following approaches to maintain and access a service’s assets and settings files.

Set the content root path to the app’s folder

The ContentRootPath is the same path provided to the binPath argument when a service is created. Instead of calling GetCurrentDirectory to create paths to settings files, call SetCurrentDirectory with the path to the app’s content root.

In Program.Main , determine the path to the folder of the service’s executable and use the path to establish the app’s content root:

Store a service’s files in a suitable location on disk

Specify an absolute path with SetBasePath when using an IConfigurationBuilder to the folder containing the files.

Troubleshoot

Common errors

• An old or pre-release version of PowerShell is in use.
• The registered service doesn’t use the app’s published output from the dotnet publish command. Output of the dotnet build command isn’t supported for app deployment. Published assets are found in either of the following folders depending on the deployment type:
  • bin/Release//publish (FDD)
  • bin/Release///publish (SCD)
• The service isn’t in the RUNNING state.
• The paths to resources that the app uses (for example, certificates) are incorrect. The base path of a Windows Service is c:\Windows\System32.
• The user doesn’t have Log on as a service rights.
• The user’s password is expired or incorrectly passed when executing the New-Service PowerShell command.
• The app requires ASP.NET Core authentication but isn’t configured for secure connections (HTTPS).
• The request URL port is incorrect or not configured correctly in the app.

System and Application Event Logs

Access the System and Application Event Logs:

1. Open the Start menu, search for Event Viewer, and select the Event Viewer app.
2. In Event Viewer, open the Windows Logs node.
3. Select System to open the System Event Log. Select Application to open the Application Event Log.
4. Search for errors associated with the failing app.

Run the app at a command prompt

Many startup errors don’t produce useful information in the event logs. You can find the cause of some errors by running the app at a command prompt on the hosting system. To log additional detail from the app, lower the log level or run the app in the Development environment.

Clear package caches

A functioning app may fail immediately after upgrading either the .NET Core SDK on the development machine or changing package versions within the app. In some cases, incoherent packages may break an app when performing major upgrades. Most of these issues can be fixed by following these instructions:

Delete the bin and obj folders.

Clear the package caches by executing dotnet nuget locals all —clear from a command shell.

Clearing package caches can also be accomplished with the nuget.exe tool and executing the command nuget locals all -clear . nuget.exe isn’t a bundled install with the Windows desktop operating system and must be obtained separately from the NuGet website.

Restore and rebuild the project.

Delete all of the files in the deployment folder on the server prior to redeploying the app.

Slow or hanging app

A crash dump is a snapshot of the system’s memory and can help determine the cause of an app crash, startup failure, or slow app.

App crashes or encounters an exception

Obtain and analyze a dump from Windows Error Reporting (WER):

Create a folder to hold crash dump files at c:\dumps .

Run the EnableDumps PowerShell script with the application executable name:

Run the app under the conditions that cause the crash to occur.

After the crash has occurred, run the DisableDumps PowerShell script:

After an app crashes and dump collection is complete, the app is allowed to terminate normally. The PowerShell script configures WER to collect up to five dumps per app.

Crash dumps might take up a large amount of disk space (up to several gigabytes each).

App hangs, fails during startup, or runs normally

When an app hangs (stops responding but doesn’t crash), fails during startup, or runs normally, see User-Mode Dump Files: Choosing the Best Tool to select an appropriate tool to produce the dump.

Analyze the dump

A dump can be analyzed using several approaches. For more information, see Analyzing a User-Mode Dump File.