NewDocumentFromTemplate: create the drawing from the template, reject stencils (#229)

[saveenr]

Summary

Fixes #229. Client.Document.NewDocumentFromTemplate (and so New-VisioDocument -Template and the directed graph XML <documentoptions template="..."/>) did not create the drawing from the template. It created a blank drawing and then opened the template as a separate docked stencil (AddEx with visAddStencil + visOpenDocked, flags copied from the 2012 NewStencil helper), which left an empty stencil open in Visio 2013 and later.

It now calls AddEx with no flags, so Visio creates the drawing from the template: its page setup, styles and settings apply, and the stencils in the template's workspace open and dock.

• null, empty or whitespace template: a blank drawing (as before for null).
• a stencil file (.vss / .vssx): ArgumentException ("... is a stencil, not a template ... use -Stencil") before anything is created. Before, it failed with an opaque COM error after leaving a blank drawing open.
• a template that does not exist: throws, with no stray blank drawing.

Evidence (live Visio 16, BASFLO_U.VSTX)

Call	Result
old: blank Add("") + AddEx(template, 0, 516, 0)	Blank 8.5 x 11 drawing with an empty Template, plus an empty "Stencil" document.
AddEx(template, 0, 0, 0) or Documents.Add(template)	Drawing whose Template is set, landscape 11 x 8.5, with BASFLO_U.vssx (15 masters) and XFUNC_U.vssx (7 masters) opened and docked.
AddEx(template, 0, 256, 0) (visAddNoWorkspace)	Drawing based on the template, no stencils opened.
AddEx("basflo_u.vssx", 0, 516, 0)	Throws. So no caller could have relied on "stencil as template".

Microsoft's Documents.AddEx documentation describes the template form the same way (and visAddStencil as "Adds a new stencil file"). I could not test Visio 2010 itself.

Behavior change

Anyone who passed a template used to get a blank drawing and now gets one based on the template, which is what the docs promised. Anyone who passed a stencil got an error and still does, but a clear one. No internal caller passes a template or a stencil (the developer commands pass null).

Testing

• 7 new tests; 4 of them failed against the old code (real template, empty/whitespace template, stencil file, missing template). They are in VTest.Scripting, VTest.Models (the XML template option now checks the drawing is based on the template) and VTest.PowerShell (New-VisioDocument -Template, and the stencil error).
• Debug build, local Visio: VTest.Models 104/104, VTest.Scripting 48/48, VTest.PowerShell 84/84 (VTest, 108 tests, not touched).

Also

• NuGet/CHANGELOG.md and VisioPowerShell/CHANGELOG.md [Unreleased]: Fixed entries. The caveat on the XML option's Added entry is removed.
• docs/TESTING.md, CLAUDE.md and the Models docs backlog entry updated.
• Companion docs PRs in saveenr/VisioAutomation_GitBook_Docs (XML format page) and saveenr/VisioPowerShellDocs (New-VisioDocument page).

Closes #229

🤖 Generated with Claude Code