960e4d723c
* ApiCompat infra changes * Convert baseline to suppression files * ApiCompat.proj * update suppressions * sorted suppressions * rebase and update suppressions * enable attribute and param rules * Enable optional rules * WebAssemblyThreading proj * CompatSuppression for XmlREaderWriter * Enable optional rules correctly... * ThreadPool UnsupportedOSPlatformAttribute * VBCore CP0017 * Migrate all CoreLibs over * Update ApiCompat.proj * Add ApiCompat.proj baselines * Update ApiCompat.proj * Clean-up suppression files with nint/IntPtr fix * Clean-up CoreLib suppression * Update suppression files with latest apicompat fix * Update suppression files * update suppressions * Update suppression files * Clean-up obsolete suppression files * Update suppression files * update suppressions * huge reduction in suppression file size * update suppressions * more suppressions removed * update suppressions * Update dependencies and clean-up * Add suppression files for CoreLib and fix path * Update CoreLib coreclr suppression file * Update coreclr suppression files * Suppression file fixes and Linux path fixes * Update coreclr suppression again) * Fix suppression file path calculation * Fix previous mistake * Diagnostics.Tracing suppression file * Threading suppression file fix * use global suppression for CryptoSignedXmlRecursionException * Add Specification.Tests suppression * Disable NoTargets ref copying * Fix for coreclr build * Avoid duplicate project evals Co-authored-by: smasher164 <akhilindurti@microsoft.com> Co-authored-by: Akhil Indurti <aindurti@gmail.com>
2.5 KiB
This document provides the steps you need to take to update the reference assembly when adding new public APIs to an implementation assembly (post API Review).
For most assemblies within libraries
- Implement the API in the source assembly and build it. Note that when adding new public types, this might fail with a
TypeMustExisterror. The deadlock can be worked around by disabling ApiCompat's assembly validation:dotnet build /p:ApiCompatValidateAssemblies=false. - Run the following command (from the src directory)
dotnet msbuild /t:GenerateReferenceAssemblySourceto update the reference assembly**. - Navigate to the ref directory and build the reference assembly.
- Add, build, and run tests.
** Note: If you already added the new API to the reference source, re-generating it (after building the source assembly) will update it to be fully qualified and placed in the correct order. This can be done by running the GenerateReferenceAssemblySource command from the ref directory.
For System.Runtime
These steps can also be applied to some unique assemblies which depend on changes in System.Private.Corelib. (partial facades like System.Memory, for example).
- Run
dotnet build --no-incremental /t:GenerateReferenceAssemblySourcefrom the System.Runtime/src directory. - Filter out all unrelated changes and extract the changes you care about (ignore certain attributes being removed). Generally, this step is not required for other reference assemblies.
For Full Facade Assemblies implementation assemblies
For implementation assemblies that are "full facades" over another assembly but define types in the reference assembly (ex. System.Runtime.Serialization.Json or System.Xml.XDocument), use the following command to generate the reference source code instead:
dotnet msbuild /t:GenerateReferenceAssemblySource /p:GenAPIFollowTypeForwards=true
For .NETFramework Facade Assemblies
Some assemblies define types in .NETStandard and .NETCore but require facades on .NETFramework to forward types to their existing location in .NETFramework. In these cases we need to add type forwards manually to the .NETFramework build of the reference assembly. TypeForwards must be added for every type in the compatible .NETStandard reference assembly that exists in the .NETFramework, types which are defined in the .NETFramework reference should be factored into a shared source file.