Skip to content

Commit 9c5dd1a

Browse files
rladucarladuca
authored
Enable APICompat in WPF Builds (#880)
* Adding ApiCompat targets and enabling for System.Xaml * Setting up props to automatically run ApiCompat when appropriate assemblies are being built. * Enabling .NET 4.8 Api Compat and adding plumbing for ref->lib compat. * Fixing up location of some properties as we need certain variables to exist. Starting implementation of repo-specific ApiCompat so that things just work when code is internal or public. * Changing to use project name as the key as these are unique, where assembly names are shared between lib/ref/cycle-breakers. * Adding DARC dependency * Trimming extension assemblies out of the ApiCompat props. These were never shipped as ref assemblies in .NET 4.8, so we don't need to verify compat for them. * Removing PresentationUI from compat set as ref assembly was never published in .NET Framework. * Initial baselines of known breaks that are validated as being allowed in the port. Some errors may still arise from the build here as there are open issues still. * Adding baseline for System.Xaml * Update baseline for PresentationBuildTasks * Baseline update for UIAClientSideProviders * Update baseline for WindowsBase * Update WindowsBase baseline. * Fixing version merges with master * Baseline additions for PCore, WBase, Xaml * Update DARC Deps * DARC Updates * Change to using blob storage to access .NET 4.8 ref assemblies. * Removing MSBuild task prep as we no longer use an inline task. * Remove ref assembly compat as we need to generate more complicated matching pairs than the standard ApiCompat targets allow. * Guard package include on running ApiCompat. * Adding guard to not run APICompat against temp projects used for MarkupCompilation. * Baselining System.Printing-ref * Fixing missing attribute in System.Printing-ref and re-baselining. * Moving API Compat baselines into a central directory. * Getting rid of extraneous whitespace. * Switch to custom API Compat targets to allow us to run API compat from our compiler generated ref assemblies to .NET 4.8. This also will enable hand-crafted ref assembly compat vs the associate lib assembly and cycle-break api compat. * Moving baselines folder * Removing old baseline files * Adding API compat for hand-crafted ref assemblies. * Adding comments and guards for ManagedCxx vs. C# ref API compat targets. * DARC Updates * Fixing global.json * Adding documentation. * Fixing relative links in md * Further relative link fixes * DARC Updates
1 parent 42f8d28 commit 9c5dd1a

22 files changed

Lines changed: 578 additions & 73 deletions

‎Documentation/api-compat.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# API Compatibility
2+
API compatibility is a build-time check that ensures that an `implementation` assembly implements the API surface area of a `contract` assembly.
3+
4+
For `WPF on .NET Core`, this means the following:
5+
* All `WPF on .NET Core` reference assemblies contain **at least** the API surface area contained by `WPF on .NET Framework 4.8` reference assemblies.
6+
* All hand-crafted reference assemblies for `WPF on .NET Core` contain **exactly** the needed API surface area defined by their corresponding runtime assemblies.
7+
8+
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.
9+
10+
## [ApiCompat.props](/eng/WpfArcadeSdk/tools/ApiCompat.props)
11+
This props file implements necessary elements to trigger and control the usage of API Compatibility checks.
12+
### Net48CompatNeededProjects
13+
This property contains a list of projects that should have their reference assemblies compared against reference assemblies for `WPF on .NET Framework 4.8`.
14+
### Net48RefAssembliesDir
15+
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
16+
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
17+
contains a copy of these assemblies.
18+
### RefApiCompatNeededProjects
19+
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.
20+
21+
## [ApiCompat.targets](/eng/WpfArcadeSdk/tools/ApiCompat.targets)
22+
This targets file implements necessary targets to run API compatibility checks.
23+
### Properties
24+
#### RunNetFrameworkApiCompat
25+
Controls if a project's reference assembly is checked for API compatibility against the reference assemblies for `WPF on .NET Framework 4.8`.
26+
#### RunRefApiCompat
27+
Controls if a project's hand-crafted reference assembly is checked for API compatibility against its corresponding runtime assembly.
28+
#### RunApiCompat
29+
Controls if Arcade's default API compatibility targets will run. WPF turns this off.
30+
#### ApiCompatBaseline
31+
Controls the location of the API compatibility baseline file for a specific project and API compatibility check.
32+
### Items
33+
These MSBuild Items are important to the setup of the API compatibility checks.
34+
#### ResolvedMatchingContract
35+
This points to the assembly that contains the contract API surface to validate against.
36+
#### ResolvedImplementationAssembly
37+
This points to the assembly whose API surface is being validated.
38+
### Targets
39+
The various targets both setup and execute API compatibility checks.
40+
#### ResolveNetFrameworkApiCompatItems
41+
Sets up [ApiCompatBaseline](#ApiCompatBaseline), [ResolvedMatchingContract](#ResolvedMatchingContract), and [ResolvedImplementationAssembly](#ResolvedImplementationAssembly) for projects that require
42+
API compatibility checks against `WPF on .NET Framework 4.8`. This is run before [WpfValidateApiCompatForNetFramework](#WpfValidateApiCompatForNetFramework) to
43+
ensure that the necessary configuration is availabe for the check.
44+
#### ResolveRefApiCompatItems
45+
Sets up [ApiCompatBaseline](#ApiCompatBaseline), [ResolvedMatchingContract](#ResolvedMatchingContract), and [ResolvedImplementationAssembly](#ResolvedImplementationAssembly) for projects that require
46+
API compatibility checks between runtime assemblies and hand-crafted reference assemblies. This is run before [WpfValidateApiCompatForRef](#WpfValidateApiCompatForRef) to
47+
ensure that the necessary configuration is availabe for the check.
48+
#### WpfValidateApiCompatForNetFramework
49+
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`.
50+
The [ResolvedMatchingContract](#ResolvedMatchingContract) is the `.NET Framework 4.8` assembly and the [ResolvedImplementationAssembly](#ResolvedImplementationAssembly) is the
51+
`.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
52+
an idea of the kinds of errors that can be reported.
53+
54+
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.
55+
#### WpfValidateApiCompatForRef
56+
Calls the API compatibility tool in order to validate a particular project's hand-crafted reference assembly against the corresponding runtime assembly.
57+
The [ResolvedMatchingContract](#ResolvedMatchingContract) is the runtime assembly and the [ResolvedImplementationAssembly](#ResolvedImplementationAssembly) is the
58+
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
59+
an idea of the kinds of errors that can be reported.
60+
61+
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.
62+
## [Baseline Files](/src/Microsoft.DotNet.Wpf/ApiCompat/Baselines)
63+
This directory contains the aggregate baseline files for all initial API compatibility checks. The filenames are of the general form
64+
"{Project}-{APICompatType}.baseline.txt", where `APICompatType` is either `Net48` or `ref`.
65+
66+
Errors listed in a baseline file are ignored by the API compatibility tool on subsequent runs.
67+
68+
These baselined errors are, generally, one of the following:
69+
* Intential API changes that diverge from `WPF on .NET Framework 4.8`
70+
* Errors resulting from changes to underlying assemblies in `.NET Core` that do not adversely affect product functionality
71+
* Errors due to build-specific architecture at the time of baselining (e.g. the split nature of WPF's product build).
72+
73+
A developer can re-baseline the entirety of the product by setting the property `BaselineAllAPICompatError` to `true` during a build.

‎eng/Version.Details.xml‎

Lines changed: 52 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -1,103 +1,107 @@
11
<?xml version="1.0" encoding="utf-8"?>
22
<Dependencies>
33
<ProductDependencies>
4-
<Dependency Name="Microsoft.Private.Winforms" Version="4.8.0-preview7.19310.2">
4+
<Dependency Name="Microsoft.Private.Winforms" Version="4.8.0-preview7.19311.1">
55
<Uri>https://github.com/dotnet/winforms</Uri>
6-
<Sha>b8fb4ecab72d1a292f75f14222ec867d7ea77341</Sha>
6+
<Sha>222cadfaec73af00b08bb4fa9cd36c829135ce15</Sha>
77
</Dependency>
88
</ProductDependencies>
99
<ToolsetDependencies>
10-
<Dependency Name="Microsoft.Win32.Registry" Version="4.6.0-preview7.19310.8" CoherentParentDependency="Microsoft.NETCore.App">
10+
<Dependency Name="Microsoft.Win32.Registry" Version="4.6.0-preview7.19311.2" CoherentParentDependency="Microsoft.NETCore.App">
1111
<Uri>https://github.com/dotnet/corefx</Uri>
12-
<Sha>6d37591d13dd58abc90b7f15b707f605e809be29</Sha>
12+
<Sha>082499823f9a80e1d47b3574743f24d8a1447cfa</Sha>
1313
</Dependency>
14-
<Dependency Name="System.CodeDom" Version="4.6.0-preview7.19310.8" CoherentParentDependency="Microsoft.NETCore.App">
14+
<Dependency Name="System.CodeDom" Version="4.6.0-preview7.19311.2" CoherentParentDependency="Microsoft.NETCore.App">
1515
<Uri>https://github.com/dotnet/corefx</Uri>
16-
<Sha>6d37591d13dd58abc90b7f15b707f605e809be29</Sha>
16+
<Sha>082499823f9a80e1d47b3574743f24d8a1447cfa</Sha>
1717
</Dependency>
18-
<Dependency Name="System.Configuration.ConfigurationManager" Version="4.6.0-preview7.19310.8" CoherentParentDependency="Microsoft.NETCore.App">
18+
<Dependency Name="System.Configuration.ConfigurationManager" Version="4.6.0-preview7.19311.2" CoherentParentDependency="Microsoft.NETCore.App">
1919
<Uri>https://github.com/dotnet/corefx</Uri>
20-
<Sha>6d37591d13dd58abc90b7f15b707f605e809be29</Sha>
20+
<Sha>082499823f9a80e1d47b3574743f24d8a1447cfa</Sha>
2121
</Dependency>
22-
<Dependency Name="System.Diagnostics.EventLog" Version="4.6.0-preview7.19310.8" CoherentParentDependency="Microsoft.NETCore.App">
22+
<Dependency Name="System.Diagnostics.EventLog" Version="4.6.0-preview7.19311.2" CoherentParentDependency="Microsoft.NETCore.App">
2323
<Uri>https://github.com/dotnet/corefx</Uri>
24-
<Sha>6d37591d13dd58abc90b7f15b707f605e809be29</Sha>
24+
<Sha>082499823f9a80e1d47b3574743f24d8a1447cfa</Sha>
2525
</Dependency>
26-
<Dependency Name="System.DirectoryServices" Version="4.6.0-preview7.19310.8" CoherentParentDependency="Microsoft.NETCore.App">
26+
<Dependency Name="System.DirectoryServices" Version="4.6.0-preview7.19311.2" CoherentParentDependency="Microsoft.NETCore.App">
2727
<Uri>https://github.com/dotnet/corefx</Uri>
28-
<Sha>6d37591d13dd58abc90b7f15b707f605e809be29</Sha>
28+
<Sha>082499823f9a80e1d47b3574743f24d8a1447cfa</Sha>
2929
</Dependency>
30-
<Dependency Name="System.Drawing.Common" Version="4.6.0-preview7.19310.8" CoherentParentDependency="Microsoft.NETCore.App">
30+
<Dependency Name="System.Drawing.Common" Version="4.6.0-preview7.19311.2" CoherentParentDependency="Microsoft.NETCore.App">
3131
<Uri>https://github.com/dotnet/corefx</Uri>
32-
<Sha>6d37591d13dd58abc90b7f15b707f605e809be29</Sha>
32+
<Sha>082499823f9a80e1d47b3574743f24d8a1447cfa</Sha>
3333
</Dependency>
34-
<Dependency Name="System.Reflection.Emit" Version="4.6.0-preview7.19310.8" CoherentParentDependency="Microsoft.NETCore.App">
34+
<Dependency Name="System.Reflection.Emit" Version="4.6.0-preview7.19311.2" CoherentParentDependency="Microsoft.NETCore.App">
3535
<Uri>https://github.com/dotnet/corefx</Uri>
36-
<Sha>6d37591d13dd58abc90b7f15b707f605e809be29</Sha>
36+
<Sha>082499823f9a80e1d47b3574743f24d8a1447cfa</Sha>
3737
</Dependency>
38-
<Dependency Name="System.Reflection.MetadataLoadContext" Version="4.6.0-preview7.19310.8" CoherentParentDependency="Microsoft.NETCore.App">
38+
<Dependency Name="System.Reflection.MetadataLoadContext" Version="4.6.0-preview7.19311.2" CoherentParentDependency="Microsoft.NETCore.App">
3939
<Uri>https://github.com/dotnet/corefx</Uri>
40-
<Sha>6d37591d13dd58abc90b7f15b707f605e809be29</Sha>
40+
<Sha>082499823f9a80e1d47b3574743f24d8a1447cfa</Sha>
4141
</Dependency>
42-
<Dependency Name="System.Security.AccessControl" Version="4.6.0-preview7.19310.8" CoherentParentDependency="Microsoft.NETCore.App">
42+
<Dependency Name="System.Security.AccessControl" Version="4.6.0-preview7.19311.2" CoherentParentDependency="Microsoft.NETCore.App">
4343
<Uri>https://github.com/dotnet/corefx</Uri>
44-
<Sha>6d37591d13dd58abc90b7f15b707f605e809be29</Sha>
44+
<Sha>082499823f9a80e1d47b3574743f24d8a1447cfa</Sha>
4545
</Dependency>
46-
<Dependency Name="System.Security.Cryptography.Xml" Version="4.6.0-preview7.19310.8" CoherentParentDependency="Microsoft.NETCore.App">
46+
<Dependency Name="System.Security.Cryptography.Xml" Version="4.6.0-preview7.19311.2" CoherentParentDependency="Microsoft.NETCore.App">
4747
<Uri>https://github.com/dotnet/corefx</Uri>
48-
<Sha>6d37591d13dd58abc90b7f15b707f605e809be29</Sha>
48+
<Sha>082499823f9a80e1d47b3574743f24d8a1447cfa</Sha>
4949
</Dependency>
50-
<Dependency Name="System.Security.Permissions" Version="4.6.0-preview7.19310.8" CoherentParentDependency="Microsoft.NETCore.App">
50+
<Dependency Name="System.Security.Permissions" Version="4.6.0-preview7.19311.2" CoherentParentDependency="Microsoft.NETCore.App">
5151
<Uri>https://github.com/dotnet/corefx</Uri>
52-
<Sha>6d37591d13dd58abc90b7f15b707f605e809be29</Sha>
52+
<Sha>082499823f9a80e1d47b3574743f24d8a1447cfa</Sha>
5353
</Dependency>
54-
<Dependency Name="System.Security.Principal.Windows" Version="4.6.0-preview7.19310.8" CoherentParentDependency="Microsoft.NETCore.App">
54+
<Dependency Name="System.Security.Principal.Windows" Version="4.6.0-preview7.19311.2" CoherentParentDependency="Microsoft.NETCore.App">
5555
<Uri>https://github.com/dotnet/corefx</Uri>
56-
<Sha>6d37591d13dd58abc90b7f15b707f605e809be29</Sha>
56+
<Sha>082499823f9a80e1d47b3574743f24d8a1447cfa</Sha>
5757
</Dependency>
58-
<Dependency Name="System.Windows.Extensions" Version="4.6.0-preview7.19310.8" CoherentParentDependency="Microsoft.NETCore.App">
58+
<Dependency Name="System.Windows.Extensions" Version="4.6.0-preview7.19311.2" CoherentParentDependency="Microsoft.NETCore.App">
5959
<Uri>https://github.com/dotnet/corefx</Uri>
60-
<Sha>6d37591d13dd58abc90b7f15b707f605e809be29</Sha>
60+
<Sha>082499823f9a80e1d47b3574743f24d8a1447cfa</Sha>
6161
</Dependency>
62-
<Dependency Name="Microsoft.NETCore.App" Version="3.0.0-preview7-27811-01">
62+
<Dependency Name="Microsoft.NETCore.App" Version="3.0.0-preview7-27811-07">
6363
<Uri>https://github.com/dotnet/core-setup</Uri>
64-
<Sha>bba327461e7521b640be91127309760a18f12416</Sha>
64+
<Sha>3f692b82905b83e775d49984b3e8507e6afeb5de</Sha>
6565
</Dependency>
66-
<Dependency Name="Microsoft.DotNet.Arcade.Sdk" Version="1.0.0-beta.19310.24">
66+
<Dependency Name="Microsoft.DotNet.Arcade.Sdk" Version="1.0.0-beta.19311.2">
6767
<Uri>https://github.com/dotnet/arcade</Uri>
68-
<Sha>f268510de7a7bcf800a6966830f8d11ff8d24e0d</Sha>
68+
<Sha>dfc41299b9aadb1ca98093d660df81811eca901b</Sha>
6969
</Dependency>
70-
<Dependency Name="Microsoft.DotNet.CodeAnalysis" Version="1.0.0-beta.19310.24">
70+
<Dependency Name="Microsoft.DotNet.CodeAnalysis" Version="1.0.0-beta.19311.2">
7171
<Uri>https://github.com/dotnet/arcade</Uri>
72-
<Sha>f268510de7a7bcf800a6966830f8d11ff8d24e0d</Sha>
72+
<Sha>dfc41299b9aadb1ca98093d660df81811eca901b</Sha>
7373
</Dependency>
74-
<Dependency Name="Microsoft.NETCore.Platforms" Version="3.0.0-preview7.19310.8" CoherentParentDependency="Microsoft.NETCore.App">
74+
<Dependency Name="Microsoft.NETCore.Platforms" Version="3.0.0-preview7.19311.2" CoherentParentDependency="Microsoft.NETCore.App">
7575
<Uri>https://github.com/dotnet/corefx</Uri>
76-
<Sha>6d37591d13dd58abc90b7f15b707f605e809be29</Sha>
76+
<Sha>082499823f9a80e1d47b3574743f24d8a1447cfa</Sha>
7777
</Dependency>
78-
<Dependency Name="Microsoft.DotNet.Wpf.DncEng" Version="4.8.0-preview7.19310.4">
78+
<Dependency Name="Microsoft.DotNet.Wpf.DncEng" Version="4.8.0-preview7.19311.6">
7979
<Uri>https://dev.azure.com/dnceng/internal/_git/dotnet-wpf-int</Uri>
80-
<Sha>e99b2cb79ebb6fe0050a90b41da86fe5ee32662d</Sha>
80+
<Sha>95764b755a2cd678f40e2a2cfc83d17672e511da</Sha>
8181
</Dependency>
82-
<Dependency Name="System.IO.Packaging" Version="4.6.0-preview7.19310.8" CoherentParentDependency="Microsoft.NETCore.App">
82+
<Dependency Name="System.IO.Packaging" Version="4.6.0-preview7.19311.2" CoherentParentDependency="Microsoft.NETCore.App">
8383
<Uri>https://github.com/dotnet/corefx</Uri>
84-
<Sha>6d37591d13dd58abc90b7f15b707f605e809be29</Sha>
84+
<Sha>082499823f9a80e1d47b3574743f24d8a1447cfa</Sha>
8585
</Dependency>
86-
<Dependency Name="Microsoft.NETCore.Runtime.CoreCLR" Version="3.0.0-preview7.19310.2" CoherentParentDependency="Microsoft.NETCore.App">
86+
<Dependency Name="Microsoft.NETCore.Runtime.CoreCLR" Version="3.0.0-preview7.19311.1" CoherentParentDependency="Microsoft.NETCore.App">
8787
<Uri>https://github.com/dotnet/coreclr</Uri>
88-
<Sha>a64fd279a830a91e2e687d1456ba742823176e63</Sha>
88+
<Sha>f70085f37f3c49618087f852e44165954b3ed8d6</Sha>
8989
</Dependency>
90-
<Dependency Name="Microsoft.NETCore.ILDAsm" Version="3.0.0-preview7.19310.2" CoherentParentDependency="Microsoft.NETCore.Runtime.CoreCLR">
90+
<Dependency Name="Microsoft.NETCore.ILDAsm" Version="3.0.0-preview7.19311.1" CoherentParentDependency="Microsoft.NETCore.Runtime.CoreCLR">
9191
<Uri>https://github.com/dotnet/coreclr</Uri>
92-
<Sha>a64fd279a830a91e2e687d1456ba742823176e63</Sha>
92+
<Sha>f70085f37f3c49618087f852e44165954b3ed8d6</Sha>
9393
</Dependency>
94-
<Dependency Name="Microsoft.NETCore.ILAsm" Version="3.0.0-preview7.19310.2" CoherentParentDependency="Microsoft.NETCore.Runtime.CoreCLR">
94+
<Dependency Name="Microsoft.NETCore.ILAsm" Version="3.0.0-preview7.19311.1" CoherentParentDependency="Microsoft.NETCore.Runtime.CoreCLR">
9595
<Uri>https://github.com/dotnet/coreclr</Uri>
96-
<Sha>a64fd279a830a91e2e687d1456ba742823176e63</Sha>
96+
<Sha>f70085f37f3c49618087f852e44165954b3ed8d6</Sha>
9797
</Dependency>
98-
<Dependency Name="Microsoft.DotNet.Helix.Sdk" Version="2.0.0-beta.19310.24">
98+
<Dependency Name="Microsoft.DotNet.Helix.Sdk" Version="2.0.0-beta.19311.2">
9999
<Uri>https://github.com/dotnet/arcade</Uri>
100-
<Sha>f268510de7a7bcf800a6966830f8d11ff8d24e0d</Sha>
100+
<Sha>dfc41299b9aadb1ca98093d660df81811eca901b</Sha>
101+
</Dependency>
102+
<Dependency Name="Microsoft.DotNet.ApiCompat" Version="1.0.0-beta.19311.2">
103+
<Uri>https://github.com/dotnet/arcade</Uri>
104+
<Sha>dfc41299b9aadb1ca98093d660df81811eca901b</Sha>
101105
</Dependency>
102106
</ToolsetDependencies>
103107
</Dependencies>

0 commit comments

Comments
 (0)