Forem: Alberto Monteiro

Como testei minha aplicação Blazor Server de ponta a ponta com Aspire e Playwright

Alberto Monteiro — Sun, 29 Mar 2026 12:00:00 +0000

Fala galera, tudo beleza?!

Recentemente precisei escrever testes de integração para uma aplicação Blazor Server orquestrada com .NET Aspire. A aplicação tem dependências reais: um banco PostgreSQL, um serviço externo mockado com WireMock, e uma interface Blazor com rendermode InteractiveServer. O desafio era subir tudo isso dentro dos testes, interagir com a interface como um usuário real faria, e validar que as peças se conectavam de verdade — do clique no botão até a chamada na API externa.

Nesse artigo vou contar a jornada: desde subir o AppHost nos testes com Aspire.Hosting.Testing, passando pela armadilha do AngleSharp com InteractiveServer, até fazer o Playwright baixar o próprio browser em C# sem depender de PowerShell.

Aspire.Hosting.Testing, ou: subir o mundo inteiro para testar

O .NET Aspire já facilita muito a orquestração local da aplicação, e o pacote Aspire.Hosting.Testing — que eu já uso para testes de integração de REST APIs — permite instanciar o AppHost inteiro dentro dos seus testes. O xUnit sobe o PostgreSQL em container, o WireMock, e a aplicação Blazor — tudo como se fosse o ambiente real. A diferença aqui foi aplicar isso num contexto com UI interativa, onde só ter o servidor no ar não é suficiente.

Para isso, criei uma AppHostFixture que implementa IAsyncLifetime do xUnit, garantindo que o ambiente sobe antes dos testes e é descartado ao final:

public sealed class AppHostFixture : IAsyncLifetime
{
    public ProjectAppHost AppHost { get; private set; } = default!;
    public HttpClient AppHostClient { get; private set; } = default!;
    public HttpClient WireMock { get; private set; } = default!;

    public async Task InitializeAsync()
    {
        AppHost = new ProjectAppHost();
        await AppHost.StartAsync();

        AppHostClient = AppHost.CreateHttpClient("minha-app-web");
        WireMock = AppHost.CreateHttpClient("api-mock");

        await ApplyMigrationsAsync();
    }

    public async Task DisposeAsync()
        => await AppHost.DisposeAsync();

    private async Task ApplyMigrationsAsync()
    {
        var connectionString = await AppHost.GetConnectionString("Default");

        var options = new DbContextOptionsBuilder<ApplicationDbContext>()
            .UseNpgsql(connectionString)
            .Options;

        using var context = new ApplicationDbContext(options);
        await context.Database.MigrateAsync(); // <- aplica as migrations no banco de teste
    }
}

O CreateHttpClient("nome-do-serviço") retorna um HttpClient já apontando para a porta correta que o Aspire escolheu para aquele serviço. Simples assim.

Agora, sobre o ProjectAppHost: a documentação oficial do Aspire mostra o uso direto do DistributedApplicationTestingBuilder — que é a forma mais simples de subir o AppHost nos testes. Mas eu precisava de mais controle, então criei uma classe própria herdando de DistributedApplicationFactory:

public sealed class ProjectAppHost() : DistributedApplicationFactory(typeof(Projects.My_App))
{
    protected override void OnBuilderCreating(DistributedApplicationOptions applicationOptions, HostApplicationBuilderSettings hostOptions)
    {
        // Suporte ao proxy de imagens Docker do GitLab CI
        applicationOptions.ContainerRegistryOverride =
            Environment.GetEnvironmentVariable("CI_DEPENDENCY_PROXY_DIRECT_GROUP_IMAGE_PREFIX");

        applicationOptions.AllowUnsecuredTransport = true;
        hostOptions.Args = ["--testmode=true"]; // <- flag lida no AppHost para ajustar comportamento em testes
    }

    protected override void OnBuilderCreated(DistributedApplicationBuilder builder)
       => builder.Services.ConfigureHttpClientDefaults(x => x.AddStandardResilienceHandler(c =>
       {
           var timeSpan = TimeSpan.FromMinutes(2);
           c.AttemptTimeout.Timeout = timeSpan;
           c.CircuitBreaker.SamplingDuration = timeSpan * 2;
           c.TotalRequestTimeout.Timeout = timeSpan * 3; // <- containers demoram mais para subir em CI
       }));
}

