Skip to content

Enable APICompat in WPF Builds #880

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 40 commits into from
Jun 11, 2019
Merged

Enable APICompat in WPF Builds #880

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
40 commits
Select commit Hold shift + click to select a range
b84eeff
Adding ApiCompat targets and enabling for System.Xaml
rladuca May 22, 2019
133ea1e
Setting up props to automatically run ApiCompat when appropriate asse…
rladuca May 24, 2019
f5463c8
Enabling .NET 4.8 Api Compat and adding plumbing for ref->lib compat.
rladuca May 24, 2019
d5fce6e
Fixing up location of some properties as we need certain variables to…
rladuca May 24, 2019
44cefe5
Changing to use project name as the key as these are unique, where as…
rladuca May 24, 2019
676f3ea
Adding DARC dependency
rladuca May 24, 2019
32c7f94
Trimming extension assemblies out of the ApiCompat props. These were…
May 31, 2019
72795c0
Removing PresentationUI from compat set as ref assembly was never pub…
May 31, 2019
d64106d
Initial baselines of known breaks that are validated as being allowed…
May 31, 2019
e3f47ca
Adding baseline for System.Xaml
Jun 1, 2019
b58db4b
Update baseline for PresentationBuildTasks
Jun 1, 2019
9c88ee9
Baseline update for UIAClientSideProviders
Jun 1, 2019
a051cf1
Update baseline for WindowsBase
Jun 1, 2019
ba20e65
Update WindowsBase baseline.
Jun 1, 2019
74588b7
Fixing version merges with master
rladuca Jun 5, 2019
db31d69
Baseline additions for PCore, WBase, Xaml
rladuca Jun 5, 2019
86d7601
Update DARC Deps
rladuca Jun 5, 2019
c331ea6
DARC Updates
rladuca Jun 5, 2019
d782bfc
Change to using blob storage to access .NET 4.8 ref assemblies.
rladuca Jun 6, 2019
1114110
Removing MSBuild task prep as we no longer use an inline task.
rladuca Jun 6, 2019
8ce8d65
Remove ref assembly compat as we need to generate more complicated ma…
rladuca Jun 7, 2019
ebed3c4
Guard package include on running ApiCompat.
rladuca Jun 7, 2019
4e1038c
Adding guard to not run APICompat against temp projects used for Mark…
rladuca Jun 7, 2019
2a75e20
Baselining System.Printing-ref
rladuca Jun 7, 2019
940e15a
Fixing missing attribute in System.Printing-ref and re-baselining.
rladuca Jun 7, 2019
748fcff
Moving API Compat baselines into a central directory.
rladuca Jun 7, 2019
096529f
Getting rid of extraneous whitespace.
rladuca Jun 7, 2019
c235f3e
Switch to custom API Compat targets to allow us to run API compat fro…
rladuca Jun 7, 2019
39cb560
Moving baselines folder
Jun 8, 2019
e5ef63a
Removing old baseline files
Jun 8, 2019
e6d20cf
Adding API compat for hand-crafted ref assemblies.
Jun 8, 2019
6532ebb
Adding comments and guards for ManagedCxx vs. C# ref API compat targets.
Jun 8, 2019
d4b72ca
DARC Updates
rladuca Jun 10, 2019
464d968
Merge branch 'master' into dev/roladuca/apicompat
rladuca Jun 10, 2019
4f1ba0b
Fixing global.json
rladuca Jun 10, 2019
8d0552c
Adding documentation.
rladuca Jun 10, 2019
07e8f98
Fixing relative links in md
rladuca Jun 10, 2019
66df286
Further relative link fixes
rladuca Jun 10, 2019
b57f74d
Merging master
rladuca Jun 11, 2019
797a088
DARC Updates
rladuca Jun 11, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 73 additions & 0 deletions Documentation/api-compat.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
# API Compatibility
API compatibility is a build-time check that ensures that an `implementation` assembly implements the API surface area of a `contract` assembly.

