Extension Methods em C#: criação, segmentação, testes e reuso

O que são extension methods

Extension methods permitem adicionar métodos a um tipo existente sem herança, sem modificar o código-fonte original e sem criar uma classe derivada. Em outras palavras, você estende o tipo por fora.

Em C#, você declara esses métodos em classes estáticas, com o primeiro parâmetro precedido pela palavra-chave this. Esse modificador indica qual tipo recebe a extensão.

public static class StringExtension
{
    public static string NormalizeTitle(this string value)
        => // implementação
}

A partir dessa definição, qualquer variável do tipo string pode invocar NormalizeTitle() como se fosse um método nativo:

var normalized = "  Clean   Architecture  ".NormalizeTitle();
// resultado: "Clean Architecture"

Na prática, o compilador transforma essa chamada em StringExtension.NormalizeTitle(value) em tempo de compilação. Por isso, não há custo adicional em runtime, já que extension methods são syntax sugar puro.

A documentação oficial de extension members reforça um detalhe importante. Para usar o método, basta adicionar uma diretiva using com o namespace em que a classe estática foi declarada.

Um bom exemplo do próprio .NET é o LINQ. Os operadores Where, Select e OrderBy também são extension methods definidos sobre IEnumerable<T>, e por isso qualquer coleção ganha esses recursos automaticamente.

Se você quer revisar a sintaxe básica antes de seguir, o artigo Extension methods no C# traz uma introdução direta ao recurso.

Por que usar extension methods

A alternativa mais comum aos extension methods é a criação de classes utilitárias estáticas. Nesse modelo, os métodos recebem o valor como parâmetro:

// Sem extension method
var normalized = StringUtils.NormalizeTitle(value);

// Com extension method
var normalized = value.NormalizeTitle();

A segunda forma é superior por três razões. A primeira é a descobribilidade: ao digitar value., o IntelliSense exibe todos os métodos disponíveis para aquele tipo, incluindo os de extensão.

Assim, o desenvolvedor não precisa saber que StringUtils existe. Ele encontra o método no momento em que precisa dele.

A segunda razão é a legibilidade. Uma chamada em cadeia como value.NormalizeTitle().ToLowerInvariant().Slugify() é mais fluente do que chamadas aninhadas de métodos estáticos.

A terceira é a coesão. O método vive conceitualmente próximo do tipo que estende, e com isso a organização do código fica mais intuitiva.

Ainda assim, as diretrizes de design do .NET pedem cautela. Elas recomendam evitar extension methods frívolos, principalmente em tipos que você não controla, porque o excesso polui a API do tipo estendido.

Segmentação por responsabilidade

O erro mais comum ao organizar extension methods é agrupá-los em uma única classe genérica chamada StringUtils, Helpers ou Extensions. Essa abordagem cria uma classe sem coesão, que cresce indefinidamente e se torna impossível de manter.

A alternativa correta é segmentar por responsabilidade, ou seja, cada classe de extensão tem um propósito único e bem definido. Em um projeto que lida com normalização de texto, slugs, domínios e URLs, a separação natural fica assim:

StringExtension.cs     # normalização de espaços e caracteres
SlugExtension.cs       # geração de slugs a partir de texto
DomainExtension.cs     # extração e manipulação de domínios
UrlExtension.cs        # extração de URLs a partir de texto

Dessa forma, cada arquivo tem uma única responsabilidade, um conjunto coeso de métodos e uma superfície de testes bem definida.

Na prática, quando os métodos de uma categoria são poucos, é aceitável agrupá-los em uma única classe StringExtension. Nesse caso, use regiões ou comentários que deixem clara a separação conceitual:

public static class StringExtension
{
    #region Normalization

    public static string NormalizeTitle(this string value) => ...

    #endregion

    #region Slug

    public static string Slugify(this string value) => ...

    #endregion

    #region Domain

    public static string? ExtractDomain(this string value) => ...

    #endregion

    #region URL

    public static string? ExtractUrl(this string value) => ...

    #endregion
}

O tamanho e a complexidade de cada grupo guiam a decisão entre um arquivo por responsabilidade ou regiões dentro de um único arquivo. Quando um grupo passa de três ou quatro métodos, a separação em arquivo próprio se torna a escolha mais adequada.

Relação com expressões regulares

Extension methods são a camada natural entre as expressões regulares e os Value Objects. Eles recebem uma string, aplicam uma ou mais transformações com apoio de expressões regulares e retornam o resultado.

