Ferramentas de compatibilidade da API

  • Artigo

A compatibilidade multiplataforma se tornou um requisito principal para autores da biblioteca do .NET. No entanto, sem ferramentas para validar assemblies e pacotes, eles podem conter alterações de falha não intencionais. Como um autor de biblioteca, você precisa garantir que os assemblies de vários destinos sejam compatíveis. Por exemplo, para um pacote que tem vários destinos para .NET 6 e .NET Standard 2.0, você deve garantir que o código compilado no binário .NET Standard 2.0 possa ser executado no binário do .NET 6.

Você poderá pensar que uma alteração é segura e compatível se o consumo de origem dessa alteração continuar sendo compilado sem alterações. No entanto, as alterações ainda poderão causar problemas em tempo de execução se o consumidor não tiver sido recompilado. Por exemplo, adicionar um parâmetro opcional a um método ou alterar o valor de uma constante pode causar esses tipos de problemas de compatibilidade.

O SDK do .NET fornece várias maneiras de comparar versões criadas para estruturas de destino diferentes. Você também pode validar uma versão mais recente em relação a uma versão de linha de base para garantir que nenhuma alteração interruptiva tenha sido introduzida. Habilite as tarefas do MSBuild para validar seus assemblies em tempo de compilação ou em seus pacotes quando você empacotar. Ou use a ferramenta global Microsoft.DotNet.ApiCompat.Tool para validar fora do MSBuild.

Para obter mais informações sobre a validação do pacote, confira Validação do pacote. A validação do assembly deve ser usada quando o aplicativo não puder ser empacotado. Para obter mais informações sobre a validação do assembly, confira Validação do Assembly.

Observação

Para executar a validação do assembly como uma tarefa do MSBuild, você deve adicionar uma referência de pacote a Microsoft.DotNet.ApiCompat.Task. Da mesma forma, você também pode adicionar uma referência a esse pacote quando quiser testar recursos mais recentes que ainda não estão disponíveis no SDK do .NET. Por exemplo, você pode referenciar a versão 9.0.100-preview do pacote Microsoft.DotNet.ApiCompat.Task ao usar o SDK do .NET 8.

Modo estrito

Por padrão, a validação executa verificações de compatibilidade. No entanto, você também pode optar pelo modo estrito. No modo estrito, a validação realiza verificações de igualdade. Igualdade significa que nenhuma adição de API ou alterações de assembly, mesmo as compatíveis, foram feitas.

Os casos de uso para o modo estrito incluem o seguinte:

  • Manutenção, na qual as adições de API geralmente são proibidas.
  • Para acompanhar as alterações de API. A funcionalidade de compatibilidade da API registrará todas as diferenças de compatibilidade no arquivo de supressão se você definir ApiCompatGenerateSuppressionFile como true.

Para habilitar o modo estrito para a ferramenta de linha de comando, especifique a opção --strict-mode ou uma das opções --enable-strict*. Para habilitar o modo estrito para as tarefas do MSBuild, adicione uma ou mais das seguintes propriedades do MSBuild ao arquivo de projeto: