XML documentation from Dynamics AX to Word

Posted by on

It may also happen sometimes to you that you want to add a description of basic classes of some solution to a document. If you write XML documentation in code (and it’s a really big mistake if not), you have the description already done, you just need to get it into the target document. You have to manually go through the classes, copy documentation comments, remove “\\\”, line breaks, possibly formatting tags… – or to automate the whole thing.

That’s exactly what the script decribed below does. The result is a Word document with paragraphs and styles:

The first thing to do is to export the documentation to a file. Create an AOT project in Dynamics AX and add all relevant classes to it. Then right-click the project and choose Add-Ins > Extract XML documentation. A dialog window will open – tick Documentation checkbox, fill in the file name and confirm that by OK button.

Then it’s the time for the script which is – as usual – written in PowerShell. You can download it from here; I’m going through it and describing it in the rest of this post.

The script initially loads the XML file with the documentation (set the path to the file generated by Dynamics AX) and looks for information about classes. That’s a piece of cake thanks to XPath.

#Input file
[xml]$xml = (Get-Content ExportedDocumentation.xml)
#Extract nodes with types
$types = $xml.SelectNodes("doc/members/member[starts-with(@name,'T:')]")

Then an object with properties ClassName, Summary and Remarks is created for every class.

#Fill texts to object properties
$doc = $types | % {New-Object PSObject -Property @{
    ClassName = ($_.name).SubString(2) #Omit "T:"
    Summary = ExtractText $_.summary
    Remarks = ExtractText $_.remarks}}

ExtractText() function selects a text from an XML and adjust it a little.

Function ExtractText($node)
{
    if ($node -is [System.Xml.XMLElement])
    {
        [string]$text = $node.InnerXml
    }
    else
    {
        [string]$text = $node
    }
    if ($text)
    {
        #Remove <c> and </c> tags
        $text = [Regex]::Replace($text, '</?c>', '')
        #Extract type name from <see cref=...> tag
        $text = [Regex]::Replace($text, '<see[ \n]*cref="[TM]:(?<ref>[a-zA-Z0-9_]*)"[ \n]*/>', '${ref}')
        #Remove line breaks and suppress repeated whitespaces
        $text = [Regex]::Replace($text, '[\n ]+', ' ')
        $text = $text.Trim()
    }
    return $text
}

The last part of the script takes the obtained data and creates a Word document. Adjust styles and everything else according to your actual needs.

#Create Word document
$word = New-Object -ComObject Word.Application
$word.Visible = $true
$range = $word.Documents.Add().Range()
 
foreach ($item in $doc)
{
    #Class name
    $range.Text = "Class $($item.ClassName)"
    $range.Style = "Heading 3"
    $range.InsertParagraphAfter()
    $range.SetRange($range.End, $range.End)
 
    if ($item.Summary)
    {
        #Summary
        $range.Text = $item.Summary
        $range.Style = "Normal"
        $range.InsertParagraphAfter()
        $range.SetRange($range.End, $range.End)
    }
 
    if ($item.Remarks)
    {
        #Remarks (title)
        $range.Text = "Remarks:"
        $range.Style = "Normal"
        $range.InsertParagraphAfter()
        $range.SetRange($range.End, $range.End)
 
        #Remarks (text)
        $range.Text = $item.Remarks
        $range.Style = "Emphasis"
        $range.InsertParagraphAfter()
        $range.SetRange($range.End, $range.End)
    }
}

Links:
Script to download
MSDN: XML Documentation [AX 2012]

3 Comments

    • Oh d’oh I didn’t see link at the very bottom, only the in-line “here” link. It worked great for me, I just changed the “T:” to “M:” or whatever to get different objects. Very clever.

Comments are closed.