Esse papel intermediário é importante porque mantém cada camada com uma única responsabilidade:

• A classe RegularExpression define os padrões, sem saber como alguém vai usá-los.
• A classe StringExtension aplica os padrões, sem saber quem vai consumir o resultado.
• Os Value Objects consomem os métodos de extensão, sem saber quais padrões estão por trás.

public static class StringExtension
{
    private static readonly Regex TabsAndLineBreaks = RegularExpression.TabsAndLineBreaksRegex();
    private static readonly Regex MultipleSpaces = RegularExpression.MultipleSpacesRegex();

    public static string NormalizeTitle(this string value)
    {
        var result = value.Trim();
        result = TabsAndLineBreaks.Replace(result, string.Empty);
        result = MultipleSpaces.Replace(result, " ");
        return result;
    }
}

Armazenar as instâncias das expressões regulares como campos estáticos privados dentro da classe de extensão é uma prática recomendada.

Embora o atributo [GeneratedRegex] já elimine o custo de inicialização, a referência estática evita chamadas repetidas ao método gerado. Além disso, ela deixa explícito de quais padrões o método depende.

Segundo a documentação dos source generators de expressões regulares, o gerador surgiu no .NET 7. Ele cria o código do Regex em tempo de compilação e também mantém uma instância singleton em cache.

Para aprofundar a organização da classe RegularExpression, vale ler o artigo sobre como criar, organizar e reutilizar expressões regulares em C#.

Nomenclatura de extension methods sem conflitos

Extension methods de string competem diretamente com os métodos nativos da classe string no IntelliSense. Por isso, uma nomenclatura imprecisa pode causar conflitos sérios.

A regra do compilador é clara: um membro de instância sempre tem prioridade sobre um extension method com a mesma assinatura. Em outras palavras, se o tipo já tem o método, a sua extensão nunca será chamada.

O exemplo mais concreto é o método string.Normalize(), que já existe no .NET e realiza normalização Unicode (NFC, NFD e outras formas).

Ao criar um método de extensão com o mesmo nome para normalizar espaços, o compilador pode invocar silenciosamente o método nativo em vez do customizado:

// Perigoso: conflita com string.Normalize() do .NET
public static string Normalize(this string value) => ...

// Correto: nome específico que comunica a intenção
public static string NormalizeTitle(this string value) => ...

A regra geral, então, é escolher um nome específico o suficiente para não conflitar com nenhum método nativo atual ou futuro do tipo estendido.

Prefixos que indicam o domínio (NormalizeTitle, NormalizeWhiteSpace) funcionam bem. Da mesma forma, nomes que indicam a ação (ExtractDomain, ExtractUrl, Slugify) são estratégias eficazes.

Composição de extension methods em cadeia

Um dos benefícios mais poderosos dos extension methods é a capacidade de compô-los em cadeia. Com isso, você cria pipelines de transformação legíveis e expressivos.

O método Slugify ilustra bem essa composição:

public static string Slugify(this string value)
{
    var lower = value.NormalizeTitle().ToLowerInvariant();
    var noSpecial = RegularExpression.NonSlugCharactersRegex().Replace(lower, string.Empty);
    return RegularExpression.WhiteSpaceRegex().Replace(noSpecial, "-").Trim('-');
}

Nesse método, NormalizeTitle() roda antes de qualquer outra transformação. Assim, tabulações, quebras de linha e espaços múltiplos desaparecem antes das regras específicas do slug.

A ordem das operações é determinante:

1. NormalizeTitle(): remove tabulações e quebras de linha e colapsa espaços múltiplos.
2. ToLowerInvariant(): converte para minúsculas, de forma compatível com a RFC de URLs.
3. NonSlugCharactersRegex: remove caracteres especiais como ., , e !.
4. WhiteSpaceRegex: substitui espaços por hífens.
5. Trim('-'): remove hífens nas bordas, originados de caracteres especiais no início ou no fim.

A inversão de qualquer uma dessas etapas produziria resultados incorretos. Portanto, documentar essa ordem e a razão de cada etapa é tão importante quanto a implementação em si.

Tratamento de valores nulos e vazios

Métodos de extensão em string devem sempre considerar entradas nulas ou vazias. A decisão sobre como tratar esses casos depende do contrato do método.

