You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Convert C# Reference Assembly Generation to Use GenAPI (dotnet#1057)
* Adding DARC dependency for Microsoft.DotNet.GenAPI and updating
* Version updates, adding basic target
* Enabling GenAPI to generate sources for all applicable assemblies.
Disabling use of ProduceReferenceAssembly across the codebase.
* Adding PBT to GenAPI project list.
* Initial build targets for GenAPI and generated reference assembly projects.
* Reverting to projects explicitly declaring their needed PackageReferences. Otherwise we can potentially import at incorrect times, overriding various values from the WpfArcadeSdk.
* Adding additional GenAPI params.
* Switching to generate the reference assembly project via a task using the runtime assembly's project as a template. Based on PBT's GenerateTemporaryTargetAssembly.
* Adding project exclusions for WIndowsBase
* Turning off XLIFF generation for reference assemblies.
Removing EmbeddedResources from reference assemblies.
* Removing module initializer injection from PCore-ref
* Removing CompileDependsOn from PFramework-ref
* Removing disabling of default compile items to pickup the generated reference sources.
* Adding global API exclusions file.
* Removing further default excludes.
* Adding initial exclusions and NoWarns based on building.
* Initial change to manual reference assembly projects.
File dumping the initial generated code and projects.
* Modifications to build System.Xaml-ref.
Changes to ensure that reference assembly projects are properly bin placed into the ref pack.
* Fixing issues with checks against hand ref assembly property.
Adding WindowsBase reference assembly.
* Adding UIAutomationTypes reference assembly
* Adding reference project for UIAutomationProvider
* Adding UIAutomationClient ref project
* Removing workaround for WindowsBase GenAPI issue and adding back manually fixed output for WindowsBase reference assembly.
* Adding UIAutomationClientSideProviders reference project.
* Adding System.Windows.Input.Manipulations reference project
* Adding PresentationBuildTasks reference project
* Adding PresentationCore ref project.
* Cleaning up PresentationCore ref assembly and adding exclusion notes.
* Adding security attributes to exclusions
* Fixing exclusion list
* Fixing exclude param
* Fixing attribute exclusions to match CoreFX.
Fixing cmd line params to GenAPI.
* Applying new exclusions to ref assembly code and fixups
* Cleaning UIA assemblies and updating code with latest exclusions.
* New exclusions and cleanup
* PBT cleanup and new exclusions
* New exclusions and fixups for PCore ref assembly
* Adding ReachFramework ref project and cleaning.
* Adding PresentationFramework reference assembly and fixups.
* Removing any extraneous ProjectReferences from reference assembly projects. Anything that is not itself a reference assembly was removed.
* Adding back assembly attributes to ref assemblies where applicable.
Fixing PresentationFramework-ref to use private copy of asm attributes due to internals dependency.
* Removing PBT reference assembly as we're not shipping one anymore.
* Further removing PBT-ref
* Adding the ReferenceAssemblyAttribute to all hand-crafted ref assemblies.
* Removing no longer applicable tasks
* Fixing an issue with incorrect signing of System.Xaml.
* Enable ApiCompat against new ref assemblies.
Fixing ApiCompat issues with PCore and re-baselining.
* PresentationFramework ApiCompat baseline
* ReachFramework ApiCompat baseline
* System.Windows.Input.Manipulations ApiCompat baseline
* UIA ApiCompat baselines
* Fixing removal of ObsoleteAttribute and ApiCompat baseline for System.Xaml
* ApiCompat baselines for WindowsBase
* Updating WindowsBase ApiCompat baseline.
* Adding back attributes that were removed incorrectly.
* Fixing missing attributes
* Fixing missing attributes on reachframework
* Updating PCore baselines and adding back missing attrs
* PresentationFramework fixup + baselines
* Fixing ApiCompat bugs
* Re-baselining with ApiCompat fixes and removing old, no longer applicable baseline files.
* Updating reference assemblies due to System.Security.Permissions changes.
* Fixing up ResolveMicrosoftDotNetWpfGitHubReferences so that dotnet_wpf_int references lib assemblies instead of ref assemblies from the GitHub package.
* Fixing up ApiCompat for C++\CLI vs C# runtime projects.
* Fixing PackageRefernece for RID specific MicrosoftDotNetWpfGitHubPackageso that it doesn't get added when the package isn't defined (building in the open).
* Adding dotnet-wpf-int ref assemblies to signing and apicompat.
* Cleaning up reference assembly generation.
Fixing Intellisense XML placement.
* Add back internals to support XAML compilation.
In WPF on .NET Core, C# reference assemblies are created via the use of [GenAPI](https://github.com/dotnet/arcade/tree/master/src/Microsoft.DotNet.GenAPI) and a separate reference assembly project located in the `ref` directory under a particular assemblies source directory.
3
+
4
+
WPF assemblies make extensive use of the [InternalsVisibleToAttribute](https://docs.microsoft.com/en-us/dotnet/api/system.runtime.compilerservices.internalsvisibletoattribute?view=netcore-3.0) which precludes the use of [ProduceReferenceAssembly](https://docs.microsoft.com/en-us/visualstudio/msbuild/common-msbuild-project-properties?view=vs-2019) or [ProduceOnlyReferenceAssembly](https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-options/refonly-compiler-option). This is because these compiler options will include internal types and members in the reference assembly. In WPF, this creates dangling references to assemblies that do not exist in the `WindowsDesktop` reference pack.
5
+
6
+
Using GenAPI allows us to strip out internals, removing the dangling references from our reference assemblies.
Contains various properties related to GenAPI runs and configurations.
10
+
*`GenAPIEnabledProjects`
11
+
* The set of projects to run GenAPI on
12
+
*`GlobalApiExclusionsFile`
13
+
* A file that specifies API surface area to exclude from code generation (see [GlobalApiExclusions.txt](/eng/WpfArcadeSdk/tools/GenApi/GlobalApiExclusions.txt))
14
+
*`GlobalAttrExclusionsFile`
15
+
* A file that specifies Attributes to exclude from code generation (see [GlobalAttrExclusions.txt](/eng/WpfArcadeSdk/tools/GenApi/GlobalAttrExclusions.txt))
16
+
*`GenAPIAdditionalParameters`
17
+
* Parameters to GenAPI built up from local configuration
18
+
*_GenerateReferenceAssemblySource
19
+
* A private parameter used to enable GenAPI targets
Contains targets and properties related to GenAPI runs
22
+
*`GenAPITargetDir`
23
+
* The directory where GenAPI will generate code
24
+
*`GenAPITargetPath`
25
+
* The full path to the file GenAPI will generate
26
+
*`EnsureGenAPITargetDirectory`
27
+
* Creates the directory specified by `GenAPITargetDir` if it does not exist
28
+
## Using GenAPI in WPF
29
+
GenAPI is run only on-demand. In the event that a change to a runtime assembly creates new public surface area, a developer will see an [ApiCompat](api-compat.md) error between the reference assembly and the runtime assembly. In order to address this, the developer must run GenAPI to generate new reference assembly code.
30
+
### Running GenAPI
31
+
GenAPI can be run by setting the following MSBuild property while building.
32
+
```
33
+
/p:GenerateReferenceAssemblySource=true
34
+
```
35
+
When a build is run with that property enabled, GenAPI will read the runtime assembly and generate a new `{AssemblyName}.cs` file under the ref directory in the assembly's source tree.
36
+
37
+
This new file will contain the newly created surface area and will need to be checked in along with the runtime assembly change. The next build without `GenerateReferenceAssemblySource` enabled will no longer display an ApiCompat error as the surface area will now match the baseline.
38
+
### Issues with GenAPI
39
+
Often, GenAPI will generate code output that will contain code that is either private, internal, or creates build errors. For this reason a developer usually cannot just use the output of GenAPI directly. Instead, the developer should do the following:
40
+
* Build with GenAPI enabled
41
+
* Diff the output file against the previous version
42
+
* Extract just the new surface area (and related code) from the generated code
43
+
* Revert the generated file
44
+
* Add back the new surface area to the reference assembly code
45
+
* Ensure that nothing in the new surface area is private or internal unless requried by XAML compilation or other reference assemblies
46
+
* Rebuild without GenAPI enabled and verify there are no ApiCompat errors
0 commit comments