Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
VS2022 and .NET Core Build Support (#874)
* Major overhaul to support both .NET Framework and .NET Core builds Significant breaking changes were made to support both .NET Framework (MSBuild.exe) and .NET Core (dotnet.exe) builds. - Updated all but the VSIX package and MPF projects to the new SDK project format. - Made updates throughout the code base to fix code analysis issues and to use current language syntax features. - Consolidated the SHFB and Sandcastle tools projects into a single solution file. The VSIX package still has its own solution file for now. - Consolidated the code into common namespaces and merged the SHFB build components into the main build components project. - Updated all tool projects to target .NET 4.7.2 and .NETCoreApp 3.1. The latter allows for builds using the dotnet.exe tool. The core libraries, build components, plug-ins, and presentation styles target .NETStandard 2.0 so that they are universal. - Restructured the tools folders to allow for the tool version and platform-specific code to be cleanly separated. - Separated Windows platform-specific code out into separate assemblies. The Sandcastle.Platform.Windows assembly contains the shared code. Reworked all build components and plug-ins to separate the configuration UIs into separate Windows platform-specific assemblies. This allows the components themselves to be used with both .NET Framework and .NET Core builds while allowing the IDEs to still configure them interactively. - All build tasks were moved from SandcastleBuilder.Utils to their own assembly (SandcastleBuilder.MSBuild). - The AddNamespaceGroups tool was removed. The code was merged into the build engine under a new build step (BuildStep.AddNamespaceGroups). - The standalone VersionBuilder tool was removed and the code from it was merged into the related plug-in were it runs directly now at build time. - The XslTransform tool and the related production XSL transformations were removed. The XSL transformation code was moved into the build engine in three new build steps. BuildStep.ApplyDocumentModel handles the ApplyVsDocModel.xsl code, BuildStep.AddApiTopicFilenames handles the AddFilenames.xsl code, and BuildStep.GenerateApiTopicManifest handles the ReflectionToManifest.xsl code. Along with BuildStep.AddNamespaceGroups, these new build steps replace BuildStep.TransformReflectionInfo which was removed. The code in CreateVSToc.xsl is handled by new code in the build engine that runs under the existing build step BuildStep.GenerateIntermediateTableOfContents. These changes should allow for better extensibility of the related build steps in the future. - Updated all presentation styles to use the code-based interfaces for applying the document model to the reflection information file and generating the intermediate table of contents. These replace the old properties that specified the related XSL transformations to use. Custom presentation styles are free to use the default implementations or supply their own. It is also now possible for plug-ins to replace them at runtime as long as the replacements meet the requirements of the presentation style. - Removed the GenerateHelpFormatTableOfContents and GenerateHelpFileIndex build steps as they effectively did nothing anymore. - Removed the BuildAssembler build components DisplayComponent, InheritDocumentationComponent, PlatformsComponent, SnippetComponent, TaskGrabberComponent, and ValidateComponent as they were never used. - The AjaxDoc plug-in has been deprecated. AjaxDoc itself has been deprecated in favor of JSDoc. The plug-in is also dependent on Windows platform-specific features and cannot be used with .NET Core builds. - All build component and plug-in configuration forms were updated to use WPF for better high DPI scaling support on 4K displays (#344). The standalone GUI hosts all of the WPF controls and UI forms but is a Windows Forms application at its core. That probably won't change anytime soon. New folder structure under SHFBROOT: - The root folder only contains the Sandcastle Help File Builder MSBuild targets file. - Components - Contains build components, plug-ins, and presentation style related files. - Data - Contains the framework reflection information files. - Extras - Contains optional tools that are not part of Sandcastle or SHFB such as the HTML to MAML converter and the web project code providers. - Help - Contains the Help 1 (CHM) help files. - net472 - Contains the .NET Framework build tools for MSBuild.exe. - netcoreapp3.1 - Contains the .NET Core build tools for dotnet.exe. - Schemas - Contains the XML schemas for the reflection data file and the MAML topic files. - Snippets - Contains Visual Studio snippet files used to insert common block and inline MAML elements. - Templates - Contains template project files used by the build tools. - Tools - Contains the Windows platform specific tools (reflection data manager, standalone GUI, SHFB project launcher, and help library manager launcher). Current Known Issues and Limitations - The Visual Studio project templates for components, plug-ins, and presentation styles need updating to match the new format that separates the platform-specific UI configuration code into its own assembly. For now, they will not work at all if you create new projects from them. You will need to manually fix them to separate the UI code and use the new structure. Any existing build components, plug-ins, and presentation styles will also need updating to work with the new system. Information on porting them will be provided at a later date. - The XSL transform in the Completion Notification plug-in currently fails on .NET Core probably because script code is not supported. - Data caches built using the .NET Framework ESent and SQL cached data components cannot be used by the .NET Core versions of the same components and vice versa due to differences in the serialized framework types. May need to introduce separate caches based on the build type. - The ESent cached data components are not currently working under .NET Core due to some non-serializable types. - The SQL cached data components are not currently working under .NET Core due to System.Data.SqlClient not being supported. It probably needs to be switched to Microsoft.Data.SqlClient. - The help file is now out of date with regard to all of the above changes. It will be updated at a later date to reflect the new functionality. * Template project updates and NuGet support - Updated all template projects so that they work with the updated build engine. - Updated all template projects so that they use the new SDK format and generate their output as NuGet packages. This makes them easier to find and use and no longer requires a common component path setting be used in the help file builder projects to locate them. - Updated the standalone GUI and Visual Studio package to support adding package references to help file builder projects for build components, plug-ins, presentation styles, and syntax generators interactively with a search dialog box . The component packages are shown in a separate node in the project/solution explorer tool window. - Updated the build engine to search for build components, plug-ins, presentation styles, and syntax generators added to the project as NuGet packages by looking for their SHFBComponentPath items. * Minor update Minor update to package code to use more up to date APIs for main window handle and solution events. * Minor updates to prepare for VS2022 support * Changes to prepare for VS2022 support * VS2022 support MPF project refactoring - Moved the common MPF project code into a shared project. - Added MPFProj_VS2022. * VS2022 support VSIX project refactory - Moved the common VSIX project code into a shared project. - Added the SandcastleBuilderPackage_VS2022 project. * Installer updates - Updated the VSIX package to install the MAML schemas. - Updated the guided installer to support the VS2022 package and VSIX MAML schemas. - Added the HTML Help Workshop installer to the project for use by the guided installer as the official download seems to be permanently broken. * Updates and fixes for test deployment * Doc updates and minor fixes for issues found during testing * Template project fixes - Reworked how the project and project item template files are included in the package projects so that the VS2022 project can used linked items. - Added a hack so that the root container added to the Add New Item dialog in VS2019 and VS2022 shows "Documentation" rather than "Token File". - VS2022 is doing something odd with selected item icons. As such, I modified the folder icons shown in the Solution Explorer so that they look a little better in VS2022 when selected in the Dark and Light themes. - Fixed some spelling errors in the MAML schemas. * Documentation updates * Minor fixes and new visibility option and transform option - Added a new visibility option to exclude internal members in other assemblies and private members of base types. - Fixed F# parameter with a single quote causing BuildAssembler to crash. - Fixed sitemap API content placement not working. - Added a new logoUrl transform argument property to the VS2010 and VS2013 presentation styles. This allows you to specify a URL to navigate to when the logo is clicked. * Documentation updates * Documentation updates
- Loading branch information
1 parent
84082c3
commit 64ecc94