Hospedar o ASP.NET Core em um serviço Windows

Um aplicativo ASP.NET Core pode ser hospedado no Windows somo um Serviço Windows sem usar o IIS. Quando hospedado como um Serviço Windows, o aplicativo é iniciado automaticamente após a reinicialização do servidor.

Pré-requisitos

• SDK do ASP.NET Core 7.0 ou posterior
• PowerShell 6.2 ou posterior

Modelo de serviço de trabalho

O modelo de Serviço de Trabalho do ASP.NET Core fornece um ponto inicial para escrever aplicativos de serviço de execução prolongada. Para usar o modelo como base para um aplicativo de Serviço Windows:

1. Crie um aplicativo de serviço de trabalho usando o modelo do .NET Core.
2. Instale o pacote NuGet Microsoft.Extensions.Hosting.WindowsServices.
3. Siga as orientações na seção Configuração de aplicativos para atualizar o aplicativo do Serviço de Trabalho para que ele possa ser executado como um Serviço Windows.

Visual Studio

1. Criar um novo projeto.
2. Selecione Serviço de Trabalho. Selecione Avançar.
3. Forneça um nome ao projeto no campo Nome do projeto ou aceite o nome do projeto padrão. Selecione Criar.
4. Na caixa de diálogo Criar um serviço de trabalho, selecione Criar.

Visual Studio para Mac

1. Criar um novo projeto.
2. Selecione Aplicativo em .NET Core na barra lateral.
3. Selecione Trabalho em ASP.NET Core. Selecione Avançar.
4. Selecione .NET Core 3.0 ou posterior para a Estrutura de Destino. Selecione Avançar.
5. Forneça um nome no campo Nome do Projeto. Selecione Criar.

CLI do .NET Core

Use o modelo de Serviço de Trabalho (worker) com o comando dotnet novo em um shell de comando. No exemplo a seguir, um aplicativo de Serviço de Trabalho é criado com o nome ContosoWorker. Uma pasta para o aplicativo ContosoWorker é criada automaticamente quando o comando é executado.

dotnet new worker -o ContosoWorker

Configuração do aplicativo

Atualize Program.cs para chamar AddWindowsService. Quando o aplicativo estiver sendo executado como um Serviço Windows, AddWindowsService:

• Define o tempo de vida do host como WindowsServiceLifetime.
• Define a raiz do conteúdo como AppContext.BaseDirectory. Para saber mais, consulte a seção Diretório atual e a raiz do conteúdo.
• Habilita o registro em log no log de eventos:
  • O nome do aplicativo é usado como o nome de origem padrão.
  • O nível de log padrão é Aviso ou superior para um aplicativo com base em um modelo de ASP.NET Core que chama CreateDefaultBuilder para criar o host.
  • Substitua o nível de log padrão com a chave Logging:EventLog:LogLevel:Default em appsettings.json/appsettings.{Environment}.json ou outro provedor de configuração.
  • Somente administradores podem criar novas fontes de evento. Quando uma fonte de evento não puder ser criada usando o nome do aplicativo, um aviso será registrado em log como a fonte do Aplicativo e os logs de eventos serão desabilitados.

Considere a classe ServiceA a seguir:

namespace SampleApp.Services;

public class ServiceA : BackgroundService
{
    public ServiceA(ILoggerFactory loggerFactory)
    {
        Logger = loggerFactory.CreateLogger<ServiceA>();
    }

    public ILogger Logger { get; }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        Logger.LogInformation("ServiceA is starting.");

        stoppingToken.Register(() => Logger.LogInformation("ServiceA is stopping."));

        while (!stoppingToken.IsCancellationRequested)
        {
            Logger.LogInformation("ServiceA is doing background work.");

            await Task.Delay(TimeSpan.FromSeconds(5), stoppingToken);
        }

        Logger.LogInformation("ServiceA has stopped.");
    }
}

O Program.cs a seguir chama AddHostedService para registrar ServiceA:

using SampleApp.Services;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.AddWindowsService();
builder.Services.AddHostedService<ServiceA>();

var app = builder.Build();

app.MapRazorPages();

app.Run();

Os seguintes aplicativos de exemplo acompanham este tópico:

• Exemplo de Serviço de Trabalho em Segundo Plano: um exemplo de aplicativo não Web baseado no modelo do Serviço de Trabalho que usa serviços hospedados para tarefas em segundo plano.
• Exemplo de Serviço de Aplicativo Web: um exemplo de aplicativo Web do Razor Pages que é executado como um Serviço do Windows com serviços hospedados para tarefas em segundo plano.

Para obter diretrizes do MVC, consulte os artigos em Visão geral do ASP.NET Core MVC e Migrar do ASP.NET Core 2.2 para 3.0.

Tipo de implantação

Para saber mais e obter conselhos sobre cenários de implantação, consulte Implantação de aplicativos .NET Core.

