Host ASP.NET Core em um serviço do Windows

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

Pré-requisitos

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

Modelo de Serviço do Trabalhador

O modelo ASP.NET Core Worker Service fornece um ponto de partida para escrever aplicativos de serviço de longa execução. Para usar o modelo como base para um aplicativo de serviço do Windows:

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

Visual Studio

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

Visual Studio para Mac

1. Crie um novo projeto.
2. Selecione App sob .NET Core na barra lateral.
3. Selecione Worker em ASP.NET Core. Selecione Avançar.
4. Selecione .NET Core 3.0 ou posterior para o Target Framework. Selecione Avançar.
5. Forneça um nome no campo Nome do Projeto. Selecione Criar.

Use o modelo Serviço de Trabalhador (worker) com o comando dotnet new a partir de um shell de comandos. No exemplo a seguir, um aplicativo de Serviço de Trabalho é criado chamado 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 do Windows, AddWindowsService:

• Define o tempo de vida do host como WindowsServiceLifetime.
• Define como raiz de conteúdo para AppContext.BaseDirectory. Para obter mais informações, consulte a seção "Diretório Atual" e "Raiz do Conteúdo".
• Permite o registo no log de eventos.
  • O nome do aplicativo é usado como o nome de origem padrão.
  • O nível de registo padrão é Aviso ou mais alto para uma aplicação baseada num modelo ASP.NET Core que chama CreateDefaultBuilder para construir o anfitrião.
  • Substitua o nível de log predefinido pela chave Logging:EventLog:LogLevel:Default em appsettings.json/appsettings.{Environment}.json ou noutro fornecedor de configuração.
  • Apenas os administradores podem criar novas fontes de eventos. Quando não é possível criar uma fonte de eventos usando o nome da aplicação, um aviso é registrado na origem Application e os logs de eventos são desativados.

Considere a seguinte classe ServiceA:

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 seguinte Program.cs 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 Trabalhador em Segundo Plano: um exemplo de aplicativo não Web baseado no modelo Serviço de Trabalhador que usa de serviços hospedados para tarefas em segundo plano.
• Exemplo de Serviço de Aplicação Web: um exemplo de aplicação web Razor Páginas que é executado como um Serviço do Windows com serviços hospedados para tarefas em segundo plano.

Para obter orientação sobre MVC, consulte os artigos sob Visão geral do ASP.NET Core MVC e Migrar do ASP.NET Core 2.2 para 3.0.

Tipo de implantação

Para obter informações e conselhos sobre cenários de implantação, consulte : implantação de aplicativos .NET Core.

SDK

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 do trabalhador no arquivo de projeto:

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

Implementação dependente de plataforma (FDD)

A implementação dependente de framework (FDD) depende da presença de uma versão compartilhada do .NET Core em todo o sistema de destino. Quando o cenário FDD é adotado de acordo com as orientações deste artigo, o SDK produz um executável (.exe), chamado um executável dependente do framework.

Se estiver usando o Web SDK, um arquivo web.config, que normalmente é produzido ao publicar um aplicativo ASP.NET Core, é desnecessário para um aplicativo de Serviços do Windows. Para desativar a criação do arquivo web.config, adicione a propriedade <IsTransformWebConfigDisabled> definida como true.

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

Implementação autónoma (SCD)

A implantação autônoma (SCD) não depende da presença de uma estrutura compartilhada no sistema host. O tempo de execução e as dependências do aplicativo são implantados com o aplicativo.

Um do Identificador do Tempo de Execução do Windows (RID) está incluído no que contém a estrutura de destino:

<RuntimeIdentifier>win-x64</RuntimeIdentifier>

Para publicar em vários RIDs:

• Forneça os RIDs em uma lista delimitada por ponto-e-vírgula.
• Utilize 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.

No Windows 10 October 2018 Update (versão 1809/build 10.0.17763) ou posterior:

New-LocalUser -Name {SERVICE NAME}

No sistema operacional 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 menos que o parâmetro -AccountExpires seja fornecido ao cmdlet New-LocalUser com uma expiração DateTime, a conta não expira.

Para obter mais informações, consulte Microsoft.PowerShell.LocalAccounts e Service User Accounts.

Uma abordagem alternativa para gerenciar usuários ao usar o Ative Directory é usar Contas de Serviço Gerenciado. Para obter mais informações, consulte a Visão Geral de Contas de Serviço Gerido de Grupo .

Direitos de início de sessão como serviço

Para estabelecer Iniciar sessão como um serviço direitos para uma conta de utilizador de serviço:

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

