Validación de ensamblado

De forma similar a validación de paquetes, las herramientas de validación de ensamblados le permiten, como desarrollador de biblioteca, validar que los ensamblados son coherentes y bien formados. Use la validación de ensamblados en lugar de la validación de paquetes cuando la aplicación no se pueda empaquetar.

La validación de ensamblado proporciona las siguientes comprobaciones:

• Valida que no haya cambios importantes en las versiones.
• Validar que el ensamblado tiene el mismo conjunto de API públicas para todas las implementaciones específicas del entorno de ejecución.
• Captura cualquier marcador de aplicabilidad.

Puede ejecutar la validación de ensamblados como una tarea de MSBuild o mediante la herramienta global Microsoft.DotNet.ApiCompat.Tool.

Habilitación de la tarea de MSBuild

Para habilitar la validación de ensamblados en el proyecto de .NET, establezca la propiedad ApiCompatValidateAssemblies en true y especifique la ruta de acceso al ensamblado de contrato (línea base). También debe agregar una referencia de paquete a Microsoft.DotNet.ApiCompat.Task. (Los targets archivos de ese paquete no forman parte del SDK de .NET.)

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFrameworks>net8.0</TargetFrameworks>
    <ApiCompatValidateAssemblies>true</ApiCompatValidateAssemblies>
    <ApiCompatContractAssembly>[Path to contract assembly]</ApiCompatContractAssembly>
    <IsPackable>false</IsPackable>
  </PropertyGroup>

  <ItemGroup Condition="'$(ApiCompatValidateAssemblies)' == 'true'">
    <PackageReference Include="Microsoft.DotNet.ApiCompat.Task" Version="8.0.100" PrivateAssets="all" IsImplicitlyDefined="true" />
  </ItemGroup>

</Project>

La validación de ensamblados se ejecuta en la compilación externa para proyectos de varios destinos (después del DispatchToInnerBuilds destino) o en la compilación interna para un proyecto de destino único (como parte del PrepareForRun destino). También es totalmente incremental, lo que significa que la comparación solo se desencadena si las entradas o salidas han cambiado.

Ejemplo

1. Cree y compile una biblioteca de clases de C# denominada "ValidateMe" que contenga la siguiente interfaz simple:

   namespace ValidateMe;
   
   public interface IAnimal
   {
       string Name { get; }
       //string Sound { get; }
   }
   

2. Cambie el nombre del ensamblado de salida a "ValidateMeV1.dll".

3. Agregue la propiedad Sound a la interfaz quitando la marca de comentario de esa línea de código.

4. Agregue las propiedades ApiCompatValidateAssemblies y ApiCompatContractAssembly, y la referencia del paquete "Microsoft.DotNet.ApiCompat.Task" al archivo del proyecto. Incremente también la versión del ensamblado a "2.0.0".

   <PropertyGroup>
     <OutputType>Library</OutputType>
     <TargetFrameworks>net8.0</TargetFrameworks>
     <ApiCompatValidateAssemblies>true</ApiCompatValidateAssemblies>
     <ApiCompatContractAssembly>$(OutDir)bin\Release\net8.0\ValidateMeV1.dll</ApiCompatContractAssembly>
     <IsPackable>false</IsPackable>
     <Version>2.0.0</Version>
   </PropertyGroup>
   
   <ItemGroup Condition="'$(ApiCompatValidateAssemblies)' == 'true'">
      <PackageReference Include="Microsoft.DotNet.ApiCompat.Task" Version="8.0.100" PrivateAssets="all" IsImplicitlyDefined="true" />
   </ItemGroup>
   

5. Recompile la biblioteca de clases.

   Se produce un error en la compilación con los errores siguientes:

   C:\Users\me\.nuget\packages\microsoft.dotnet.apicompat.task\8.0.100\build\Microsoft.DotNet.ApiCompat.ValidateAssemblies.Common.targets(16,5): error : API compatibility errors between 'bin\Release\net8.0\ValidateMeV1.dll' (left) and 'C:\Users\me\source\repos\ValidateMe\bin\Release\net8.0\ValidateMe.dll' (right):
   1>C:\Users\me\.nuget\packages\microsoft.dotnet.apicompat.task\8.0.100\build\Microsoft.DotNet.ApiCompat.ValidateAssemblies.Common.targets(16,5): error CP0006: Cannot add interface member 'string ValidateMe.IAnimal.Sound' to C:\Users\me\source\repos\ValidateMe\bin\Release\net8.0\ValidateMe.dll because it does not exist on bin\Release\net8.0\ValidateMeV1.dll
   1>C:\Users\me\.nuget\packages\microsoft.dotnet.apicompat.task\8.0.100\build\Microsoft.DotNet.ApiCompat.ValidateAssemblies.Common.targets(16,5): error : API breaking changes found. If those are intentional, the APICompat suppression file can be updated by rebuilding with '/p:ApiCompatGenerateSuppressionFile=true'
   

Suprimir advertencias de compatibilidad

Para obtener información sobre cómo suprimir advertencias de compatibilidad, consulte Cómo suprimir.