.

Para um serviço baseado em aplicativo Web que usa as estruturas Razor Pages ou MVC, especifique o SDK da Web no arquivo de projeto:

<Project Sdk="Microsoft.NET.Sdk.Web">

Se o serviço executar apenas tarefas em segundo plano (por exemplo, serviços hospedados), especifique o SDK de Trabalho no arquivo de projeto:

<Project Sdk="Microsoft.NET.Sdk.Worker">

FDD (Implantação dependente de estrutura)

A FDD (Implantação Dependente de Estrutura) se baseia na presença de uma versão compartilhada em todo o sistema do .NET Core no sistema de destino. Quando o cenário FDD é adotado após a orientação deste artigo, o SDK produz um executável (.exe), chamado de executável dependente de estrutura.

Ao usar o SDK da Web, um arquivo web.config, que normalmente é gerado durante a publicação de um aplicativo ASP.NET Core, é desnecessário para um aplicativo de serviços do Windows. Para desabilitar a criação de um arquivo web.config, adicione a propriedade <IsTransformWebConfigDisabled> definida como true.

<PropertyGroup>
  <TargetFramework>net7.0</TargetFramework>
  <IsTransformWebConfigDisabled>true</IsTransformWebConfigDisabled>
</PropertyGroup>

SCD (Implantação Autossuficiente)

A SCD (Implantação Autossuficiente) não se baseia na presença de uma estrutura compartilhada no sistema de destino. O runtime e as dependências do aplicativo são implantados com o aplicativo.

Um RID (Identificador do Runtime do Windows) está incluído no <PropertyGroup> que contém a estrutura de destino:

<RuntimeIdentifier>win7-x64</RuntimeIdentifier>

Para publicar para vários RIDs:

• Forneça os RIDs em uma lista delimitada por ponto e vírgula.
• Use o nome da propriedade <RuntimeIdentifiers> (plural).

Para obter mais informações, consulte Catálogo de RID do .NET Core.

Conta de usuário do serviço

Para criar uma conta de usuário para um serviço, use o cmdlet New-LocalUser de um shell de comando administrativo do PowerShell 6.

Na Atualização de outubro de 2018 do Windows 10 (versão 1809/build 10.0.17763) ou posterior:

New-LocalUser -Name {SERVICE NAME}

No sistema operacional do Windows anterior à Atualização de outubro de 2018 do Windows 10 (versão 1809/build 10.0.17763):

powershell -Command "New-LocalUser -Name {SERVICE NAME}"

Forneça uma senha forte quando solicitado.

A conta só expirará se o parâmetro -AccountExpires for fornecido ao cmdlet New LocalUser com uma data de validade DateTime.

Confira mais informações em Microsoft.PowerShell.LocalAccounts e Contas de usuário do serviço.

Uma abordagem alternativa ao gerenciamento de usuários ao usar o Active Directory é usar Contas de Serviço Gerenciado. Para saber mais, confira Visão geral das Contas de Serviço Gerenciado em Grupo.

Fazer logon como direitos de um serviço

Para estabelecer os direitos de Fazer logon como um serviço para uma conta de usuário do serviço:

1. Abra a janela do editor da Política de Segurança Local executando secpol.msc.
2. Expanda o nó Políticas Locais e escolha Atribuição de Direitos de Usuário.
3. Abra a política Fazer logon como um serviço.
4. Selecione Adicionar Usuário ou Grupo.
5. Forneça o nome do objeto (conta de usuário) usando uma das abordagens a seguir:
   1. Digite a conta de usuário ({DOMAIN OR COMPUTER NAME\USER}) no campo de nome do objeto e escolha OK para adicionar o usuário à política.
   2. Selecione Avançado. Escolha Localizar Agora. Escolha a conta de usuário na lista. Selecione OK. Escolha OK novamente para adicionar o usuário à política.
6. Escolha OK ou Aplicar para aceitar as alterações.

Criar e gerenciar o Serviço Windows

Criar um serviço

Use comandos do PowerShell para registrar um serviço. Em um shell de comando administrativo do PowerShell 6, execute os seguintes comandos:

$acl = Get-Acl "{EXE PATH}"
$aclRuleArgs = "{DOMAIN OR COMPUTER NAME\USER}", "Read,Write,ReadAndExecute", "ContainerInherit,ObjectInherit", "None", "Allow"
$accessRule = New-Object System.Security.AccessControl.FileSystemAccessRule($aclRuleArgs)
$acl.SetAccessRule($accessRule)
$acl | Set-Acl "{EXE PATH}"

New-Service -Name {SERVICE NAME} -BinaryPathName "{EXE FILE PATH} --contentRoot {EXE FOLDER PATH}" -Credential "{DOMAIN OR COMPUTER NAME\USER}" -Description "{DESCRIPTION}" -DisplayName "{DISPLAY NAME}" -StartupType Automatic

