Compartilhar via

Alterações da falha

É importante que uma biblioteca .NET encontre um equilíbrio entre estabilidade para usuários existentes e inovação para o futuro. Desenvolvedores de bibliotecas tendem a refatorar e reavaliar o código até que ele esteja perfeito, mas comprometer os usuários atuais pode ter consequências negativas, especialmente para bibliotecas de baixo nível.

Tipos de projeto e mudanças disruptivas

O modo como uma biblioteca é usada pela comunidade do .NET altera o efeito das alterações de falha sobre os desenvolvedores para o usuário final.

  • Bibliotecas de nível baixo e médio , como um serializador, analisador HTML, mapeador relacional de objeto de banco de dados ou estrutura da Web são as mais afetadas por alterações interruptivas.

    Os pacotes de bloco de construção são usados por desenvolvedores de usuário final para criar aplicativos e por outras bibliotecas como dependências do NuGet. Por exemplo, você está criando um aplicativo e está usando um cliente de software livre para chamar um serviço Web. Uma atualização da falha para uma dependência que o cliente usa não é algo que você pode consertar. É o cliente de software livre que precisa ser alterado e você não tem controle sobre ele. Você precisa encontrar versões compatíveis das bibliotecas ou enviar uma correção para a biblioteca de clientes e aguardar uma nova versão. A pior situação é se você quiser usar duas bibliotecas que dependem de versões mutuamente incompatíveis de uma terceira biblioteca.

  • Bibliotecas de alto nível, tais como um pacote de controles de interface do usuário, são menos sensíveis a alterações da falha.

    Bibliotecas de alto nível são referenciadas diretamente em um aplicativo de usuário final. Se ocorrerem alterações da falha, o desenvolvedor poderá optar por atualizar para a versão mais recente ou poderá modificar seu aplicativo para funcionar com a alteração da falha.

✔️ Pense em como sua biblioteca será usada. Que efeito as alterações disruptivas terão sobre os aplicativos e bibliotecas que o utilizam?

✔️ Minimize alterações significativas ao desenvolver uma biblioteca .NET de baixo nível.

✔️ CONSIDERE a publicação de uma reescrita importante de uma biblioteca como um novo pacote NuGet.

Tipos de alterações da falha

Alterações da falha se enquadram em categorias diferentes e não são igualmente impactantes.

Alteração da falha de origem

Uma alteração da falha de origem não afeta a execução do programa, mas causará erros de compilação na próxima vez que o aplicativo for recompilado. Por exemplo, uma nova sobrecarga pode criar uma ambiguidade em chamadas de método que eram inequívocas anteriormente ou um parâmetro renomeado interromperá os chamadores que usam parâmetros nomeados.

public class Task
{
    // Adding a type called Task could conflict with System.Threading.Tasks.Task at compilation
}

Já que uma fonte de alteração da falha só é prejudicial quando os desenvolvedores recompilam seus aplicativos, ela a alteração da falha com menos interrupções. Os desenvolvedores podem corrigir seu próprio código-fonte quebrado facilmente.

Alteração da falha de comportamento

As alterações de comportamento são o tipo mais comum de alteração disruptiva: praticamente qualquer alteração no comportamento pode resultar em um erro lógico para o consumidor. Alterações em sua biblioteca, como assinaturas de método, exceções geradas ou formatos de dados de entrada ou saída, podem afetar negativamente os consumidores da biblioteca. Até mesmo uma correção de bug pode se qualificar como uma alteração da falha se os usuários contavam com o comportamento anteriormente desfeito.

Adicionar recursos e melhorar comportamentos ruins é uma coisa boa, mas sem cuidado pode dificultar muito a atualização dos usuários existentes. Uma abordagem para ajudar os desenvolvedores a lidar com alterações que quebram o comportamento é escondê-las por trás das configurações. As configurações permitem que os desenvolvedores atualizem para a versão mais recente da sua biblioteca, optando simultaneamente por aceitar ou recusar alterações significativas. Essa estratégia permite que os desenvolvedores permaneçam atualizados, permitindo que o código consumido se adapte ao longo do tempo.

Por exemplo, ASP.NET Core MVC tem o conceito de uma versão de compatibilidade que modifica os recursos habilitados e desabilitados MvcOptions.

✔️ CONSIDERE deixar novos recursos desativados por padrão, se eles afetarem os usuários existentes e permitir que os desenvolvedores optem pelo recurso com uma configuração.

Para obter mais informações sobre alterações de comportamento disruptivas em APIs do .NET, consulte compatibilidade de alterações comportamentais do .NET.

Alteração da falha binária

Uma alteração da falha binária acontece quando você altera a API pública de sua biblioteca, portanto, os assemblies compilados para versões mais antigas da sua biblioteca não são mais capazes de chamar a API. Por exemplo, alterar a assinatura de um método adicionando um novo parâmetro fará com que assemblies compilados com a versão mais antiga da biblioteca lancem um MissingMethodException.

Um alteração da falha binária também pode interromper um assembly inteiro. Renomear um assembly com AssemblyName alterará a identidade do assembly, o que também ocorrerá ao adicionar, remover ou alterar a chave de nomenclatura forte do assembly. Uma alteração na identidade de uma assemblagem quebrará todo o código compilado que a usa.

❌ NÃO altere um nome de assembly.

❌ NÃO adicione, remova nem altere a chave de nome forte.

✔️ CONSIDERE o uso de classes base abstratas em vez de interfaces.

Adicionar qualquer coisa a uma interface fará com que os tipos existentes que a implementem falhem. Uma classe base abstrata permite adicionar uma implementação virtual padrão.

✔️ CONSIDERE colocar o ObsoleteAttribute nos tipos e membros que você pretende remover. O atributo deve ter instruções para atualizar o código para não usar mais a API obsoleta.

O código que chama tipos e métodos com o ObsoleteAttribute gerará um aviso de build com a mensagem fornecida ao atributo. Os avisos dão às pessoas que usam a API obsoleta tempo para migrar, de modo que, quando a API for removida, a maioria já não esteja mais a utilizando.

public class Document
{
    [Obsolete("LoadDocument(string) is obsolete. Use LoadDocument(Uri) instead.")]
    public static Document LoadDocument(string uri)
    {
        return LoadDocument(new Uri(uri));
    }

    public static Document LoadDocument(Uri uri)
    {
        // Load the document
    }
}

✔️ CONSIDERE a possibilidade de manter os tipos e métodos com o ObsoleteAttribute indefinidamente em bibliotecas de nível médio e baixo.

A remoção de APIs é uma alteração que quebra a compatibilidade binária. Considere manter tipos e métodos obsoletos se o custo de mantê-los for baixo e não adicionar muita dívida técnica à sua biblioteca. Não remover tipos e métodos pode ajudar a evitar os piores cenários mencionados acima.

Para obter mais informações sobre quais alterações da API do .NET interrompem a compatibilidade binária, consulte a compatibilidade do contrato público do .NET.

Consulte também

Anterior

  • Last updated on