Vale lembrar um detalhe da especificação do C#: chamar um extension method sobre uma referência nula não lança exceção na chamada. O valor null chega ao método como chega a qualquer método estático, e cabe à implementação decidir o que fazer.

Para métodos de normalização, que rodam antes da validação, a abordagem mais segura é devolver o valor sem modificação quando ele é nulo ou vazio. Dessa forma, o chamador fica responsável por tratar esses casos:

public static string NormalizeTitle(this string value)
{
    if (string.IsNullOrEmpty(value))
        return value;

    var result = value.Trim();
    result = TabsAndLineBreaks.Replace(result, string.Empty);
    result = MultipleSpaces.Replace(result, " ");
    return result;
}

Já os métodos de extração podem legitimamente não encontrar um resultado. Nesse caso, o retorno null é semanticamente correto e aparece no tipo de retorno:

public static string? ExtractDomain(this string value)
{
    var match = RegularExpression.DomainExtractorRegex().Match(value.ToLowerInvariant());
    return match.Success ? match.Groups[1].Value : null;
}

public static string? ExtractUrl(this string value)
{
    var match = RegularExpression.UrlRegex().Match(value.ToLowerInvariant());
    return match.Success
        ? match.Value.TrimEnd('.', ',', ')', ']', '\'', '"')
        : null;
}

O tipo string? torna explícita a possibilidade de ausência de resultado. Com isso, o chamador precisa lidar com esse caso de forma consciente.

Testabilidade de extension methods

A razão mais importante para isolar comportamento em extension methods é a testabilidade. Um método de extensão bem definido pode ser testado sem depender dos Value Objects, das expressões regulares ou de qualquer outra camada.

Isso produz testes precisos, rápidos e com mensagens de falha claras. Quando um teste de NormalizeTitle falha, o desenvolvedor sabe exatamente onde está o problema, sem depurar um Value Object inteiro.

Se você está começando com testes, o artigo Fundamentos dos testes de unidade explica a base antes de entrarmos nos exemplos com NUnit.

[TestFixture]
public class StringExtensionTests
{
    #region NormalizeTitle

    [TestFixture]
    public class NormalizeTitleTests
    {
        [Test(Description = "Should remove leading and trailing spaces from the value")]
        [TestCase("  hello")]
        [TestCase("hello  ")]
        [TestCase("  hello  ")]
        public void NormalizeTitle_ShouldTrimLeadingAndTrailingSpaces(string value)
            => Assert.That(value.NormalizeTitle(), Is.EqualTo("hello"));

        [Test(Description = "Should collapse multiple consecutive spaces into a single space")]
        [TestCase("hello  world")]
        [TestCase("hello   world")]
        [TestCase("hello    world")]
        public void NormalizeTitle_ShouldCollapseMultipleSpaces(string value)
            => Assert.That(value.NormalizeTitle(), Is.EqualTo("hello world"));

        [Test(Description = "Should remove tab characters from the value")]
        [TestCase("hello\tworld")]
        [TestCase("hello\t\tworld")]
        public void NormalizeTitle_ShouldRemoveTabs(string value)
            => Assert.That(value.NormalizeTitle(), Is.EqualTo("helloworld"));

        [Test(Description = "Should remove line break characters from the value")]
        [TestCase("hello\nworld")]
        [TestCase("hello\r\nworld")]
        public void NormalizeTitle_ShouldRemoveLineBreaks(string value)
            => Assert.That(value.NormalizeTitle(), Is.EqualTo("helloworld"));

        [Test(Description = "Should return empty string when value is empty")]
        public void NormalizeTitle_ShouldReturnEmpty_WhenValueIsEmpty()
            => Assert.That(string.Empty.NormalizeTitle(), Is.EqualTo(string.Empty));
    }

    #endregion

    #region Slugify

    [TestFixture]
    public class SlugifyTests
    {
        [Test(Description = "Should create a slug from a plain text")]
        public void Slugify_ShouldCreateSlug_FromPlainText()
            => Assert.That("Clean Architecture".Slugify(), Is.EqualTo("clean-architecture"));

        [Test(Description = "Should remove special characters")]
        public void Slugify_ShouldCreateSlug_RemovingSpecialCharacters()
            => Assert.That("Clean Architecture in .NET".Slugify(), Is.EqualTo("clean-architecture-in-net"));

