Ferramentas de compatibilidade de API
A compatibilidade entre plataformas tornou-se um requisito básico para os autores de bibliotecas .NET. No entanto, sem ferramentas para validar montagens e pacotes, eles podem conter alterações de quebra não intencionais. Como autor de uma biblioteca, você precisa garantir que os assemblies de vários destinos sejam compatíveis. Por exemplo, para um pacote com destinos múltiplos para .NET 6 e .NET Standard 2.0, você deve garantir que o código compilado em relação ao binário do .NET Standard 2.0 possa ser executado no binário do .NET 6.
Você pode pensar que uma alteração é segura e compatível se a fonte que consome essa alteração continuar a ser compilada sem alterações. No entanto, as alterações ainda podem causar problemas em tempo de execução se o consumidor não foi 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 diferentes estruturas de destino. 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 significativa tenha sido introduzida. Habilite as tarefas do MSBuild para validar seus assemblies em tempo de compilação ou 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 validação de pacote, consulte Validação de pacote. A validação de assembly deve ser usada quando seu aplicativo não pode ser empacotado. Para obter mais informações sobre validação de assembly, consulte Assembly validation.
Nota
Para executar a validação de 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 este pacote quando quiser testar recursos mais recentes que ainda não estão disponíveis no SDK do .NET. Por exemplo, você pode fazer referência à 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 executa verificações de igualdade . Igualdade significa que nenhuma adição de API ou alterações de montagem, mesmo as compatíveis, foram feitas.
Os casos de uso para o modo estrito incluem o seguinte:
- Manutenção, em que adições de API são geralmente proibidas.
- Para acompanhar as alterações da API. A funcionalidade de compatibilidade da API registra 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 --strict-mode
opção ou uma das --enable-strict*
opções. Para habilitar o modo estrito para as tarefas do MSBuild, adicione uma ou mais das seguintes propriedades do MSBuild ao seu arquivo de projeto: