The .Net Configuration Section Documentation Generator lets you generate schemas and documentation for configuration sections used in .Net’s configuration system (e.g.
web.config files), which are defined by a class that derives from the
The documentation generator is a command-line tool that operates in two modes. The reflect mode uses reflection to inspect the properties of a class that derives from the
ConfigurationSection class, and generates an XML schema file (XSD) for the section and all its child elements. The document mode generates an HTML documentation file based on a schema created with the reflect mode.
If you have any feedback, please leave a comment here.
To use the documentation generator in reflect mode, launch it with
ConfigurationDocumentationGenerator.exe reflect. The command line arguments specify the assembly file containing the configuration section, the type that defines the configuration section, the name of the root element for the section, and the output file name for the schema. If you invoke the reflect mode without arguments, a full overview of the possible command line arguments is given.
The reflect mode will load the specified assembly file, and search for the specified type inheriting from
ConfigurationSection. It will generate a schema and save it in the specified output file. If the output file already exists, the existing schema will be updated, leaving any annotations already added intact.
Reflection generates a schema as follows:
ConfigurationElementtype found by recursively searching the configuration properties (and including the
ConfigurationSectionitself) it will create an
:complexTypeelement to describe the configuration element.
:elementin the complex type if the property’s type derives from
ConfigurationElement, or an
xs:attributeif it does not. These elements are grouped using
ConfigurationElementCollection, it will add child
:elements for the add, remove and clear elements (or only add if the collection type is a basic map). These are grouped using
:simpleTypeis created for them. For enumerations, this is populated with a suitable restriction based on the enumeration’s values. Otherwise, the simple type is left empty so you can manually define it.
The reflect mode has the following limitations:
ConfigurationSectionitself is not specified in code, it must be manually specified when invoking the documentation generator.
ConfigurationElementCollectionit is required to apply a
ConfigurationCollectionAttributeto indicate the item type, collection type (basic map or add/remove/clear map), and the names of the add, remove and clear elements. In the case of a basic map, you must also specify the element name using the
="unbounded". This is not correct, because it means the schema will allow all elements to be repeated many times, while in fact the configuration section will not load if they occur more than once. Unfortunately, it is not possible to accurately specify the real schema using XSD 1.0 in this case.
To use the documentation generator in document mode, invoke it using
ConfigurationDocumentationGenerator.exe document. It takes arguments to specify the XSD file and optionally the output file and XSL transform to use. Invoke it without arguments to view a description of all the arguments.
The document mode will read the XSD file, and run the indicated XSL transform to generate an output HTML file. In this mode the documentation generator is basically just an XSLT processor, and is therefore not limited to XSD schemas generated by the reflect mode. However, the included Default.xslt transform is geared towards schemas generated by the reflect mode, and does not support all XSD features. It is possible to customize the Default.xslt file, or specify a custom XSL transform.
The default XSL transform will create a section for every element in the file that can be reached from the top-level
:element tag. Note it creates a section for every element, even if multiple elements use the same complex type. These sections list the syntax, attributes and child elements of the elements.
In addition, the default transform also adds a section for every top-level simple type in the file. For enumerations, the possible values are listed.
In order to add documentation to an XSD file, add
xs:documentation elements to it. The content of these elements will be included in the HTML documentation by the default XSL transform. You can add documentation to
xs:enumeration elements. When updating a schema with the reflect command later, these annotation elements will not be removed. The documentation may contain HTML elements in the XHTML namespace.
You can use a few attributes specified to the documentation generator in your schema. These attributes are in the
="http://www.ookii.org/documentation" namespace. Apply the
:title attribute to the
xs:schema element to specify the title of the documentation file. Use the
doc:refName attributes on an
xs:element to have the documentation for that element link to another element, rather than actually outputting the documentation for that element. This is useful if the element uses the same complex type as another element and you want to avoid repeating the same documentation. The doc:ref attribute should use the full path to the element, with element names separated by underscores, while the doc:refName attribute specifies the link text. For example, to link to the documentation of
someElement which is a child of
If the XSD contains a cycle (a complex type has a descendent element whose type is that same complex type; this can happen in a configuration section if it has a configuration element with a descendent property of that same type), this is detected by the default XSL transform, but all it does is output a warning message in the HTML and prevent infinite recursion from crashing the documentation generator. To handle cycles, have the descendent element use
doc:refName to refer back to its ancestor of the same type. This stops recursion and avoids the warning message.
You can customize the simple type mapping for the reflect mode, and the XSL transform for the document mode.
How the reflect mode maps a CLR type to an XSD simple type is defined in the ConfigurationDocumentationGenerator.exe.config file. The schema for this configuration is explained in the documentation generator configuration documentation.
You can customize the XSL transform by editing the Default.xslt file, or by specifying an alternative XSLT file on the command line. It’s usually recommended to make a copy of the Default.xslt file if you want to customize it. For example, you can tweak the generated HTML or the included CSS to alter the appearance of the documentation.