Hangfire para C# (.NET): guia completo com exemplos

O que é Hangfire e para que serve?

Hangfire é uma biblioteca poderosa e popular para C# (.NET), projetada para executar tarefas em segundo plano (background jobs). No desenvolvimento web moderno, surge frequentemente a necessidade de realizar operações que não devem bloquear o fluxo principal de execução da aplicação. Por exemplo: envio de notificações por e-mail, geração de relatórios, processamento de arquivos carregados, sincronização de dados com APIs externas, limpeza de registros obsoletos no banco de dados e muito mais.

Hangfire fornece uma maneira simples, mas flexível, de executar essas tarefas. Os principais recursos da biblioteca são:

\n
• Execução de tarefas em segundo plano: As tarefas são executadas de forma assíncrona, sem bloquear a resposta ao usuário.
\n
• Agendamento: É possível executar tarefas conforme uma programação (expressões cron) ou com atraso.
\n
• Confiabilidade: Hangfire salva as informações das tarefas em um armazenamento persistente (banco de dados). Mesmo que a aplicação seja reiniciada, as tarefas não concluídas serão executadas.
\n
• Monitoramento: Uma interface web integrada (Dashboard) permite acompanhar o status das tarefas, visualizar logs e reexecutar tarefas com falha.
\n
• Tentativas repetidas: Se uma tarefa falhar, o Hangfire tentará executá-la novamente automaticamente (com uma política de repetição configurável).
\n
• Integração com DI: Integra-se facilmente com contêineres de injeção de dependência (Dependency Injection) no ASP.NET Core.
\n

Hangfire suporta vários armazenamentos: SQL Server, PostgreSQL, Redis, MongoDB e outros. Isso o torna adequado para projetos de qualquer escala — desde pequenos sites até sistemas corporativos de alta carga.

Instalação

Hangfire é instalado através do NuGet Package Manager. Diferente do Python, onde se usa pip install, no ecossistema .NET utiliza-se dotnet add package ou o gerenciador de pacotes do Visual Studio.

Para instalar o pacote base do Hangfire, execute o comando no terminal (na pasta raiz do seu projeto):

dotnet add package Hangfire

Este comando instalará o núcleo do Hangfire e as dependências para armazenamento de tarefas em memória (InMemory). Para um ambiente de produção, você precisará instalar o pacote para um banco de dados específico, por exemplo:

\n
• SQL Server: dotnet add package Hangfire.SqlServer
\n
• PostgreSQL: dotnet add package Hangfire.PostgreSql
\n
• Redis: dotnet add package Hangfire.Redis
\n

Após a instalação dos pacotes, é necessário configurar o Hangfire no arquivo Program.cs (para ASP.NET Core) ou Startup.cs.

Início rápido

Vamos considerar um exemplo mínimo de configuração e uso do Hangfire em uma aplicação ASP.NET Core.

Passo 1: Configuração no Program.cs

using Hangfire;\nusing Hangfire.SqlServer;\n\nvar builder = WebApplication.CreateBuilder(args);\n\n// Adicionando Hangfire com armazenamento SQL Server\nbuilder.Services.AddHangfire(configuration => configuration\n    .SetDataCompatibilityLevel(CompatibilityLevel.Version_180)\n    .UseSimpleAssemblyNameTypeSerializer()\n    .UseRecommendedSerializerSettings()\n    .UseSqlServerStorage(builder.Configuration.GetConnectionString("HangfireConnection")));\n\n// Adicionando o servidor Hangfire\nbuilder.Services.AddHangfireServer();\n\nvar app = builder.Build();\n\n// Habilitando o Dashboard (painel de monitoramento)\napp.UseHangfireDashboard();\n\n// Exemplo de tarefa em segundo plano simples\napp.MapGet("/fire-and-forget", () =>\n{\n    var jobId = BackgroundJob.Enqueue(() => Console.WriteLine("Hello from Hangfire!"));\n    return $"Job {jobId} foi enfileirado.";\n});\n\napp.Run();

Passo 2: Criando uma tarefa

No exemplo acima, usamos o método <