O OnBuilderCreating e o OnBuilderCreated são os hooks que a DistributedApplicationFactory expõe para você customizar antes e depois de o builder ser criado. Os dois motivos principais que me fizeram ir por esse caminho em vez do DistributedApplicationTestingBuilder padrão:

ContainerRegistryOverride: no pipeline CI/CD, usamos um proxy de imagens Docker do GitLab. Essa propriedade redireciona os pulls de container para esse proxy sem precisar alterar o AppHost original.
Timeouts generosos: containers demoram mais para subir em agentes de CI do que na sua máquina. Sem ajustar os timeouts do resilience handler, os testes quebram por timeout antes mesmo de o ambiente estar pronto.

Se você não precisar dessas configurações, o DistributedApplicationTestingBuilder resolve com muito menos código — a documentação oficial mostra bem como usá-lo.

Também rodei as migrations direto no InitializeAsync, pegando a connection string dinâmica do AppHost. Assim o banco começa limpo e com o schema correto a cada sessão de testes.

Para amarrar a fixture com os testes, basta usar as collections do xUnit:

[CollectionDefinition("AppTestCollection", DisableParallelization = true)]
public class AppTestCollection : ICollectionFixture<AppHostFixture>;

O DisableParallelization = true é importante — os testes que sobem containers não se dão bem rodando em paralelo.

AngleSharp parecia a escolha óbvia, ou: InteractiveServer muda tudo

Com o ambiente no ar, a próxima etapa era interagir com a interface. Minha primeira tentativa foi o AngleSharp, uma lib C# para parsear e navegar HTML. Ela é leve, roda in-process, e já usei ela antes em projetos mais simples.

O problema foi o rendermode InteractiveServer.

O formulário já tinha o FormName configurado corretamente no EditForm. Mesmo assim, ao tentar submeter via AngleSharp, aparecia esse erro:

The POST request does not specify which form is being submitted.
To fix this, ensure <form> elements have a @formname attribute
with any unique value, or pass a FormName parameter if using <EditForm>.

O AngleSharp faz requisições HTTP comuns — ele não executa JavaScript e não entende o protocolo do Blazor Interactive. O rendermode InteractiveServer do Blazor Server usa SignalR para manter o circuit entre browser e servidor: é por meio dessa conexão que os eventos, o state binding e os submits do formulário são processados. O AngleSharp simplesmente não estabelece essa conexão.

No meu caso, a aplicação usa MudBlazor, e o rendermode InteractiveServer é necessário para que os componentes MudBlazor funcionem corretamente. Não era uma questão de ajustar o FormName — o problema era estrutural. A solução certa era usar um browser de verdade.

Microsoft.Playwright, ou: um browser real dentro do teste

O Microsoft.Playwright é o binding .NET do Playwright — permite controlar um browser real (Chromium, Firefox ou WebKit) de forma programática. Com ele, o teste navega pela interface como um usuário faria: preenche campos, clica em botões, espera elementos aparecerem.

O grande problema prático do Playwright é o processo de instalação do browser. O pacote NuGet não vem com o executável do Chromium — você precisa rodar um script PowerShell para baixar:

pwsh bin/Debug/net10.0/playwright.ps1 install

Isso funciona bem na sua máquina. Mas em pipelines de CI/CD? Vai depender de ter o PowerShell instalado no agente, o que em muitos ambientes — especialmente imagens Linux minimalistas — não é garantido. Não gosto de criar essa dependência.

nor0x.Playwright.BrowserDownloader, ou: adeus PowerShell

Foi aí que encontrei a lib nor0x.Playwright.BrowserDownloader. Ela resolve exatamente esse problema: permite fazer o download do browser dentro do próprio código C#, sem nenhuma dependência externa.

var downloader = new BrowserDownloader();
var executablePath = await downloader.DownloadBrowserAsync(BrowserInfo.Chromium, TargetPlatform.Win64);

