Union types no C# 15: substituindo o Result por tipos de domínio

O erro é apenas uma string

Quem consome o método não sabe quais falhas podem acontecer sem abrir a implementação. A assinatura Result<Order> Cancel() não comunica se o pedido pode já estar cancelado, se o prazo expirou ou se existe outra restrição.

Na prática, o tratamento acaba dependendo de comparações de texto ou de códigos mágicos. Assim, qualquer alteração na mensagem de erro pode quebrar silenciosamente um consumidor.

Estados inválidos são representáveis

Nada impede que o código acesse Value quando a operação falhou, ou Error quando ela teve sucesso. O compilador não oferece qualquer proteção contra esse tipo de engano.

O resultado é um código repleto de verificações como if (!result.IsSuccess). Essas verificações dependem da disciplina do desenvolvedor, e não de garantias da linguagem.

Novos erros passam despercebidos

Se amanhã surgir uma nova regra de negócio, com um novo motivo de falha, nenhum ponto do código recebe sinalização. Os consumidores continuam compilando, e o novo caso cai em algum tratamento genérico ou fica sem tratamento.

Esse é talvez o problema mais grave, porque o custo aparece apenas em produção.

Tipo soma versus tipo produto

Na teoria de tipos, um union recebe o nome de tipo soma, ou sum type. O valor é A ou B ou C, nunca mais de um ao mesmo tempo.

Por outro lado, uma classe ou record convencional é um tipo produto. Ela contém A e B e C simultaneamente, como propriedades que coexistem na mesma instância.

Linguagens como F#, Rust, Haskell e TypeScript já oferecem tipos soma há bastante tempo. No C#, a alternativa era simular esse comportamento com hierarquias de classes ou com bibliotecas de terceiros.

Declaração, conversão implícita e exaustividade

A declaração de um union é direta, porque basta listar os case types entre parênteses:

public record class Cat(string Name);
public record class Dog(string Name);

public union Pet(Cat, Dog);

Três características tornam os union types no C# relevantes para modelagem de domínio. A primeira é o conjunto fechado: um Pet só pode conter um Cat ou um Dog, e nenhum código externo acrescenta uma terceira alternativa.

A segunda é a conversão implícita. O compilador gera uma conversão de cada case type para o union, então Pet pet = new Dog("Rex"); compila sem new Pet(...).

A terceira é a exaustividade. Como o compilador conhece todos os casos, uma expressão switch que cobre cada um deles dispensa o braço _ =>.

Pet pet = new Dog("Rex");

var name = pet switch
{
    Dog d => d.Name,
    Cat c => c.Name,
};

Se algum caso ficar de fora, o compilador emite o aviso de switch não exaustivo. Essa é a propriedade que resolve o terceiro problema do Result<T>.

O que o compilador gera para union types no C#

Um union não é uma construção mágica do runtime. O compilador transforma a declaração em uma struct marcada com o atributo [Union], que implementa a interface IUnion do namespace System.Runtime.CompilerServices.

De forma simplificada, a declaração public union Pet(Cat, Dog); equivale ao código abaixo:

[Union]
public struct Pet : IUnion
{
    public Pet(Cat value) => Value = value;
    public Pet(Dog value) => Value = value;
    public object? Value { get; }
}

Existe um construtor público para cada case type e uma propriedade Value do tipo object?. Além disso, os case types não precisam compartilhar classe base ou interface, o que diferencia o union de uma hierarquia abstrata.

O pattern matching também atua diretamente sobre o conteúdo do union. Ao escrever pet is Dog, o compilador testa a propriedade Value, sem que você precise acessá-la manualmente.

Resultados como tipos de negócio

Em vez de strings, cada desfecho possível passa a ser um tipo próprio, que carrega apenas os dados relevantes para aquele cenário.

public sealed record OrderCanceled(Guid Id, DateTime CanceledAt);
public sealed record OrderAlreadyCanceled(Guid Id, DateTime CanceledAt);
public sealed record CancellationDeadlineExpired(Guid Id, TimeSpan Deadline);

public union CancellationResult(
    OrderCanceled,
    OrderAlreadyCanceled,
    CancellationDeadlineExpired);

