This project has moved and is read-only. For the latest updates, please go here.

SHFB plugin and sandcastle.config

Topics: Developer Forum, User Forum
Oct 9, 2007 at 9:52 AM
I'm working on Sandcastle component called "MetaAttributeComponent" which adds custom configured meta attributes like "DocSet" into help document header. This component is independent on SHFB itself, but I decided to create SHFB plugin for easier component configuration.

My component requires some additional configuration (meta attributes definitions) stored in sandcastle.config file

I have small problem, how to correctly place component configuration in sandcastle.config file at runtime (my plugin execution point is defined as ExecutionPoint(BuildStep.CreateConfig, ExecutionBehavior.After)).

At present I have workaround - I insert component configuration before last component (SaveComponent).

I have solution also :-)
It could be useful decorate each component element in config file with unique id (name) attribute. These id (names) should be accesible as constants in SHFB API. After that plugin developers can easily find concrete component configuration
Oct 9, 2007 at 4:16 PM
Since you are trying to insert something into sandcastle.config and are using a component, you are better off doing this entirely as a build component rather than a plug-in and a component. You can give instructions on how to paste your default XML config into the configuration files. You can implement the static ConfigureComponent method to allow configuration from within the help file builder. As long as the component has an ID on its configuration section and that method is implemented it will be configurable from the ComponentConfigurations property. See the article at for details.

Oct 10, 2007 at 9:52 AM
Hello Eric, thanks for direct me :-) Personally a think this solution has a few issuses

1] As I said, I would like to keep my component independent on SHFB (it could be used in other projects also). So any static method for configuration purposes is unacceptable for me. I would like configure my component(s) through additional layer (like SHFB plugin)

2] I planning installation for my component and plugin as simple as possible (with MSI installer for example), so additional modification of template files (three or more) do not sounds good.

3] I think build components configuration should be similar as plugin configuration (users should configure them at the same place) with these exceptions/enhacements:
- build component must have unique id
- build component can depend on other build component (it should be possible define/check build component order), for example build component plugin should returns collection of component ids, which are required to be defined before component self.
- i think build component plugins should be executed only at BuildStep.CreateConfig step

with regards
Martin D.
Oct 10, 2007 at 8:30 PM
I can't see how creating a plug-in is going to keep your component independent of SHFB as nothing else can use the SHFB plug-ins. The static method is there for SHFB to use but doesn't prevent the component from being used elsewhere. For standalone build scripts etc. people are going to have to edit the config file manually anyway.

I see your point about the template config file modifications so I will take a look at making integration of third party components easier in a future release. I think putting the component dependencies and other such definitions into an XML file sort of like a manifest would be sufficient to allow the configuration to be merged with the main config file without having to create a separate plug-in. I think that just makes it more complicated than it needs to be.