Duas linhas. O DownloadBrowserAsync baixa o Chromium (ou Firefox, WebKit) para a plataforma especificada e retorna o caminho do executável. Aí é só passar esse path para o Playwright na hora de iniciar o browser:

await playwright.Chromium.LaunchAsync(new BrowserTypeLaunchOptions
{
    ExecutablePath = executablePath // <- sem esse path, o Playwright não encontra o Chromium
});

Isso é muito elegante!!! O pipeline de CI não precisa saber nada sobre Playwright — o próprio teste cuida de provisionar o browser.

O teste completo, ou: preenche, clica e verifica até a API externa

Com tudo no lugar, o teste ficou assim:

[Collection("AppTestCollection")]
public sealed class CreateVariablesHappyPathTests(AppHostFixture fixture)
{
    private readonly AppHostFixture _fixture = fixture;

    [Fact]
    public async Task CreateVariablesPage_WithValidRequest_ShouldCreateVariablesAndPersistAuditLog()
    {
        // Arrange
        const string REPO_URL = "https://gitlab.com/my-group/my-project";
        const string SECRET_NAME = "my-secret-name";
        const string HML_USERNAME = "user_hml";
        const string HML_KEY = "key_hml_value";
        const string PRD_USERNAME = "user_prd";
        const string PRD_KEY = "key_prd_value";

        var downloader = new BrowserDownloader();
        var executablePath = await downloader.DownloadBrowserAsync(BrowserInfo.Chromium, TargetPlatform.Win64);

        using var playwright = await Playwright.CreateAsync();
        await using var browser = await playwright.Chromium.LaunchAsync(new BrowserTypeLaunchOptions
        {
            ExecutablePath = executablePath
        });

        var context = await browser.NewContextAsync();
        var page = await context.NewPageAsync();

        // Act
        await page.GotoAsync(_fixture.AppHostClient.BaseAddress.ToString());
        await page.WaitForSelectorAsync("form");

        await page.GetByTestId("repourl").FillAsync(REPO_URL);
        await page.GetByTestId("secretname").FillAsync(SECRET_NAME);
        await page.GetByTestId("hmlusername").FillAsync(HML_USERNAME);
        await page.GetByTestId("hmlkey").FillAsync(HML_KEY);
        await page.GetByTestId("prdusername").FillAsync(PRD_USERNAME);
        await page.GetByTestId("prdkey").FillAsync(PRD_KEY);

        var button = page.GetByRole(AriaRole.Button, new() { Name = "Criar Variáveis" });
        await button.ClickAsync();

        // Assert — interface
        var alert = await page.WaitForSelectorAsync(".mud-alert-message");
        var message = await alert.TextContentAsync();
        message.Should().Be("Variáveis criadas com sucesso!");

        // Assert — chamada na API externa via WireMock
        var wiremock = RestClient.For<IWireMockAdminApi>(_fixture.WireMock.BaseAddress);
        var requests = await wiremock.GetRequestsAsync();
        requests.Should().Contain(r => r.MappingGuid == Guid.Parse("31D30833-3BB6-47F5-B0C7-4FD4143D3FBE"));
    }
}

O que acontece nesse teste, de ponta a ponta:

O Aspire sobe o PostgreSQL, o WireMock e a aplicação Blazor em containers reais
O BrowserDownloader baixa o Chromium
O Playwright abre o browser, navega para a aplicação e preenche o formulário
O Blazor processa o submit, chama a API externa (que está mockada pelo WireMock) e persiste no banco
O Playwright valida a mensagem de sucesso na interface
A assertion final consulta o WireMock via WireMock.Net.RestClient e verifica que a requisição com aquele mapping específico foi recebida

Esse último passo é o que torna o teste realmente valioso. Não basta a interface mostrar sucesso — eu consigo provar que a chamada HTTP para a API externa aconteceu do jeito certo.

O que ficou de aprendizado

Aspire.Hosting.Testing sobe o ambiente inteiro, mas migrations são sua responsabilidade. Ele cuida dos containers e das referências entre serviços com muito pouco código, e o CreateHttpClient com o nome do serviço já resolve os endereços dinâmicos. Mas as migrations do banco precisam ser aplicadas declarativamente no seu próprio código de teste — como no InitializeAsync da fixture — não acontecem automaticamente.

