NFeSchemaDownloader 0.2.6

NFeSchemaDownloader é uma biblioteca .NET projetada para baixar e organizar os Schemas XML (XSD) oficiais e manter atualizados nos seus projetos.

Biblioteca e CLI em .NET utilizando Playwright.

O projeto tem dois formatos de uso:

• NFeSchemaDownloader: biblioteca para integração direta em sistemas .NET, workers e ERPs.
• NFeSchemaDownloader.Cli: ferramenta de linha de comando para uso em pipelines de CI/CD (GitHub Actions, etc).

Por que usar o NFeSchemaDownloader?

Todo sistema que faz emissão, consultas ou validação de Documentos Fiscais Eletrônicos (NF-e, NFC-e) precisa manter os arquivos XSD (Schemas XML) atualizados para garantir que o XML gerado está nas regras vigentes da SEFAZ.

O problema: Tradicionalmente, os desenvolvedores precisam acessar o portal da SEFAZ, procurar manualmente pelas atualizações, baixar e procurar dentro de zip um por um etc. Isso é chato, propenso a erros e fácil de esquecer.

A solução: Com a nossa biblioteca, você simplesmente instala o pacote e ele faz todo esse trabalho para você! O NFeSchemaDownloader usa um navegador headless (Playwright) para lidar de forma transparente com as políticas de acesso e validações do portal, identifica automaticamente as versões oficiais desde 2017 e extrai os novos Schemas direto para a sua pasta schemas/v4/. Sem dor de cabeça, sem downloads manuais.

Recursos

• Compatível com .NET 10.
• Download inteligente com bypass utilizando Microsoft.Playwright.
• Download performático e paralelo via HttpClient herdando cookies validados do navegador.
• Extração de arquivos .xsd diretamente em memória a partir dos arquivos .zip.
• Suporte para execução isolada como CLI e forte tipagem para uso como Biblioteca C#.

Instalação Como Biblioteca

Quando publicado no NuGet:

dotnet add package NFeSchemaDownloader

Uso básico para baixar e sincronizar os schemas:

using NFeSchemaDownloader;

// Executa a automação completa: abre o Playwright, varre a SEFAZ e baixa para a pasta local
await NFeSchemaManager.SyncSchemasAsync();

Isso criará automaticamente a pasta schemas/v4 na raiz de execução e colocará todos os XSDs sempre em sua versão mais atualizada!

Também é possível cancelar a sincronização de forma cooperativa:

using NFeSchemaDownloader;

using var cts = new CancellationTokenSource(TimeSpan.FromMinutes(5));
await NFeSchemaManager.SyncSchemasAsync(cts.Token);

Uso com Dependency Injection

Para workers, APIs e aplicações com IServiceCollection, registre os serviços com AddNFeSchemaDownloader:

using Microsoft.Extensions.DependencyInjection;
using NFeSchemaDownloader;

var services = new ServiceCollection();

services.AddNFeSchemaDownloader(options =>
{
    options.ExtractionDirectory = "schemas/v4";
    options.MaxDownloadConcurrency = 2;
    options.HttpTimeout = TimeSpan.FromMinutes(2);
    options.PlaywrightNavigationTimeout = TimeSpan.FromSeconds(90);
    options.RetryCount = 3;
    options.RetryBaseDelay = TimeSpan.FromSeconds(1);
    options.ValidateExtractedSchemas = false;
});

using var serviceProvider = services.BuildServiceProvider();
var syncService = serviceProvider.GetRequiredService<INFeSchemaSyncService>();

await syncService.SyncSchemasAsync();

Para acompanhar progresso em uma UI, worker ou pipeline, registre IProgress<NFeSchemaSyncProgress>:

services.AddSingleton<IProgress<NFeSchemaSyncProgress>>(
    new Progress<NFeSchemaSyncProgress>(progress =>
    {
        Console.WriteLine(progress.Message);
    }));

Opções Disponíveis

Uso do CLI

Execute o projeto CLI diretamente durante desenvolvimento:

