Page 38 - MSDN Magazine, October 2019

C#
Accessing XML
Documentation
via Reflection
Zachary Patten
The .NET languages (C#, F# and Visual Basic) all support XML-formatted comments above types and members in source code. Aside from providing an easily intelligible standard for com- menting code, these formatted comments are heavily integrated into Visual Studio and other development environments. They appear in tooltips and autocomplete suggestions, and in views like the Object Browser.
Even with all the benefits XML documentation currently pro- vides, there’s still a lot of untapped potential. You could use XML documentation to track bugs. You could integrate it with code analyzers to provide better recommendations. You could use it to control continuous integration pipelines. You could add docu- mentation generation as a step in your automated pipeline so your public documentation is always up-to-date.
The main issue with using XML documentation for any of these purposes is that there are no methods in .NET to access it directly from code. However, with one loading function and a handful of extension methods, you can easily add the ability to access XML documentation via reflection.
The XML Documentation File
By default, the compiler won’t do anything with XML documenta- tion. You first have to enable the XML Documentation File option in Visual Studio, which is under the Build tab of a project’s settings. Once enabled, the XML documentation will be extracted and placed into the designated file each time the code is built.
It’s worth noting that the XML documentation settings are build-configuration-dependent. So you have to enable it on each build configuration you want it to run. Also, it’s a good idea to make the name of the output XML file the same as the output assembly (just with an .xml file extension).
Figure 1 The C# Source Code
namespace Example \{
/// <summary>XML Documentation on ExampleClass.</summary> public class ExampleClass
\{
/// <summary>XML Documentation on ExampleMethod1.</summary> public static void ExampleMethod1() \{ \}
/// <summary>XML Documentation on ExampleNestedGenericClass.</summary> /// <typeparam name="A">Generic type A.</typeparam>
/// <typeparam name="B">Generic type B.</typeparam>
/// <typeparam name="C">Generic type C.</typeparam>
public class ExampleNestedGenericClass<A, B, C> \{
/// <summary>XML Documentation on ExampleMethod2.</summary> /// <typeparam name="D">Generic type D.</typeparam>
/// <typeparam name="E">Generic type E.</typeparam>
/// <typeparam name="F">Generic type F.</typeparam>
/// <param name="a">Parameter a.</param> /// <param name="d">Parameter d.</param> /// <param name="b">Parameter b.</param> /// <param name="e">Parameter e.</param> /// <param name="c">Parameter c.</param> /// <param name="f">Parameter f.</param> public static void ExampleMethod2<D, E, F>(
A a, D d, B\[\] b, E\[\] e, C\[,,\] c, F\[,,\] f) \{ \} \}
\} \}
This article discusses:
• Reflection
• XML documentation
• Extension methods
• Regular expressions
• XML file parsing Technologies discussed: Visual Studio, C#/F#/Visual Basic
Code download available at:
github.com/ZacharyPatten/Towel
34 msdn magazine