AngleSharp não serve para Blazor InteractiveServer. Não é limitação da lib — é a natureza do InteractiveServer. Se o componente precisa de SignalR para funcionar, você precisa de um browser real. Entender esse limite logo evita horas de tentativa e erro.

Nunca dependa de script externo para baixar browser em CI. O nor0x.Playwright.BrowserDownloader resolve isso elegantemente dentro do próprio código C#. O pipeline fica mais simples e autocontido.

WireMock + assertions nos requests fecha o ciclo do teste. Validar só a UI não é suficiente para testes de integração. Verificar que a requisição correta chegou no mock garante que toda a cadeia — UI → lógica → HTTP client — funcionou de verdade.

Use data-testid nos componentes desde o início. O GetByTestId do Playwright é a forma mais estável de localizar elementos. Não depende de texto, CSS ou estrutura do DOM — só do atributo que você mesmo colocou.

👉 Se você tiver dúvidas ou quiser trocar uma ideia sobre a abordagem, deixa nos comentários, vai ser muito legal!!!

Vou ficando por aqui, não deixe de comentar, um grande abraço!

#dotnet #blazor #aspire #playwright #testes #integrationtesting #csharp

NuGet Central Package Management: como criei uma dotnet tool pra limpar o lixo que ninguém limpa

Alberto Monteiro — Tue, 24 Mar 2026 12:39:10 +0000

Fala galera, tudo beleza?!

Se você trabalha com .NET e tem uma solution com mais do que meia dúzia de projetos, eu tenho certeza que já passou por aquele momento: você precisa atualizar um pacote NuGet e descobre que ele está numa versão no projeto A, outra versão no projeto B, e uma terceira versão no projeto C. Já tive muita dor de cabeça com isso. E olha que eu gosto de facilitar minha vida.

Foi aí que o Central Package Management (CPM) do NuGet mudou o jogo pra mim. Mas como nem tudo são flores, ao usar o CPM no dia a dia, percebi que ele cria um probleminha silencioso que ninguém fala. E eu não fui o único — tem uma issue aberta no repositório do NuGet sobre exatamente isso, e o time basicamente disse que não vai resolver.

Então eu fui lá e fiz.

Spoiler: ficou simples, prático e resolve uma dor real. Bora lá!

CPM do NuGet, ou: por que você deveria estar usando isso ontem

Se você ainda não conhece o Central Package Management, deixa eu te explicar rapidinho. A ideia é simples: ao invés de cada .csproj da sua solution declarar a versão dos pacotes NuGet que usa, você centraliza todas as versões num único arquivo chamado Directory.Packages.props na raiz do repositório.

Nos seus projetos, o PackageReference fica assim:

<!-- No .csproj — sem Version! -->
<PackageReference Include="Newtonsoft.Json" />

E no Directory.Packages.props:

<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>
  <ItemGroup>
    <PackageVersion Include="Newtonsoft.Json" Version="13.0.3" />
  </ItemGroup>
</Project>

Simples assim. Um arquivo, uma versão, todos os projetos alinhados.

Os benefícios são enormes:

Uma única fonte de verdade. Acabou aquela história de "no projeto X tá na versão 6, no projeto Y tá na 7". Tudo num lugar só.
Upgrade de pacotes sem sofrimento. Precisa atualizar o Entity Framework em 30 projetos? Muda uma linha. Uma. Linha.
Menos conflito de merge. Sabe quando dois devs em branches diferentes atualizam pacotes e o merge vira um pesadelo? Com CPM a mudança de versão fica concentrada num arquivo só, os conflitos diminuem drasticamente.
Projetos mais limpos. Os .csproj ficam enxutos, sem aquele monte de Version="x.y.z" espalhado.
Segurança da supply chain. Combinando CPM com Package Source Mapping, você controla de qual feed cada pacote pode vir. Pacotes internos só do seu feed privado, pacotes públicos só do nuget.org. E com lock files (packages.lock.json), o resultado é um grafo de dependências determinístico e auditável.
Pinning de dependências transitivas. Aquela dependência transitiva que veio com uma vulnerabilidade? Com o transitive pinning do CPM, você força a versão corrigida sem precisar ficar caçando de qual pacote ela veio.