• {EXE PATH}: caminho do arquivo executável do aplicativo no host (por exemplo, d:\myservice). Não inclua o nome do arquivo executável do aplicativo no caminho. A barra à direita não é necessária.
• {DOMAIN OR COMPUTER NAME\USER}: conta de usuário do serviço (por exemplo, Contoso\ServiceUser).
• {SERVICE NAME}: nome do serviço (por exemplo, MyService).
• {EXE FILE PATH}: o caminho do executável completo do aplicativo (por exemplo, d:\myservice\myservice.exe). Inclua nome do arquivo do executável com a extensão.
• {EXE FOLDER PATH}: o caminho da parta do arquivo executável completo do aplicativo (por exemplo, d:\myservice).
• {DESCRIPTION}: descrição do serviço (por exemplo, My sample service).
• {DISPLAY NAME}: nome de exibição do serviço (por exemplo, My Service).

Iniciar um serviço

Inicie o serviço com o seguinte comando do PowerShell 6:

Start-Service -Name {SERVICE NAME}

O comando leva alguns segundos para iniciar o serviço.

Determinar o status do serviço

Para verificar o status de um serviço, use o seguinte comando do PowerShell 6:

Get-Service -Name {SERVICE NAME}

O status é relatado como um dos seguintes valores:

• Starting
• Running
• Stopping
• Stopped

Parar um serviço

Pare um serviço com o seguinte comando do PowerShell 6:

Stop-Service -Name {SERVICE NAME}

Remover um serviço

Após um pequeno atraso para interromper um serviço, remova o serviço com o seguinte comando do PowerShell 6:

Remove-Service -Name {SERVICE NAME}

Servidor proxy e cenários de balanceador de carga

Serviços que interagem com solicitações da Internet ou de uma rede corporativa e estão atrás de um proxy ou de um balanceador de carga podem exigir configuração adicional. Para obter mais informações, veja Configurar o ASP.NET Core para trabalhar com servidores proxy e balanceadores de carga.

Configurar pontos de extremidade

Por padrão, o ASP.NET Core é associado a http://localhost:5000. Configure a URL e a porta definindo a variável de ambiente ASPNETCORE_URLS.

Para obter abordagens de configuração de porta e URL adicionais, consulte o artigo do servidor relevante:

• Configurar pontos de extremidade para o servidor Web Kestrel do ASP.NET Core
• Implementação do servidor Web HTTP.sys no ASP.NET Core

As diretrizes anteriores abordam o suporte para pontos de extremidade HTTPS. Por exemplo, configure o aplicativo para HTTPS quando a autenticação for usada com um Serviço do Windows.

Observação

Não há suporte para uso do certificado de desenvolvimento HTTPS do ASP.NET Core para proteger um ponto de extremidade de serviço.

Diretório atual e a raiz do conteúdo

O diretório de trabalho atual retornado ao chamar GetCurrentDirectory de um serviço Windows é a pasta C:\WINDOWS\system32. A pasta system32 não é um local adequado para armazenar os arquivos de um serviço (por exemplo, os arquivos de configurações). Use uma das seguintes abordagens para manter e acessar ativos e os arquivos de configuração de um serviço.

Usar ContentRootPath ou ContentRootFileProvider

Use IHostEnvironment.ContentRootPath ou ContentRootFileProvider para localizar os recursos do aplicativo.

Quando o aplicativo é executado como um serviço, UseWindowsService define o ContentRootPath como AppContext.BaseDirectory.

Os arquivos de configurações padrão do aplicativo, appsettings.json e appsettings.{Environment}.json, são carregados da raiz de conteúdo do aplicativo chamando CreateDefaultBuilder durante a construção do host.

Para outros arquivos de configurações carregados pelo código do desenvolvedor no ConfigureAppConfiguration, não é necessário chamar SetBasePath. No exemplo a seguir, o arquivo custom_settings.json existe na raiz de conteúdo do aplicativo e é carregado sem definir explicitamente um caminho base:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .UseWindowsService()
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddJsonFile("custom_settings.json");
            })
            .ConfigureServices((hostContext, services) =>
            {
                services.AddHostedService<Worker>();
            });
}

Não tente usar GetCurrentDirectory para obter um caminho de recurso porque um aplicativo do Serviço do Windows retorna a pasta C:\WINDOWS\system32 como seu diretório atual.

Armazenar os arquivos do serviço em um local adequado no disco

Especifique um caminho absoluto com SetBasePath quando usar um IConfigurationBuilder para a pasta que contém os arquivos.

Solucionar problemas

Para solucionar problemas de um aplicativo do Serviço do Windows, consulte Solucionar problemas e depurar projetos do ASP.NET Core.

Erros comuns