Criar e gerenciar o Serviço do 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 executável do aplicativo no host (por exemplo, d:\myservice). Não inclua o nome do arquivo executável do aplicativo no caminho. Não é necessária uma barra final.
• {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 executável completo do aplicativo (por exemplo, d:\myservice\myservice.exe). Inclua o nome do arquivo do executável com a extensão.
• {EXE FOLDER PATH}: O caminho completo da pasta executável 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 um 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 de um 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

Interromper 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 um serviço com o seguinte comando do PowerShell 6:

Remove-Service -Name {SERVICE NAME}

Cenários de servidor proxy e 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 balanceador de carga podem exigir configuração adicional. Para obter mais informações, consulte Configurar ASP.NET Core para trabalhar com servidores proxy e balanceadores de carga.

Configurar pontos de extremidade

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

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

• Configurar endpoints para o servidor web ASP.NET Core Kestrel
• HTTP.sys implementação de servidor web no ASP.NET Core

As orientações anteriores abrangem o suporte a endpoints HTTPS. Por exemplo, configure o aplicativo para HTTPS quando a autenticação for usada com um Serviço do Windows.

Observação

O uso do certificado de desenvolvimento HTTPS do ASP.NET Core para proteger um ponto de extremidade de serviço não é suportado.

Diretório atual e raiz de conteúdo

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

Usar ContentRootPath ou ContentRootFileProvider

Use ou ContentRootFileProvider IHostEnvironment.ContentRootPath para localizar os recursos de um 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 ficheiros de configuração carregados pelo código do programador no ConfigureAppConfiguration, não há necessidade de 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 para obter um caminho de recurso porque um aplicativo de serviço do Windows retorna a pasta C:\WINDOWS\system32 como seu diretório atual.

Armazene os arquivos de um serviço em um local adequado no disco

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

Solução de problemas

Para solucionar problemas de um aplicativo de serviço Windows, consulte Solucionar problemas e depurar projetos 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 o publicado do aplicativo saída do comando dotnet publish. A saída do comando dotnet build não é suportada para a implantação da aplicação. Os ativos publicados são encontrados em 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 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 Fazer logon como um serviço direitos.
• A senha do usuário expirou ou foi passada incorretamente ao executar o comando New-Service PowerShell.
• O aplicativo requer autenticação ASP.NET Core, mas não está configurado para conexões seguras (HTTPS).
• A porta URL da solicitação está incorreta ou não está configurada corretamente no aplicativo.

Logs de eventos do sistema e do aplicativo

Acesse os logs de eventos do sistema e do aplicativo:

1. Abra o menu Iniciar, procure o Visualizador de Eventose selecione a aplicação Visualizador de Eventos.
2. Em Visualizador de Eventos, abra o nó Logs do Windows.
3. Selecione Sistema para abrir o registo de eventos do sistema. Selecione Aplicação para abrir o Log de Eventos da Aplicação.
4. Procure pelos erros associados à aplicação com falha.

Execute o aplicativo em um prompt de comando

Muitos erros de inicialização não produzem informações úteis nos logs de eventos. Você pode encontrar a causa de alguns erros executando 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 pacotes

Um aplicativo em funcionamento pode falhar imediatamente após atualizar o SDK do .NET Core na máquina de desenvolvimento ou alterar as versões do pacote no aplicativo. Em alguns casos, pacotes incoerentes podem quebrar um aplicativo ao executar grandes atualizações. A maioria desses problemas pode ser corrigida seguindo estas instruções:

1. Apague as pastas do compartimento e obj .

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

   A limpeza de caches de pacotes também pode ser realizada com a ferramenta nuget.exe e executando o comando nuget locals all -clear. nuget.exe não é uma instalação integrada com o sistema operacional de desktop Windows e deve ser obtida separadamente do site NuGet.

3. Restaure e reconstrua o projeto.

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

Aplicação lenta 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 aplicação, falha de inicialização ou aplicação lenta.

O aplicativo falha ou encontra uma exceção

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

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

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

   .\EnableDumps {APPLICATION EXE} c:\dumps
   

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

4. Depois que a falha tiver ocorrido, execute o script DisableDumps PowerShell:

   .\DisableDumps {APPLICATION EXE}
   

Depois que um aplicativo falha e a coleta de despejo é concluída, o aplicativo pode ser encerrado normalmente. O script do PowerShell configura o WER para coletar até cinco despejos por aplicativo.

Advertência

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

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

Quando um aplicativo para de responder, mas não falha, falha durante a inicialização ou funciona normalmente, consulte User-Mode Arquivos de despejo: Escolhendo a melhor ferramenta para selecionar uma ferramenta apropriada para produzir o despejo.

Analise o despejo

Um despejo pode ser analisado usando várias abordagens. Para obter mais informações, consulte Analisando um ficheiro de despejo User-Mode.

Recursos adicionais

• Visualizar ou baixar código de exemplo (como fazer download)
• Configuração de endpointKestrel (inclui configuração de HTTPS e suporte a SNI)
• Host Genérico do .NET no ASP.NET Core
• Solucionar problemas e depurar ASP.NET projetos principais