Se você tem uma solution com mais de 3 ou 4 projetos, CPM é praticamente obrigatório. É mágico, é lindo!!!

O problema que ninguém fala, ou: o lixo silencioso no Directory.Packages.props

Beleza, CPM é maravilhoso. Mas tem um detalhe que me incomodava faz tempo.

No dia a dia do desenvolvimento, pacotes vão e vêm. Você adiciona um pacote pra testar algo, remove depois. Refatora um projeto e tira uma dependência. Troca uma lib por outra. O que acontece? O PackageReference sai do .csproj, mas a declaração de <PackageVersion> continua lá no Directory.Packages.props, sossegada, juntando poeira.

Com o tempo, aquele arquivo que deveria ser a sua fonte de verdade vira um cemitério de referências que ninguém mais usa. Num projeto grande, eu já vi Directory.Packages.props com dezenas de entradas órfãs. Isso gera confusão: alguém novo no time olha e pensa que o pacote é usado, tenta entender onde, perde tempo. Ou pior, na hora de fazer upgrade, você atualiza versão de pacote que nem está sendo usado.

O detalhe que me fez criar a ferramenta: o Dependabot enlouquecendo

E aqui vem a parte que dói de verdade. Se você usa Dependabot (ou qualquer ferramenta de atualização automática de dependências), ele vai ler o Directory.Packages.props e criar pull requests pra atualizar todos os pacotes listados ali — inclusive os que ninguém mais usa. Ou seja, o time recebe PRs, revisa, aprova, faz merge... tudo pra atualizar versão de pacote que nem está no código. É trabalho jogado fora, é ruído no workflow, é tempo que podia estar indo pra coisa que importa.

A issue no NuGet, ou: "não vamos resolver isso"

Eu não fui o primeiro a perceber. Existe a issue #13562 no repositório do NuGet que descreve exatamente esse problema: ao desinstalar um pacote, ele sai do .csproj mas fica no Directory.Packages.props. A resposta do time do NuGet? Que isso é intencional por design — porque no contexto de um projeto individual, o NuGet não tem como saber quantos outros projetos usam aquele Directory.Packages.props. Faz sentido do ponto de vista deles, mas o resultado prático é que a sujeira vai acumulando e ninguém limpa.

A sugestão que ficou foi que talvez no futuro isso virasse uma opção opt-in, um argumento de linha de comando ou uma opção na UI. Mas pelo que eu entendi, não está no radar de prioridades do time.

Então eu pensei: se o time do NuGet não vai resolver, eu resolvo.

Nasce o nuget-cpm-cleaner, ou: resolvendo em minutos o que levaria horas na mão

A ideia é direta: a ferramenta lê o Directory.Packages.props, escaneia todos os .csproj do repositório, e descobre quais pacotes estão declarados mas não são usados por ninguém. Sem mais delongas, o fluxo funciona assim:

Localiza o Directory.Packages.props — sobe a árvore de diretórios a partir da raiz que você indicou
Parseia os pacotes declarados — extrai todos os <PackageVersion> do arquivo
Escaneia os projetos — roda dotnet msbuild -getItem:PackageReference em cada .csproj pra saber quais pacotes são realmente usados
Calcula a diferença — declarados menos usados = lixo
Te deixa escolher — ou mostra um prompt interativo pra você selecionar o que remover, ou remove tudo automaticamente

O detalhe que me custou um bom tempo de pesquisa

Para descobrir quais pacotes cada projeto realmente usa, eu poderia simplesmente parsear o XML dos .csproj procurando PackageReference. Mas isso não pega tudo — pacotes podem vir de Directory.Build.props, de imports condicionais, de targets dinâmicos. A solução robusta foi usar o próprio MSBuild pra avaliar o projeto:

dotnet msbuild -getItem:PackageReference

Esse comando retorna um JSON estruturado com todos os PackageReference resolvidos do projeto, considerando todas as importações e condições. É o MSBuild te dizendo "olha, no final das contas, esses são os pacotes que esse projeto precisa". Muito mais confiável do que parsear XML na mão.

Instalação e uso, ou: duas linhas e já era

