Creating a Configuration UI Project
This topic will walk you through creating a configuration UI project for a build component or
plug-in. This allows you to configure the component or plug-in interactively from within the standalone GUI or
Visual Studio. The configuration editor is placed in a separate assembly from the component or plug-in as the
editors are specific to the Windows platform. This allows the components to remain platform-neutral and usable
with either MSBuild or dotnet build.
This section describes how to create and configure the build process plug-in project. It will
describe the process for a C# project but the steps should be fairly similar for a VB.NET project with a few
differences in the configuration option titles.
In Visual Studio, select the New Project option. In the New Project
dialog box, select the C# or VB.NET language, and then select the Documentation subcategory. Select
the Build Component/Plug-In Configuration Editor template, give it a name and click OK to
create it. Once it has been created, right click on the project and select Properties.
In the Application tab, set the assembly name and default namespace as you see
fit.
By default, the Debug project properties are set to use the standalone GUI for debugging
which will help you see if the component can be located, that the configuration form is working if you created
one for the component, and that it is working within the build as expected.
Using the standalone GUI as the host is easier than using Visual Studio as the package
locks the assemblies once the help file builder project has loaded them for use and you will not be able to
rebuild them. Shutting down the standalone GUI frees the assemblies so that you can rebuild them and start a
new debugging session.
In the help file builder project that you use to test your plug-in, set the project's
Component Path property to the folder containing your build component's assembly. If
you have opened the project's Components property page before setting the component path, you may need
to close and reopen the project in order for it to discover your build component assembly.
Optionally, select the Signing tab and check the "Sign the assembly" checkbox.
Select "<New...>" from the "Choose a strong name key file" dropdown, enter a filename, and click OK to
create the key file. You can protect the key file with a password if you like or uncheck the option to create
one without a password.
The template project comes with an example Windows Forms form and a WPF form. Select the one you
want to use based on your preference and delete the other. Open the code for the form and search for
TODO comments to find sections that need to be updated.
Unlike a build component or plug-in, this assembly will not be distributed as a NuGet package.
Instead, it will be added as a package item in the build component or plug-in project. That way, it is
distributed with the component or plug-in but does not have to be added to the help file builder project
separately. See the TODO comments within the sample editor forms for instructions on
how to do this. The same instructions can be found in comments within the build component and plug-in project
files as well.
The key to making this work is the MEF editor factory class found within the editor form. Within
the sample editor form, you will find two factory classes: one for a plug-in and one for a build component. Keep
the appropriate one based on what you are creating and delete the other. Specify your component or plug-in's ID
as the parameter passed to the export attribute on the factory class. The ID must match that of the related
component or plug-in for it to be matched properly within the IDE for editing.
Add controls to the form and implement the code in the constructor and save button event handler to
finish the form.
