NLog para C# (.NET): guia completo com exemplos práticos

Bem-vindo ao guia detalhado sobre a biblioteca NLog para a plataforma .NET. NLog é um sistema de logging poderoso, flexível e de alto desempenho que se tornou o padrão de facto para muitos projetos .NET. Neste artigo, vamos abordar tudo: desde a instalação até técnicas avançadas, com exemplos reais de código e dicas de otimização.

1. O que é NLog e por que usá-la?

NLog (abreviação de ".NET Logging") é uma biblioteca gratuita e de código aberto para a plataforma .NET, projetada para logging flexível e eficiente. Ela permite que desenvolvedores gravem informações de diagnóstico (logs) em vários destinos: arquivos, console, bancos de dados, sockets de rede, sistemas de monitoramento (como Seq, Elasticsearch, Sentry) e muitos outros.

Por que o logging é importante? No desenvolvimento moderno de software, os logs são a "caixa-preta" da aplicação. Sem eles, é impossível entender por que um servidor caiu, onde ocorreu um erro ou quais dados estavam sendo processados no momento da falha. NLog resolve esse problema oferecendo:

Flexibilidade de roteamento: Configure diferentes níveis de logging (Trace, Debug, Info, Warn, Error, Fatal) para diferentes partes da aplicação.
Alto desempenho: Gravação assíncrona, inicialização preguiçosa (lazy loading) e impacto mínimo na velocidade da aplicação.
Extensibilidade: Centenas de targets prontos e a possibilidade de criar os seus próprios.
Configuração sem recompilação: Altere as configurações em tempo real via XML, JSON ou código.

NLog é ideal para: aplicações web (ASP.NET Core), utilitários de console, microsserviços, aplicações desktop (WPF/WinForms) e serviços em segundo plano (Windows Services, Worker Services).

2. Instalação

A instalação do NLog é feita através do gerenciador de pacotes NuGet. Execute um dos seguintes comandos no console do gerenciador de pacotes do Visual Studio ou no terminal do .NET CLI:

// Via .NET CLI (recomendado)
dotnet add package NLog

// Via Package Manager Console
Install-Package NLog

// Para ASP.NET Core, também é recomendado instalar a integração:
dotnet add package NLog.Web.AspNetCore

Após a instalação, você precisará criar um arquivo de configuração nlog.config na raiz do projeto (ou configurar o NLog programaticamente).

3. Início rápido — exemplo funcional mínimo

Crie um aplicativo de console e adicione o arquivo nlog.config (clique com o botão direito no projeto → Add → New Item → XML File → nomeie como nlog.config). Insira o seguinte conteúdo:

<?xml version="1.0" encoding="utf-8" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <!-- Target: para onde enviar os logs -->
    <targets>
        <target name="console" xsi:type="Console" layout="${longdate} | ${level:uppercase=true} | ${message} ${exception:format=ToString}" />
        <target name="file" xsi:type="File" fileName="${basedir}/logs/app-${shortdate}.log"
                layout="${longdate} | ${level:uppercase=true} | ${logger} | ${message} ${exception:format=ToString}" />
    </targets>

    <!-- Regras de roteamento -->
    <rules>
        <logger name="*" minlevel="Debug" writeTo="console,file" />
    </rules>
</nlog>

Agora, escreva o código no Program.cs:

using NLog;

public class Program
{
    // Criando um logger para a classe atual
    private static readonly Logger Logger = LogManager.GetCurrentClassLogger();

    public static void Main(string[] args)
    {
        Logger.Info("Aplicação iniciada");
        
        try
        {
            var result = Divide(10, 0);
            Logger.Debug($"Resultado: {result}");
        }
        catch (Exception ex)
        {
            Logger.Error(ex, "Erro ao executar divisão");
        }
        
        Logger.Info("Aplicação finalizada");
    }

    static int Divide(int a, int b)
    {
        return a / b;
    }
}

Ao executar o programa, você verá os logs no console e, simultaneamente, eles serão salvos no arquivo logs/app-{data}.log. O NLog cuida de todo o roteamento automaticamente!

4. Níveis de logging

O NLog oferece seis níveis de logging, do mais detalhado ao mais crítico:

Trace (0) — Informações de depuração extremamente detalhadas. Use apenas em desenvolvimento.
Debug (1) — Informações úteis para depuração em ambientes de desenvolvimento e teste.
Info (2) — Mensagens informativas sobre o fluxo normal da aplicação (ex: "Serviço iniciado").
Warn (3) — Avisos sobre situações inesperadas que não impedem o funcionamento (ex: "Arquivo não encontrado, usando padrão").
Error (4) — Erros que afetam uma operação específica, mas não derrubam a aplicação.
Fatal (5) — Erros críticos que forçam o encerramento da aplicação.

Você pode configurar diferentes níveis mínimos para diferentes partes da aplicação. Por exemplo, em produção, é comum usar minlevel="Info" para evitar o excesso de logs de depuração.

5. Targets populares

Os targets definem para onde os logs serão enviados. Aqui estão alguns dos mais usados:

Target	Descrição	Exemplo de uso
`Console`	Exibe logs no console/terminal	Desenvolvimento local, depuração
`File`	Grava logs em arquivos de texto	Produção, análise posterior
`Database`	Armazena logs em bancos de dados (SQL Server, PostgreSQL, etc.)	Sistemas corporativos, auditoria
`Mail`	Envia logs por e-mail	Alertas de erros críticos
`Seq`	Envia logs para o Seq (plataforma de análise de logs)	Monitoramento centralizado
`ElasticSearch`	Envia logs para o Elasticsearch (via Kibana)	Análise avançada de logs

6. Conclusão

NLog é uma ferramenta indispensável para qualquer desenvolvedor .NET que leva a sério a qualidade e a manutenibilidade do seu software. Com sua configuração flexível, alto desempenho e vasto ecossistema de targets, ela se adapta desde pequenos projetos pessoais até grandes sistemas corporativos.

Comece implementando o exemplo básico deste guia e, gradualmente, explore recursos mais avançados como filtros, layouts personalizados e targets assíncronos. Seu futuro eu (e sua equipe) agradecerão quando precisarem depurar um problema em produção!

Para mais informações, consulte a documentação oficial do NLog.