Instala como global tool:

dotnet tool install -g nuget-cpm-cleaner

Modo interativo — ele mostra os pacotes não usados e você escolhe o que remover:

nuget-cpm-cleaner --root C:/repos/minha-solution

Modo automático — remove tudo sem perguntar (ótimo pra CI ou quando você confia no resultado):

nuget-cpm-cleaner --root . --auto-remove

A saída é bem clara:

Found C:\repos\minha-solution\Directory.Packages.props
Declared packages: 42
Referenced packages across .csproj files: 38

Found 4 unused package(s):

? Select packages to remove: (Press <space> to toggle, <enter> to confirm)
> [ ] Deprecated.Package
  [ ] OldLibrary.Core
  [ ] SomeUnused.Tool
  [ ] UnusedAnalyzer

Done. Removed 2 package(s) from Directory.Packages.props:
  - Deprecated.Package
  - OldLibrary.Core

Simples assim. E de bônus: se você rodar isso antes de configurar o Dependabot (ou como step periódico no CI), nunca mais vai receber PR de atualização de pacote fantasma.

O que ficou de aprendizado

CPM não é opcional em solutions grandes. Se você tem mais de 3 projetos e ainda gerencia versões de pacote em cada .csproj, está acumulando dívida técnica todo dia. Centraliza isso.
Ferramentas boas resolvem dores pequenas que acumulam. Um <PackageVersion> órfão não quebra nada. Mas 30 deles deixam seu arquivo de configuração sujo, confuso, e fazem o Dependabot trabalhar à toa.
Se a ferramenta oficial não resolve, resolve você. A issue tá aberta, o time do NuGet explicou por que não vai tratar por padrão. Em vez de esperar, criei uma tool que resolve em dois comandos. Open source é isso.
Use o MSBuild como fonte de verdade, não o XML cru. Parsear .csproj direto é tentador, mas o resultado real de um build depende de condições, imports, e targets que só o MSBuild resolve. O -getItem é a forma correta.
Dotnet tools são subestimadas. Criar uma CLI distribuível via NuGet é absurdamente fácil no .NET. PackAsTool, ToolCommandName, e pronto — qualquer dev instala com uma linha.

Para saber mais

👉 Código fonte: https://github.com/AlbertoMonteiro/nuget-cpm-cleaner

Vou ficando por aqui. Se você já usa CPM e tem aquele Directory.Packages.props precisando de uma faxina, experimenta a tool e me conta o que achou. E se você ainda não usa CPM... bom, agora não tem mais desculpa!!!

Fique à vontade para comentar, vai ser muito legal trocar uma ideia!!!

Um grande abraço!

#dotnet #nuget #cpm #centralpackagemanagement #dotnettools #csharp #opensource #dependabot

Construindo um Terraform Provider em C# com Native AOT — e o que aprendi no caminho

Alberto Monteiro — Sat, 21 Mar 2026 16:36:55 +0000

Fala galera, tudo beleza?!

Recentemente precisei integrar o BeyondTrust Secret Safe ao Terraform e, ao pesquisar sobre como fazer isso, descobri que o ecossistema de providers é praticamente todo em Go. O problema é que o restante do projeto já estava em C#, e eu não queria trazer uma segunda linguagem só para isso. Então tomei uma decisão: vou fazer esse provider em C# mesmo, usando .NET 10 com Native AOT.

Spoiler: funcionou, e foi uma aventura e tanto!

Nesse artigo vou compartilhar as principais coisas que aprendi — inclusive as que me custaram horas de debug e que eu não encontrei documentadas em lugar nenhum.

O Terraform Plugin Protocol, ou: leia a spec com muito cuidado

O Terraform se comunica com os providers via gRPC, implementando o Terraform Plugin Protocol v5.2. Isso eu já sabia antes de começar. O que eu não sabia é que existe uma etapa de handshake que acontece antes de qualquer chamada gRPC.

Quando o Terraform inicializa o provider, ele espera receber uma linha específica no stdout:

1|5|tcp|{host}:{port}|grpc|{cert_base64}