For `WPF on .NET Core`, this means the following:
* All `WPF on .NET Core` reference assemblies contain **at least** the API surface area contained by `WPF on .NET Framework 4.8` reference assemblies.
* All hand-crafted reference assemblies for `WPF on .NET Core` contain **exactly** the needed API surface area defined by their corresponding runtime assemblies.

This is accomplished by the use of the [Arcade API Compatibility tool](https://github.com/dotnet/arcade/blob/master/src/Microsoft.DotNet.ApiCompat) with some modifications to fit our specific needs.

## [ApiCompat.props](/eng/WpfArcadeSdk/tools/ApiCompat.props)
This props file implements necessary elements to trigger and control the usage of API Compatibility checks.
### Net48CompatNeededProjects
This property contains a list of projects that should have their reference assemblies compared against reference assemblies for `WPF on .NET Framework 4.8`.
### Net48RefAssembliesDir
This property points to the directory where reference assemblies for `WPF on .NET Framework 4.8` will be downloaded during native tool acquisition. In order
to avoid requiring the [.NET Framework 4.8 Developer Pack](https://dotnet.microsoft.com/download/dotnet-framework/net48) to be installed on all machines that build `WPF on .NET Core`, a private tools zip is used that
contains a copy of these assemblies.
### RefApiCompatNeededProjects
This property contains a list of projects that have hand-crafted references assemblies that must be compared against their corresponding runtime assemblies during API Compatibility checks.

## [ApiCompat.targets](/eng/WpfArcadeSdk/tools/ApiCompat.targets)
This targets file implements necessary targets to run API compatibility checks.
### Properties
#### RunNetFrameworkApiCompat
Controls if a project's reference assembly is checked for API compatibility against the reference assemblies for `WPF on .NET Framework 4.8`.
#### RunRefApiCompat
Controls if a project's hand-crafted reference assembly is checked for API compatibility against its corresponding runtime assembly.
#### RunApiCompat
Controls if Arcade's default API compatibility targets will run. WPF turns this off.
#### ApiCompatBaseline
Controls the location of the API compatibility baseline file for a specific project and API compatibility check.
### Items
These MSBuild Items are important to the setup of the API compatibility checks.
#### ResolvedMatchingContract
This points to the assembly that contains the contract API surface to validate against.
#### ResolvedImplementationAssembly
This points to the assembly whose API surface is being validated.
### Targets
The various targets both setup and execute API compatibility checks.
#### ResolveNetFrameworkApiCompatItems
Sets up [ApiCompatBaseline](#ApiCompatBaseline), [ResolvedMatchingContract](#ResolvedMatchingContract), and [ResolvedImplementationAssembly](#ResolvedImplementationAssembly) for projects that require
API compatibility checks against `WPF on .NET Framework 4.8`. This is run before [WpfValidateApiCompatForNetFramework](#WpfValidateApiCompatForNetFramework) to
ensure that the necessary configuration is availabe for the check.
#### ResolveRefApiCompatItems
Sets up [ApiCompatBaseline](#ApiCompatBaseline), [ResolvedMatchingContract](#ResolvedMatchingContract), and [ResolvedImplementationAssembly](#ResolvedImplementationAssembly) for projects that require
API compatibility checks between runtime assemblies and hand-crafted reference assemblies. This is run before [WpfValidateApiCompatForRef](#WpfValidateApiCompatForRef) to
ensure that the necessary configuration is availabe for the check.
#### WpfValidateApiCompatForNetFramework
Calls the API compatibility tool in order to validate a particular project's reference assembly against the corresponding reference assembly for `WPF on .NET Framework 4.8`.
The [ResolvedMatchingContract](#ResolvedMatchingContract) is the `.NET Framework 4.8` assembly and the [ResolvedImplementationAssembly](#ResolvedImplementationAssembly) is the
`.NET Core` assembly. This will generate and MSBuild error for each compatibility issue found. A developer can examine the current [baseline files](#Baseline-Files) to get
an idea of the kinds of errors that can be reported.

If the tool fails completely, an error of the form "ApiCompat failed for..." will be generated. If this occurs, please [file an issue](https://github.com/dotnet/wpf/issues/new/choose) and include a link to your fork and branch that failed.
#### WpfValidateApiCompatForRef
Calls the API compatibility tool in order to validate a particular project's hand-crafted reference assembly against the corresponding runtime assembly.
The [ResolvedMatchingContract](#ResolvedMatchingContract) is the runtime assembly and the [ResolvedImplementationAssembly](#ResolvedImplementationAssembly) is the
hand-crafted reference assembly. This will generate and MSBuild error for each compatibility issue found. A developer can examine the current [baseline files](#Baseline-Files) to get
an idea of the kinds of errors that can be reported.

If the tool fails completely, an error of the form "ApiCompat failed for..." will be generated. If this occurs, please [file an issue](https://github.com/dotnet/wpf/issues/new/choose) and include a link to your fork and branch that failed.
## [Baseline Files](/src/Microsoft.DotNet.Wpf/ApiCompat/Baselines)
This directory contains the aggregate baseline files for all initial API compatibility checks. The filenames are of the general form
"{Project}-{APICompatType}.baseline.txt", where `APICompatType` is either `Net48` or `ref`.

Errors listed in a baseline file are ignored by the API compatibility tool on subsequent runs.

These baselined errors are, generally, one of the following:
* Intential API changes that diverge from `WPF on .NET Framework 4.8`
* Errors resulting from changes to underlying assemblies in `.NET Core` that do not adversely affect product functionality
* Errors due to build-specific architecture at the time of baselining (e.g. the split nature of WPF's product build).

A developer can re-baseline the entirety of the product by setting the property `BaselineAllAPICompatError` to `true` during a build.
100 changes: 52 additions & 48 deletions eng/Version.Details.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,103 +1,107 @@
<?xml version="1.0" encoding="utf-8"?>
<Dependencies>
<ProductDependencies>
<Dependency Name="Microsoft.Private.Winforms" Version="4.8.0-preview7.19310.2">
<Dependency Name="Microsoft.Private.Winforms" Version="4.8.0-preview7.19311.1">
<Uri>https://github.com/dotnet/winforms</Uri>
<Sha>b8fb4ecab72d1a292f75f14222ec867d7ea77341</Sha>
<Sha>222cadfaec73af00b08bb4fa9cd36c829135ce15</Sha>
</Dependency>
</ProductDependencies>
<ToolsetDependencies>
<Dependency Name="Microsoft.Win32.Registry" Version="4.6.0-preview7.19310.8" CoherentParentDependency="Microsoft.NETCore.App">
<Dependency Name="Microsoft.Win32.Registry" Version="4.6.0-preview7.19311.2" CoherentParentDependency="Microsoft.NETCore.App">
<Uri>https://github.com/dotnet/corefx</Uri>
<Sha>6d37591d13dd58abc90b7f15b707f605e809be29</Sha>
<Sha>082499823f9a80e1d47b3574743f24d8a1447cfa</Sha>
</Dependency>
<Dependency Name="System.CodeDom" Version="4.6.0-preview7.19310.8" CoherentParentDependency="Microsoft.NETCore.App">
<Dependency Name="System.CodeDom" Version="4.6.0-preview7.19311.2" CoherentParentDependency="Microsoft.NETCore.App">
<Uri>https://github.com/dotnet/corefx</Uri>
<Sha>6d37591d13dd58abc90b7f15b707f605e809be29</Sha>
<Sha>082499823f9a80e1d47b3574743f24d8a1447cfa</Sha>
</Dependency>
<Dependency Name="System.Configuration.ConfigurationManager" Version="4.6.0-preview7.19310.8" CoherentParentDependency="Microsoft.NETCore.App">
<Dependency Name="System.Configuration.ConfigurationManager" Version="4.6.0-preview7.19311.2" CoherentParentDependency="Microsoft.NETCore.App">
<Uri>https://github.com/dotnet/corefx</Uri>
<Sha>6d37591d13dd58abc90b7f15b707f605e809be29</Sha>
<Sha>082499823f9a80e1d47b3574743f24d8a1447cfa</Sha>
</Dependency>
<Dependency Name="System.Diagnostics.EventLog" Version="4.6.0-preview7.19310.8" CoherentParentDependency="Microsoft.NETCore.App">
<Dependency Name="System.Diagnostics.EventLog" Version="4.6.0-preview7.19311.2" CoherentParentDependency="Microsoft.NETCore.App">
<Uri>https://github.com/dotnet/corefx</Uri>
<Sha>6d37591d13dd58abc90b7f15b707f605e809be29</Sha>
<Sha>082499823f9a80e1d47b3574743f24d8a1447cfa</Sha>
</Dependency>
<Dependency Name="System.DirectoryServices" Version="4.6.0-preview7.19310.8" CoherentParentDependency="Microsoft.NETCore.App">
<Dependency Name="System.DirectoryServices" Version="4.6.0-preview7.19311.2" CoherentParentDependency="Microsoft.NETCore.App">
<Uri>https://github.com/dotnet/corefx</Uri>
<Sha>6d37591d13dd58abc90b7f15b707f605e809be29</Sha>
<Sha>082499823f9a80e1d47b3574743f24d8a1447cfa</Sha>
</Dependency>
<Dependency Name="System.Drawing.Common" Version="4.6.0-preview7.19310.8" CoherentParentDependency="Microsoft.NETCore.App">
<Dependency Name="System.Drawing.Common" Version="4.6.0-preview7.19311.2" CoherentParentDependency="Microsoft.NETCore.App">
<Uri>https://github.com/dotnet/corefx</Uri>
<Sha>6d37591d13dd58abc90b7f15b707f605e809be29</Sha>
<Sha>082499823f9a80e1d47b3574743f24d8a1447cfa</Sha>
</Dependency>
<Dependency Name="System.Reflection.Emit" Version="4.6.0-preview7.19310.8" CoherentParentDependency="Microsoft.NETCore.App">
<Dependency Name="System.Reflection.Emit" Version="4.6.0-preview7.19311.2" CoherentParentDependency="Microsoft.NETCore.App">
<Uri>https://github.com/dotnet/corefx</Uri>
<Sha>6d37591d13dd58abc90b7f15b707f605e809be29</Sha>
<Sha>082499823f9a80e1d47b3574743f24d8a1447cfa</Sha>
</Dependency>
<Dependency Name="System.Reflection.MetadataLoadContext" Version="4.6.0-preview7.19310.8" CoherentParentDependency="Microsoft.NETCore.App">
<Dependency Name="System.Reflection.MetadataLoadContext" Version="4.6.0-preview7.19311.2" CoherentParentDependency="Microsoft.NETCore.App">
<Uri>https://github.com/dotnet/corefx</Uri>
<Sha>6d37591d13dd58abc90b7f15b707f605e809be29</Sha>
<Sha>082499823f9a80e1d47b3574743f24d8a1447cfa</Sha>
</Dependency>
<Dependency Name="System.Security.AccessControl" Version="4.6.0-preview7.19310.8" CoherentParentDependency="Microsoft.NETCore.App">
<Dependency Name="System.Security.AccessControl" Version="4.6.0-preview7.19311.2" CoherentParentDependency="Microsoft.NETCore.App">
<Uri>https://github.com/dotnet/corefx</Uri>
<Sha>6d37591d13dd58abc90b7f15b707f605e809be29</Sha>
<Sha>082499823f9a80e1d47b3574743f24d8a1447cfa</Sha>
</Dependency>
<Dependency Name="System.Security.Cryptography.Xml" Version="4.6.0-preview7.19310.8" CoherentParentDependency="Microsoft.NETCore.App">
<Dependency Name="System.Security.Cryptography.Xml" Version="4.6.0-preview7.19311.2" CoherentParentDependency="Microsoft.NETCore.App">
<Uri>https://github.com/dotnet/corefx</Uri>
<Sha>6d37591d13dd58abc90b7f15b707f605e809be29</Sha>
<Sha>082499823f9a80e1d47b3574743f24d8a1447cfa</Sha>
</Dependency>
<Dependency Name="System.Security.Permissions" Version="4.6.0-preview7.19310.8" CoherentParentDependency="Microsoft.NETCore.App">
<Dependency Name="System.Security.Permissions" Version="4.6.0-preview7.19311.2" CoherentParentDependency="Microsoft.NETCore.App">
<Uri>https://github.com/dotnet/corefx</Uri>
<Sha>6d37591d13dd58abc90b7f15b707f605e809be29</Sha>
<Sha>082499823f9a80e1d47b3574743f24d8a1447cfa</Sha>
</Dependency>
<Dependency Name="System.Security.Principal.Windows" Version="4.6.0-preview7.19310.8" CoherentParentDependency="Microsoft.NETCore.App">
<Dependency Name="System.Security.Principal.Windows" Version="4.6.0-preview7.19311.2" CoherentParentDependency="Microsoft.NETCore.App">
<Uri>https://github.com/dotnet/corefx</Uri>
<Sha>6d37591d13dd58abc90b7f15b707f605e809be29</Sha>
<Sha>082499823f9a80e1d47b3574743f24d8a1447cfa</Sha>
</Dependency>
<Dependency Name="System.Windows.Extensions" Version="4.6.0-preview7.19310.8" CoherentParentDependency="Microsoft.NETCore.App">
<Dependency Name="System.Windows.Extensions" Version="4.6.0-preview7.19311.2" CoherentParentDependency="Microsoft.NETCore.App">
<Uri>https://github.com/dotnet/corefx</Uri>
<Sha>6d37591d13dd58abc90b7f15b707f605e809be29</Sha>
<Sha>082499823f9a80e1d47b3574743f24d8a1447cfa</Sha>
</Dependency>
<Dependency Name="Microsoft.NETCore.App" Version="3.0.0-preview7-27811-01">
<Dependency Name="Microsoft.NETCore.App" Version="3.0.0-preview7-27811-07">
<Uri>https://github.com/dotnet/core-setup</Uri>
<Sha>bba327461e7521b640be91127309760a18f12416</Sha>
<Sha>3f692b82905b83e775d49984b3e8507e6afeb5de</Sha>
</Dependency>
<Dependency Name="Microsoft.DotNet.Arcade.Sdk" Version="1.0.0-beta.19310.24">
<Dependency Name="Microsoft.DotNet.Arcade.Sdk" Version="1.0.0-beta.19311.2">
<Uri>https://github.com/dotnet/arcade</Uri>
<Sha>f268510de7a7bcf800a6966830f8d11ff8d24e0d</Sha>
<Sha>dfc41299b9aadb1ca98093d660df81811eca901b</Sha>
</Dependency>
<Dependency Name="Microsoft.DotNet.CodeAnalysis" Version="1.0.0-beta.19310.24">
<Dependency Name="Microsoft.DotNet.CodeAnalysis" Version="1.0.0-beta.19311.2">
<Uri>https://github.com/dotnet/arcade</Uri>
<Sha>f268510de7a7bcf800a6966830f8d11ff8d24e0d</Sha>
<Sha>dfc41299b9aadb1ca98093d660df81811eca901b</Sha>
</Dependency>
<Dependency Name="Microsoft.NETCore.Platforms" Version="3.0.0-preview7.19310.8" CoherentParentDependency="Microsoft.NETCore.App">
<Dependency Name="Microsoft.NETCore.Platforms" Version="3.0.0-preview7.19311.2" CoherentParentDependency="Microsoft.NETCore.App">
<Uri>https://github.com/dotnet/corefx</Uri>
<Sha>6d37591d13dd58abc90b7f15b707f605e809be29</Sha>
<Sha>082499823f9a80e1d47b3574743f24d8a1447cfa</Sha>
</Dependency>
<Dependency Name="Microsoft.DotNet.Wpf.DncEng" Version="4.8.0-preview7.19310.4">
<Dependency Name="Microsoft.DotNet.Wpf.DncEng" Version="4.8.0-preview7.19311.6">
<Uri>https://dev.azure.com/dnceng/internal/_git/dotnet-wpf-int</Uri>
<Sha>e99b2cb79ebb6fe0050a90b41da86fe5ee32662d</Sha>
<Sha>95764b755a2cd678f40e2a2cfc83d17672e511da</Sha>
</Dependency>
<Dependency Name="System.IO.Packaging" Version="4.6.0-preview7.19310.8" CoherentParentDependency="Microsoft.NETCore.App">
<Dependency Name="System.IO.Packaging" Version="4.6.0-preview7.19311.2" CoherentParentDependency="Microsoft.NETCore.App">
<Uri>https://github.com/dotnet/corefx</Uri>
<Sha>6d37591d13dd58abc90b7f15b707f605e809be29</Sha>
<Sha>082499823f9a80e1d47b3574743f24d8a1447cfa</Sha>
</Dependency>
<Dependency Name="Microsoft.NETCore.Runtime.CoreCLR" Version="3.0.0-preview7.19310.2" CoherentParentDependency="Microsoft.NETCore.App">
<Dependency Name="Microsoft.NETCore.Runtime.CoreCLR" Version="3.0.0-preview7.19311.1" CoherentParentDependency="Microsoft.NETCore.App">
<Uri>https://github.com/dotnet/coreclr</Uri>
<Sha>a64fd279a830a91e2e687d1456ba742823176e63</Sha>
<Sha>f70085f37f3c49618087f852e44165954b3ed8d6</Sha>
</Dependency>
<Dependency Name="Microsoft.NETCore.ILDAsm" Version="3.0.0-preview7.19310.2" CoherentParentDependency="Microsoft.NETCore.Runtime.CoreCLR">
<Dependency Name="Microsoft.NETCore.ILDAsm" Version="3.0.0-preview7.19311.1" CoherentParentDependency="Microsoft.NETCore.Runtime.CoreCLR">
<Uri>https://github.com/dotnet/coreclr</Uri>
<Sha>a64fd279a830a91e2e687d1456ba742823176e63</Sha>
<Sha>f70085f37f3c49618087f852e44165954b3ed8d6</Sha>
</Dependency>
<Dependency Name="Microsoft.NETCore.ILAsm" Version="3.0.0-preview7.19310.2" CoherentParentDependency="Microsoft.NETCore.Runtime.CoreCLR">
<Dependency Name="Microsoft.NETCore.ILAsm" Version="3.0.0-preview7.19311.1" CoherentParentDependency="Microsoft.NETCore.Runtime.CoreCLR">
<Uri>https://github.com/dotnet/coreclr</Uri>
<Sha>a64fd279a830a91e2e687d1456ba742823176e63</Sha>
<Sha>f70085f37f3c49618087f852e44165954b3ed8d6</Sha>
</Dependency>
<Dependency Name="Microsoft.DotNet.Helix.Sdk" Version="2.0.0-beta.19310.24">
<Dependency Name="Microsoft.DotNet.Helix.Sdk" Version="2.0.0-beta.19311.2">
<Uri>https://github.com/dotnet/arcade</Uri>
<Sha>f268510de7a7bcf800a6966830f8d11ff8d24e0d</Sha>
<Sha>dfc41299b9aadb1ca98093d660df81811eca901b</Sha>
</Dependency>
<Dependency Name="Microsoft.DotNet.ApiCompat" Version="1.0.0-beta.19311.2">
<Uri>https://github.com/dotnet/arcade</Uri>
<Sha>dfc41299b9aadb1ca98093d660df81811eca901b</Sha>
</Dependency>
</ToolsetDependencies>
</Dependencies>
Loading