Repare que o sucesso também é um caso nomeado. Não existe um Ok genérico, e sim um OrderCanceled, que fala a linguagem do negócio.

Essa abordagem também facilita a comunicação com especialistas de domínio. Afinal, os nomes dos tipos correspondem aos termos usados nas conversas sobre a regra.

O método de domínio

Agora, a assinatura do método documenta, por si só, todos os resultados possíveis.

public sealed class Order
{
    // Prazo máximo para cancelar o pedido
    private static readonly TimeSpan CancellationDeadline = TimeSpan.FromHours(24);

    public Order(Guid id, DateTime createdAt)
    {
        Id = id;
        CreatedAt = createdAt;
    }

    public Guid Id { get; private set; }
    public DateTime CreatedAt { get; private set; }
    public DateTime? CanceledAt { get; private set; }

    public CancellationResult Cancel(DateTime now)
    {
        if (CanceledAt is not null)
            return new OrderAlreadyCanceled(Id, CanceledAt.Value);

        if (now - CreatedAt > CancellationDeadline)
            return new CancellationDeadlineExpired(Id, CancellationDeadline);

        CanceledAt = now;
        return new OrderCanceled(Id, now);
    }
}

O método devolve diretamente o record de cada situação. Então, a conversão implícita gerada pelo compilador transforma o record em CancellationResult, sem fábricas como Result.Ok ou Result.Fail.

Outro ponto de design é o parâmetro now. Receber o instante atual como argumento mantém o domínio determinístico e facilita os testes, pois o método não depende de DateTime.UtcNow.

TreatWarningsAsErrors e WarningsAsErrors

Com a opção abaixo habilitada, o aviso vira erro e o build falha:

<PropertyGroup>
  <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
</PropertyGroup>

Na prática, o compilador passa a funcionar como um checklist de regras de negócio. Nenhum consumidor esquece o novo caso, porque o código simplesmente não compila.

Caso a equipe não queira transformar todos os avisos em erros, a propriedade WarningsAsErrors restringe o comportamento apenas ao CS8509:

<PropertyGroup>
  <WarningsAsErrors>$(WarningsAsErrors);CS8509</WarningsAsErrors>
</PropertyGroup>

Com isso, os union types no C# deixam de ser apenas uma conveniência sintática. Eles passam a proteger cada evolução da regra de negócio.

Ainda é preview

Na época desta publicação, o .NET 11 ainda estava em fase de preview. A própria documentação informa que parte da especificação ainda não chegou ao compilador e que a sintaxe pode mudar até a versão final.

Por isso, a recomendação é experimentar em protótipos e projetos internos, mantendo o código de produção no .NET 10 até o lançamento estável. O artigo sobre union types no .NET 11 acompanha a evolução do recurso.

Casos precisam ser tipos distintos

Um union de (string, string) não tem como diferenciar um caso do outro. Quando mais de um case type aceita o mesmo valor, a conversão fica ambígua e o compilador reporta erro.

Por isso, represente erros de domínio com records próprios. Essa restrição acaba reforçando uma boa prática de modelagem.

Value types sofrem boxing

O union gerado pelo compilador guarda o conteúdo em uma propriedade object?. Consequentemente, o runtime aloca no heap qualquer caso int, double ou struct.

Em código de domínio que usa union types no C#, esse custo raramente importa. Em caminhos críticos de performance, porém, a alternativa é implementar um union customizado com o padrão de acesso sem boxing, usando HasValue e métodos TryGetValue.

O valor default de um union

Como o union é uma struct, a expressão default(CancellationResult) produz uma instância cuja propriedade Value vale null. Nesse caso, um switch sem braço para null lança SwitchExpressionException em tempo de execução.

O compilador rastreia o estado de nulidade e emite aviso quando o valor pode ser nulo. Ainda assim, é prudente evitar campos e propriedades não inicializados do tipo union.

Sem igualdade nem desconstrução

Diferente de um record, o union não gera igualdade estrutural, clonagem ou desconstrução. Ele responde apenas à pergunta de qual caso está presente.

Entretanto, a igualdade e a desconstrução continuam disponíveis nos records que compõem o union, que é onde esses comportamentos fazem sentido.