Simples assim. O provider precisa escrever essa linha e só depois o Terraform vai tentar conectar via gRPC. Se qualquer outra coisa aparecer no stdout antes dessa linha, o Terraform simplesmente não consegue fazer o parse e o provider morre.

O detalhe que me custou horas de debug

O certificado TLS que vai no final dessa linha precisa estar em base64 sem padding — sem os = no final. Isso porque a biblioteca go-plugin da HashiCorp usa internamente base64.RawStdEncoding, que omite o padding.

Se você colocar o padding, o Terraform vai falhar com um erro de "certificate parse error" que não te diz absolutamente nada útil. Eu fiquei batendo cabeça nesse erro por horas até achar a causa!!!

var cert = Convert.ToBase64String(certificate.RawData)
    .Replace("\r", "")
    .Replace("\n", "")
    .TrimEnd('=');  // <- essa linha é a chave de tudo

var line = $"1|5|tcp|{address}|grpc|{cert}\n";
var bytes = Encoding.ASCII.GetBytes(line);

using var stdout = Console.OpenStandardOutput();
stdout.Write(bytes);
stdout.Flush();

Esse .TrimEnd('=') não está em nenhuma documentação oficial. É o tipo de coisa que você só descobre lendo o código fonte da lib do HashiCorp ou... sofrendo.

Native AOT: adeus reflexão, olá disciplina

Compilar com PublishAot=true e TrimMode=full muda bastante a forma como você escreve código. Basicamente, tudo que depende de reflexão em tempo de execução vai quebrar:

Type.GetType() — não vai funcionar
MethodInfo.Invoke() — não vai funcionar
Serialização JSON "mágica" — não vai funcionar

Para tudo isso, você precisa de source generators. Para JSON usei o JsonSourceGenerationContext do System.Text.Json, e para a injeção de dependência tudo tem que ser registrado explicitamente na inicialização. E aqui entra um terceiro serializer que merece atenção especial.

MessagePack: o protocolo binário do Terraform

O Terraform Plugin Protocol define um tipo chamado DynamicValue no protobuf, que pode chegar como JSON ou como MessagePack. Isso significa que o provider precisa saber desserializar os dois formatos. Para o MessagePack usei a lib MessagePack-CSharp, que é muito performática — mas que, por padrão, usa reflexão para descobrir como serializar cada tipo.

Adivinha: reflexão e AOT não combinam.

A solução é o [GeneratedMessagePackResolver], um source generator que gera todo o código de serialização em tempo de compilação. Você cria uma classe parcial vazia com o atributo e o generator cuida do resto!!!

[GeneratedMessagePackResolver]
partial class MessagePackResolverPlaceholder
{
}

E nos modelos, você anota com [MessagePackObject] e [Key] para mapear as propriedades:

[MessagePackObject]
public class ProviderConfiguration
{
    [Key("runas")]
    public required string RunAs { get; set; }

    [Key("key")]
    public required string Key { get; set; }

    [Key("baseUrl")]
    public required string BaseUrl { get; set; }

    [Key("pwd")]
    public string? Pwd { get; set; }
}

Com isso, o SmartSerializer consegue tratar os dois formatos de forma transparente — se o DynamicValue que chegou tem dados em msgpack, desserializa com MessagePack; se veio em JSON, usa o System.Text.Json. Nenhuma reflexão em runtime, zero problema com AOT:

public static T? Deserialize<T>(DynamicValue dynamicValue)
{
    return dynamicValue switch
    {
        { Msgpack.IsEmpty: false } => MessagePackSerializer.Deserialize<T>(dynamicValue.Msgpack.Memory),
        { Json.IsEmpty: false }    => JsonSerializer.Deserialize<T>(dynamicValue.Json.Span, Json.Default.Options)!,
        _                          => default
    };
}

Isso é muito elegante!!! O provider não precisa saber o que o Terraform vai enviar — ele simplesmente trata os dois casos.

No começo parece trabalhoso, mas a recompensa é muito boa:

Binário final de ~15 MB, completamente self-contained
Startup sub-segundo (sem JIT, sem carregamento de assembly)
Zero dependências de runtime no servidor

Para um provider que o Terraform spawna e mata várias vezes durante uma execução de terraform apply, isso faz uma diferença real!!!