dotnet run --project .\NFeSchemaDownloader.Cli\NFeSchemaDownloader.Cli.csproj -- --output-dir schemas/v4

Exemplos:

dotnet run --project .\NFeSchemaDownloader.Cli\NFeSchemaDownloader.Cli.csproj -- --dry-run
dotnet run --project .\NFeSchemaDownloader.Cli\NFeSchemaDownloader.Cli.csproj -- --output-dir C:\schemas\nfe --concurrency 3
dotnet run --project .\NFeSchemaDownloader.Cli\NFeSchemaDownloader.Cli.csproj -- --timeout 120 --retry-count 5 --retry-delay 2
dotnet run --project .\NFeSchemaDownloader.Cli\NFeSchemaDownloader.Cli.csproj -- --playwright-timeout 180
dotnet run --project .\NFeSchemaDownloader.Cli\NFeSchemaDownloader.Cli.csproj -- --force
dotnet run --project .\NFeSchemaDownloader.Cli\NFeSchemaDownloader.Cli.csproj -- --validate-schemas
dotnet run --project .\NFeSchemaDownloader.Cli\NFeSchemaDownloader.Cli.csproj -- --json-logs

Flags disponíveis:

Manifesto Incremental

O downloader cria um manifesto local chamado .nfe-schema-manifest.json dentro do diretório de extração. Ele registra os pacotes processados, os metadados HTTP observados no download (Content-Type, Content-Length, ETag, Last-Modified e filename remoto) e os XSDs extraídos com tamanho e SHA-256.

Quando overwrite está desativado, pacotes já registrados no manifesto são ignorados para evitar downloads redundantes. No CLI, use --force quando quiser baixar e sobrescrever novamente.

Extração Transacional

Os XSDs são extraídos primeiro para um diretório temporário dentro da pasta de saída. A biblioteca só promove os arquivos para o destino final depois que a extração e as validações opcionais terminam com sucesso. Se algo falhar no meio do processo, os arquivos finais existentes são preservados.

Playwright e Testes de Integração

O scraper usa Playwright para abrir o portal da SEFAZ em navegador headless. Em ambientes novos, instale os browsers do Playwright antes de rodar a automação real:

pwsh .\NFeSchemaDownloader\bin\Debug\net10.0\playwright.ps1 install

Os testes de integração que acessam a SEFAZ real ficam desativados por padrão. Para executá-los:

$env:NFESCHEMA_RUN_INTEGRATION_TESTS='true'
dotnet test --filter Category=Integration

Uso Automático no GitHub (CI/CD)

O poder real dessa ferramenta é deixar rodando em nuvem. Se você olhar o código fonte deste repositório, verá que utilizamos o projeto NFeSchemaDownloader.Cli em um arquivo .github/workflows/publish.yml.

Toda segunda-feira, de forma automática, o robô roda esse projeto na nuvem, acessa a SEFAZ, baixa novos XSDs se existirem e faz o commit direto na branch principal do repositório, além de bump de versão e publicação no NuGet automatizada!

Estrutura

• NFeSchemaDownloader: biblioteca reutilizável e pacote NuGet.
• NFeSchemaDownloader.Cli: CLI para rodar a automação no GitHub Actions.
• schemas: pasta oficial mantida sempre atualizada pelo robô onde ficam todos os XSDs extraídos.

Troubleshooting

🔗 Projetos relacionados

O ecossistema fiscal open-source é gigante! Conheça também:

Fluxo recomendado

NFeSchemaDownloader (Mantém os arquivos XSD atualizados para validação prévia)
   │
   ▼
NFEEmissor (Gera o XML da NF-e)
   │
   ▼
NF-e XML
   │
   ▼
NFEConsulta (Valida XML e consulta autorização)
   │
   ▼
NFEDanfe (Gera o PDF final)

👨‍💻 Autor

Fabyo Guimarães Oliveira

• LinkedIn: https://www.linkedin.com/in/fabyo-guimaraes/
• GitHub: https://github.com/fabyo

Licença

MIT.