-
Notifications
You must be signed in to change notification settings - Fork 1.2k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Convert C# Reference Assembly Generation to Use GenAPI (#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.
- Loading branch information
Showing
77 changed files
with
33,163 additions
and
198 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,46 @@ | ||
| # GenApi Usage in WPF on .NET Core | ||
| 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. | ||
|
|
||
| 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. | ||
|
|
||
| Using GenAPI allows us to strip out internals, removing the dangling references from our reference assemblies. | ||
|
|
||
| ## [GenApi.props](/eng/WpfArcadeSdk/tools/GenApi.props) | ||
| Contains various properties related to GenAPI runs and configurations. | ||
| * `GenAPIEnabledProjects` | ||
| * The set of projects to run GenAPI on | ||
| * `GlobalApiExclusionsFile` | ||
| * A file that specifies API surface area to exclude from code generation (see [GlobalApiExclusions.txt](/eng/WpfArcadeSdk/tools/GenApi/GlobalApiExclusions.txt)) | ||
| * `GlobalAttrExclusionsFile` | ||
| * A file that specifies Attributes to exclude from code generation (see [GlobalAttrExclusions.txt](/eng/WpfArcadeSdk/tools/GenApi/GlobalAttrExclusions.txt)) | ||
| * `GenAPIAdditionalParameters` | ||
| * Parameters to GenAPI built up from local configuration | ||
| * _GenerateReferenceAssemblySource | ||
| * A private parameter used to enable GenAPI targets | ||
| ## [GenApi.targets](/eng/WpfArcadeSdk/tools/GenApi.targets) | ||
| Contains targets and properties related to GenAPI runs | ||
| * `GenAPITargetDir` | ||
| * The directory where GenAPI will generate code | ||
| * `GenAPITargetPath` | ||
| * The full path to the file GenAPI will generate | ||
| * `EnsureGenAPITargetDirectory` | ||
| * Creates the directory specified by `GenAPITargetDir` if it does not exist | ||
| ## Using GenAPI in WPF | ||
| 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. | ||
| ### Running GenAPI | ||
| GenAPI can be run by setting the following MSBuild property while building. | ||
| ``` | ||
| /p:GenerateReferenceAssemblySource=true | ||
| ``` | ||
| 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. | ||
|
|
||
| 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. | ||
| ### Issues with GenAPI | ||
| 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: | ||
| * Build with GenAPI enabled | ||
| * Diff the output file against the previous version | ||
| * Extract just the new surface area (and related code) from the generated code | ||
| * Revert the generated file | ||
| * Add back the new surface area to the reference assembly code | ||
| * Ensure that nothing in the new surface area is private or internal unless requried by XAML compilation or other reference assemblies | ||
| * Rebuild without GenAPI enabled and verify there are no ApiCompat errors |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.