• Uma versão antiga ou de pré-lançamento do PowerShell está em uso.
• O serviço registrado não usa a saída publicada do aplicativo do comando dotnet publish. Não há suporte para a saída do comando dotnet build para implantação de aplicativo. Os ativos publicados são encontrados em qualquer uma das seguintes pastas, dependendo do tipo de implantação:
  • bin/Release/{TARGET FRAMEWORK}/publish (FDD)
  • bin/Release/{TARGET FRAMEWORK}/{RUNTIME IDENTIFIER}/publish (SCD)
• O serviço não está no estado RUNNING.
• Os caminhos para os recursos que o aplicativo usa (por exemplo, certificados) estão incorretos. O caminho base de um Serviço do Windows é c:\Windows\System32.
• O usuário não tem direitos de Logon como serviço.
• A senha do usuário expirou ou foi aprovada incorretamente ao executar o comando New-Service do PowerShell.
• O aplicativo requer autenticação do ASP.NET Core, mas não está configurado para HTTPS (conexões seguras).
• A porta da URL de solicitação está incorreta ou não foi configurada corretamente no aplicativo.

Logs de Eventos do Sistema e do Aplicativo

Acesso aos Logs de Eventos do Sistema e do Aplicativo:

1. Abra o menu Iniciar, procure Visualizador de Eventos e selecione o aplicativo Visualizador de Eventos.
2. No Visualizador de Eventos, abra o nó Logs do Windows.
3. Selecione Sistema para abrir o Log de Eventos do Sistema. Selecione Aplicativo para abrir o Log de Eventos do Aplicativo.
4. Procure erros associados ao aplicativo com falha.

Execute o aplicativo em um prompt de comando

Muitos erros de inicialização não produzem informações úteis no log de eventos. Você pode encontrar a causa de alguns erros ao executar o aplicativo em um prompt de comando no sistema de hospedagem. Para registrar detalhes adicionais do aplicativo, diminua o nível de log ou execute o aplicativo no Ambiente de desenvolvimento.

Limpar caches de pacote

Um aplicativo em funcionamento pode falhar imediatamente depois de atualizar o SDK do .NET Core no computador de desenvolvimento ou alterar as versões do pacote dentro do aplicativo. Em alguns casos, pacotes incoerentes podem interromper um aplicativo ao executar atualizações principais. A maioria desses problemas pode ser corrigida seguindo estas instruções:

1. Exclua as pastas bin e obj.

2. Limpe os caches de pacote executando dotnet nuget locals all --clear de um shell de comando.

   Também é possível limpar os caches de pacote com a ferramenta nuget.exe e executando o comando nuget locals all -clear. nuget.exe não é uma instalação fornecida com o sistema operacional Windows Desktop e devem ser obtidos separadamente do site do NuGet.

3. Restaure e recompile o projeto.

4. Exclua todos os arquivos na pasta de implantação no servidor antes de reimplantar o aplicativo.

Aplicativo lento ou sem resposta

Um despejo de memória é um instantâneo da memória do sistema e pode ajudar a determinar a causa de uma falha de aplicativo, falha de inicialização ou lentidão de aplicativo.

O aplicativo falha ou encontra uma exceção

Obter e analisar um despejo de memória do WER (Relatório de Erros do Windows):

1. Crie uma pasta para armazenar os arquivos de despejo de memória em c:\dumps.

2. Execute o script do PowerShell EnableDumps com o nome executável do aplicativo:

   .\EnableDumps {APPLICATION EXE} c:\dumps
   

3. Execute o aplicativo sob as condições que causam a falha.

4. Após a falha, execute o script DisableDumps do PowerShell:

   .\DisableDumps {APPLICATION EXE}
   

Depois que um aplicativo falhar e a coleta de despejo de memória for concluída, o aplicativo terá permissão para encerrar normalmente. O script do PowerShell configura o WER para coletar até cinco despejos de memória por aplicativo.

Aviso

Os despejos de memória podem usar uma grande quantidade de espaço em disco (até vários gigabytes cada).

O aplicativo não responde, falha durante a inicialização ou executa normalmente

Quando um aplicativo travar (para de responder, mas não falha), falhar durante a inicialização ou executar normalmente, veja Arquivos de despejo de memória do modo de usuário: escolher a melhor ferramenta para selecionar uma ferramenta adequada para produzir o despejo de memória.

Analisar o despejo de memória

Um despejo de memória pode ser analisado usando várias abordagens. Para obter mais informações, confira Analisando um arquivo de despejo de memória do modo de usuário.

Recursos adicionais

• Exibir ou baixar código de exemplo (como baixar)
• Configuração do ponto de extremidade Kestrel (inclui a configuração HTTPS e suporte à SNI)
• Host genérico do .NET no ASP.NET Core
• Solucionar problemas e depurar projetos do ASP.NET Core