        [Test(Description = "Should not have leading or trailing hyphens")]
        public void Slugify_ShouldNotHave_LeadingOrTrailingHyphens()
            => Assert.That("...Clean Architecture...".Slugify(), Is.EqualTo("clean-architecture"));

        [Test(Description = "Should return empty string when value has only special characters")]
        public void Slugify_ShouldReturnEmpty_WhenValueHasOnlySpecialCharacters()
            => Assert.That("... !!!".Slugify(), Is.EqualTo(string.Empty));
    }

    #endregion

    #region ExtractDomain

    [TestFixture]
    public class ExtractDomainTests
    {
        // o método converte a entrada para minúsculas antes de extrair
        [Test(Description = "Should extract domain from https URL")]
        [TestCase("https://Project.com/blog", "project.com")]
        [TestCase("https://www.microsoft.com", "microsoft.com")]
        public void ExtractDomain_ShouldExtract_FromHttpsUrl(string input, string expected)
            => Assert.That(input.ExtractDomain(), Is.EqualTo(expected));

        [Test(Description = "Should extract domain from uppercase URL")]
        [TestCase("HTTPS://Project.COM", "project.com")]
        public void ExtractDomain_ShouldExtract_FromUppercaseUrl(string input, string expected)
            => Assert.That(input.ExtractDomain(), Is.EqualTo(expected));

        [Test(Description = "Should return null when value has no valid domain")]
        public void ExtractDomain_ShouldReturnNull_WhenValueHasNoValidDomain()
            => Assert.That("hello".ExtractDomain(), Is.Null);
    }

    #endregion

    #region ExtractUrl

    [TestFixture]
    public class ExtractUrlTests
    {
        [Test(Description = "Should extract URL from surrounding text")]
        [TestCase("visit https://Project.com today", "https://project.com")]
        [TestCase("check https://Project.com/blog now", "https://project.com/blog")]
        public void ExtractUrl_ShouldExtract_UrlFromText(string input, string expected)
            => Assert.That(input.ExtractUrl(), Is.EqualTo(expected));

        [Test(Description = "Should trim trailing punctuation from extracted URL")]
        public void ExtractUrl_ShouldTrimTrailingPunctuation()
            => Assert.That("visit https://Project.com.".ExtractUrl(), Is.EqualTo("https://project.com"));

        [Test(Description = "Should return null when value has no URL")]
        public void ExtractUrl_ShouldReturnNull_WhenValueHasNoUrl()
            => Assert.That("hello world".ExtractUrl(), Is.Null);
    }

    #endregion
}

Idempotência

Um método de normalização bem projetado deve ser idempotente. Ou seja, aplicá-lo uma segunda vez sobre um resultado já normalizado produz o mesmo resultado.

var first = "  Clean   Architecture  ".NormalizeTitle();
var second = first.NormalizeTitle();

Assert.That(first, Is.EqualTo(second)); // deve passar

Esse teste simples detecta implementações que introduzem transformações destrutivas ou que não convergem para um estado estável. Para Slugify, a idempotência também é esperada:

var slug = "Clean Architecture in .NET".Slugify();
Assert.That(slug.Slugify(), Is.EqualTo(slug)); // deve passar

Na prática, a idempotência protege contra bugs sutis. Um Value Object reconstruído a partir de um valor já persistido, por exemplo, não pode mudar de forma ao passar de novo pelos mesmos extension methods.

Integração com Value Objects

Os Value Objects consomem os métodos de extensão diretamente e delegam a eles toda a normalização e transformação. Com isso, o código do Value Object fica focado apenas nas regras de negócio:

public sealed record Title
{
    private const int MinLength = 3;
    private const int MaxLength = 160;

    public string Value { get; }

    private Title(string value) => Value = value;

    public static Title Create(string? value)
    {
        if (string.IsNullOrWhiteSpace(value))
            throw new NullOrEmptyException(nameof(value));

        var normalized = value.NormalizeTitle(); // delega para o extension method

        return normalized.Length switch
        {
            < MinLength or > MaxLength => throw new InvalidLengthException(MinLength, MaxLength),
            _ => new Title(normalized)
        };
    }
}

public sealed record Slug
{
    private const int MinLength = 3;
    private const int MaxLength = 160;

    public string Value { get; }

    private Slug(string value) => Value = value;

