This topic provides information on migrating build components, plug-ins, presentation styles, and syntax generators built against v2021.4.9.0 and earlier to the latest release that supports .NET Core and deploying the components as NuGet packages. Presentation styles also underwent a complete rewrite in version 2022.8.14.0. However, you may be able to replace your presentation style with simpler build components or plug-ins rather than reimplementing an entire presentation style.
Some quick updates can be made to get an existing component working with the new release without having to recreate the project with the restriction that they will only work with MSBuild. For .NET Core builds, the projects will need to be recreated as described in the sections below. Make the following changes as needed based on the project type:
Remove any references to Sandcastle.Core and SandcastleBuilder.Utils and replace them with NuGet package references to EWSoftware.Sandcastle.Core and/or EWSoftware.SandcastleBuilder.Utils as needed. Use the latest release available for each. Note that the version may not match the latest release of the help file builder as the package version for these only changes when there are breaking changes to the API.
For presentation styles, refer to the section below for additional changes that are required due to change in the API.
Remove the IsConfigurable property from the build component and plug-in export attributes.
If configurable, remove the ConfigureComponent method from build components and the ConfigurePlugIn method from plug-ins. Save the code though as you will need to move it to the configuration forms when you add a new MEF editor factory class below.
For plug-ins, change the type on the Initialize method's configuration parameter from XPathNavigator to XElement. It will be necessary to rework the initialization code to work with the new parameter type.
For configurable build components and plug-ins, add an editor factory class to the configuration editor form similar to the following examples. The first is for a plug-in, the second is for a build component.
Important
It is essential that the ID specified in the export attribute matches the ID on the component or plug-in's export attribute exactly. This is how the IDEs will match the editor component to the related build component or plug-in.
Also note that the EditConfiguration methods now return true if the configuration was edited or false if it was not rather than the new configuration. If changes are made to the configuration, they should be made directly to the passed in XML element.
using SandcastleBuilder.Utils;
using SandcastleBuilder.Utils.BuildComponent;
#region Plug-in configuration editor factory for MEF
//=====================================================================
/// <summary>
/// This allows editing of the plug-in configuration
/// </summary>
[PlugInConfigurationEditorExport("TODO: Put your plug-in ID here")]
public sealed class PlugInEditorFactory : IPlugInConfigurationEditor
{
/// <inheritdoc />
public bool EditConfiguration(SandcastleProject project, XElement configuration)
{
// TODO: Add code to invoke the editor dialog.
//using (var dlg = new WindowsFormsExampleConfigDlg(configuration))
//{
// return dlg.ShowDialog() == DialogResult.OK;
//}
}
}
#endregion
#region Build component configuration editor factory for MEF
//=====================================================================
/// <summary>
/// This allows editing of the build component configuration
/// </summary>
[ConfigurationEditorExport("TODO: Put your build component ID here")]
public sealed class BuildComponentEditorFactory : IConfigurationEditor
{
/// <inheritdoc />
public bool EditConfiguration(XElement configuration, CompositionContainer container)
{
// TODO: Add code to invoke the editor dialog.
//using (var dlg = new WindowsFormsExampleConfigDlg(configuration))
//{
// return dlg.ShowDialog() == DialogResult.OK;
//}
}
}
#endregionStarting with version v2024.2.18.0, all component projects use an SDK format project and contain the necessary properties to generate a NuGet package when built. This allows them to be shared publicly on NuGet.org or privately with a local repository. So that they are platform independent and work with both MSBuild and the dotnet tool, the projects target .NET Standard 2.0. Support for configuration has also been separated from the component assemblies. If your component supports configuration within the IDE, create a new project to host the configuration forms.
It is recommended that you create a new project and import your existing code into the new project rather than modifying the old project file. That way, all of the necessary NuGet properties and the build property file are present and ready to update. The following sections provide more information on changes that need to be made to the various component project types.
Important
If, after creating a project, you rename the assembly created by the project, be sure to rename the project's .props file found in the .\build folder to match the new assembly name. This is required so that the build properties can be found when added to a help file builder project using NuGet.
Create a new project and edit the properties on the project file's Package properties page that are used to generate the NuGet package for the component.
Import your component's code into the new project to replace the example component. Some of the attribute values in the AssemblyInfo.cs file can be put in the project's package properties instead (title, description, company).
In the MEF component factory class, remove the IsConfigurable property from the attribute metadata.
If the component is configurable, remove the ConfigureComponent method. To support configuration, you will need to create a new project using the Build Component/Plug-In Configuration Editor template project. See the Creating a Configuration UI Project topic for more information.
Create a new project and edit the properties on the project file's Package properties page that are used to generate the NuGet package for the plug-in.
Import your plug-in's code into the new project to replace the example plug-in. Some of the attribute values in the AssemblyInfo.cs file can be put in the project's package properties instead (title, description, company).
In the MEF component factory class, remove the IsConfigurable property from the attribute metadata.
If the component is configurable, remove the ConfigureComponent method. To support configuration, you will need to create a new project using the Build Component/Plug-In Configuration Editor template project. See the Creating a Configuration UI Project topic for more information.
In the plug-in's Initialize method, change the type on the configuration parameter from XPathNavigator to XElement. It will be necessary to rework the initialization code to work with the new parameter type.
Starting with version 2022.8.14.0, presentation styles are implemented using a code-based API rather than XSL transformations. This makes them much easier to extend and modify compared to prior releases. If you created your own presentation style in the past to make adjustments to how the topics were rendered or to add or remove handling for certain sections or elements, it is entirely likely that you will not need to create a whole new presentation style going forward. Instead, you should be able to implement just those parts that you need to modify using standard help file builder plug-ins to adjust how the topics are rendered with selected presentation style regardless of which one is selected. See the Creating a Presentation Style Component for more information.
A new project template and more information on creating a presentation style using the new API will be provided in a future release.
Create a new project and edit the properties on the project file's Package properties page that are used to generate the NuGet package for the syntax generator.
Import your syntax generator's code and other supporting files into the new project to replace the example syntax generator. Some of the attribute values in the AssemblyInfo.cs file can be put in the project's package properties instead (title, description, company).
Note that the syntax generator's IsConfigurable property is still supported and should be left alone if set as it is used by the syntax component's configuration dialog rather than a configuration form defined within this project.