Uma coisa legal que vale mencionar: em debug uso WebApplication.CreateBuilder() para ter mais logs e facilidade de debug, mas em release uso WebApplication.CreateSlimBuilder() que é compatível com AOT e gera um binário menor. Fica assim:

#if DEBUG
var builder = WebApplication.CreateBuilder(args);
#else
var builder = WebApplication.CreateSlimBuilder(args);
#endif

mTLS com certificado gerado na hora — e por que isso faz sentido

O Terraform usa mutual TLS (mTLS) para se comunicar com o provider. A primeira ideia que vem à cabeça é usar certificados de uma CA, mas nesse caso não precisa — e seria até um exagero.

O provider gera um certificado auto-assinado a cada inicialização, embute ele no handshake e descarta quando termina. Funciona porque:

O Terraform spawna o provider na mesma máquina — a relação de confiança é implícita
Não precisa de PKI, CA ou rotação de certificados
Cada instância tem identidade própria e efêmera

No servidor, configurei AllowAnyClientCertificate() porque o Terraform também apresenta um certificado cliente como parte do mTLS, e não precisamos validar esse certificado — ele é o único cliente possível. Isso simplifica muito o gerenciamento, sem abrir mão da criptografia!!!

Testes com Aspire + WireMock: vale cada byte de complexidade

Testar um provider Terraform é diferente de testar uma API comum. Você precisa testar o comportamento gRPC completo, a autenticação com o BeyondTrust, o fluxo de sessão — tudo integrado.

A solução que encontrei foi usar o Aspire (DistributedApplicationFactory) para orquestrar o ambiente de testes, subindo:

Um container WireMock mockando a API HTTP do BeyondTrust Secret Safe
O provider server rodando de verdade
Um test client que chama os métodos gRPC e valida as respostas

O WireMock usa arquivos JSON como mappings para definir os mocks — sem código C# misturado com infra de teste, sem acoplamento. É muito mais fácil de manter e de visualizar o que está sendo mockado.

Mas aprendi uma lição cara sobre o WireMock: um typo no formato do campo headers dentro do mapping fazia ele silenciosamente ignorar o mapeamento inteiro, resultando em um 404 que eu não conseguia entender de forma alguma. Fiquei um bom tempo depurando isso até descobrir que o problema era a estrutura do JSON do mapping.

Depois disso, passei a sempre validar os mappings contra o schema do WireMock antes de confiar neles. Parece bobo, mas salvou muito tempo depois!!!

O que ficou de aprendizado

Algumas coisas que ficaram gravadas depois de tudo isso:

Documente o não óbvio. O padding do base64 é o melhor exemplo: não está em documentação nenhuma, não dá nenhum erro claro, mas quebra tudo. Se você descobrir uma dessas, documenta na hora.

AOT desde o início. Tentar adaptar código que usa reflexão para AOT depois é bem mais doloroso do que já começar com as restrições em mente. Se sabe que vai usar AOT, já escreva pensando nisso — e mapeie quais libs precisam de source generators (JSON, MessagePack, DI).

Testes de integração valem o custo. A complexidade de subir WireMock + Aspire parece exagerada no começo, mas é exatamente esse tipo de teste que vai pegar bugs que testes unitários jamais encontrariam — bugs no serialização, no fluxo de autenticação, em comportamentos do gRPC.

Entenda os contratos do protocolo. O Terraform Plugin Protocol é estrito. Não dá para ir no feeling; você precisa ler o .proto, entender cada RPC e implementar exatamente o que está definido.

O código está aberto no GitHub. Se você trabalha com BeyondTrust Secret Safe, quer entender como implementar um Terraform provider fora do ecossistema Go, ou está curioso sobre Native AOT no .NET 10, dá uma olhada!

👉 github.com/AlbertoMonteiro/terraform-provider-beyondtrust-secretsafe

Se você já passou por algo parecido ou tem alguma dúvida, deixa nos comentários, vai ser muito legal trocar uma ideia!!!

Vou ficando por aqui, um grande abraço!

#Terraform #CSharp #DotNet #NativeAOT #DevOps #InfrastructureAsCode #BeyondTrust #gRPC #DotNet10