    public static Slug Create(string? value)
    {
        if (string.IsNullOrWhiteSpace(value))
            throw new NullOrEmptyException(nameof(value));

        var slug = value.Slugify(); // delega para o extension method

        return slug.Length switch
        {
            < MinLength or > MaxLength => throw new InvalidLengthException(MinLength, MaxLength),
            _ => new Slug(slug)
        };
    }
}

Os limites MinLength e MaxLength acima são apenas ilustrativos. Defina os valores conforme as regras do seu domínio.

Essa separação tem uma consequência direta nos testes. Os testes de Title não precisam verificar de novo se espaços múltiplos colapsam ou se tabulações somem, porque NormalizeTitleTests já cobre isso.

Assim, os testes de Title assumem que NormalizeTitle funciona e focam nas regras exclusivas do Value Object: comprimento mínimo, comprimento máximo e nulidade.

Para ver como projetar esses tipos em detalhes, confira o artigo sobre como criar bons Value Objects em C#.

Organização de extension methods no projeto

A localização dos arquivos influencia diretamente a descobribilidade e o reuso dos extension methods. Por isso, recomendamos esta estrutura:

Project.Core/
  Extensions/
    StringExtension.cs
  RegularExpressions/
    RegularExpression.cs
  ValueObjects/
    Title.cs
    Slug.cs
    Name.cs
    Money.cs
    Domain.cs
    InvitationCode.cs
    Tracker.cs

A pasta Extensions no projeto Core deixa os métodos de extensão disponíveis para todos os projetos que referenciam o Core, sem duplicação. Além disso, o namespace deve refletir a estrutura de pastas:

namespace Project.Core.Extensions;

public static class StringExtension { ... }

Um namespace próprio também traz controle. Como os extension methods entram em escopo por namespace, quem consome a biblioteca decide quando importá-los com using Project.Core.Extensions;.

Nos projetos de teste, a estrutura espelha a de produção:

Project.Core.Test/
  Extensions/
    StringExtensionTests.cs
  RegularExpressions/
    RegularExpressionTests.cs
  ValueObjects/
    TitleTests.cs
    SlugTests.cs

Desse modo, qualquer pessoa do time encontra o teste de um método olhando apenas para o caminho do arquivo de produção.

Extension methods e o C# 14

Todos os exemplos deste artigo usam a sintaxe clássica, com this no primeiro parâmetro. Essa sintaxe continua válida e é a forma mais difundida de escrever extension methods.

O C# 14, no entanto, introduziu os blocos extension, que agrupam membros de extensão para um mesmo receptor e permitem até propriedades de extensão. Os princípios apresentados aqui (coesão, nomes precisos, nulos explícitos e testes isolados) valem igualmente para a nova sintaxe.

Se quiser conhecer o novo modelo, leia o artigo sobre C# 14 e o novo modelo de extension members.

Considerações finais

Extension methods, quando projetados com critério, tornam-se uma das camadas mais valiosas de uma aplicação. Eles eliminam duplicação, aumentam a legibilidade e criam uma superfície de testes clara.

Além disso, servem de base para Value Objects expressivos e seguros.

Os princípios deste artigo são segmentação por responsabilidade, nomenclatura precisa, composição ordenada, tratamento explícito de nulos, idempotência e cobertura de testes. Juntos, eles transformam extension methods de utilitários convenientes em contratos testados e confiáveis.

Por fim, a relação entre extension methods, expressões regulares centralizadas e Value Objects cria uma arquitetura em camadas. Nela, cada artefato tem um propósito único, pode ser testado de forma isolada e pode ser reutilizado em qualquer contexto com as mesmas necessidades.

É essa combinação que transforma código funcional em código verdadeiramente sustentável.

FAQ

Extension methods têm custo de performance?

Não. O compilador converte a chamada em uma invocação de método estático, então não existe custo adicional em runtime.

Um extension method pode substituir um método que já existe no tipo?

Não. Membros de instância sempre têm prioridade, e uma extensão com a mesma assinatura nunca será chamada.

Devo criar uma classe Helpers com todos os métodos de extensão?

Não é recomendado. Segmente por responsabilidade, com classes coesas como SlugExtension ou UrlExtension, para facilitar manutenção e testes.

O que acontece se eu chamar um extension method em uma variável nula?

A chamada não lança exceção por si só. O valor nulo chega ao método, e a implementação decide como tratá-lo.

Preciso testar a normalização de novo nos testes do Value Object?

Não. Se os testes do extension method já cobrem a normalização, os testes do Value Object focam nas regras de negócio exclusivas dele.