Visio PowerShell 4.7.0

Headline change: typed setters on CustomPropertyCells / UserDefinedCellCells plus a friendly diagnostic on bad formulas, closing the long-running thread that started with #117. Plus an audit-pass making Get-* cmdlets' positional bindings consistent across the module.

Added

• Typed setters on CustomPropertyCells and UserDefinedCellCells for setting cell values without having to think about Visio's formula encoding. Each setter writes a correctly-encoded Visio formula and (where applicable) sets the Type cell to match. From PowerShell:

  $cp = New-Object VisioAutomation.Shapes.CustomPropertyCells
  $cp.SetString("hello")        # Type=0 (String)
  $cp.SetNumber(42)             # Type=2 (Number)
  $cp.SetBool($true)            # Type=3 (Boolean)
  $cp.SetDate([datetime]::Now)  # Type=5 (Date)
  $cp.SetFormula("=...")        # raw escape hatch

  UserDefinedCellCells exposes SetString and SetFormula. The setters become the recommended replacement for raw $cells.Formula = ... assignment. Closes #144.

• Formula property on CustomPropertyCells and UserDefinedCellCells as the canonical name (renamed from Value to surface that the cell stores a Visio formula, not a literal value).

Deprecated

• CustomPropertyCells.Value and UserDefinedCellCells.Value are now [Obsolete] aliases for Formula. Existing PowerShell scripts that read or write $cells.Value keep working unchanged through the deprecation window. Migration: rename $cells.Value to $cells.Formula, or use the new typed setters. Part of #144.

Fixed

• Get-VisioShape now declares an explicit DefaultParameterSetName = "shapebyname". Previously a no-args Get-VisioShape call relied on PowerShell nondeterministically picking a parameter set; under stricter PowerShell configurations it could throw AmbiguousParameterSet. Closes #130.
• Get-VisioLockCells now calls WriteObject(dic) instead of WriteObject(dic, true), matching its sibling "Get a dictionary keyed by shape" cmdlets. Pure consistency fix; observable behavior is unchanged. Closes #129.

Changed

• Set-VisioCustomProperty with a manually-constructed CustomPropertyCells via -Cells now surfaces an ArgumentException with a self-explanatory message pointing at the new typed setters when the Formula field is set to a raw string. Previously this path raised an opaque COMException: #NAME? from the underlying COM call. The default Set-VisioCustomProperty -Value "x" flow is unaffected (the cmdlet pre-encodes internally). Part of #144.
• Get- cmdlet positional parameters — full audit pass.* Eleven Get-* cmdlets gain consistent positional bindings so the natural shorthand forms (Get-VisioPage "Page-1" $doc, Get-VisioCustomProperty $shape, etc.) work as users intuit. The convention adopted: cmdlets with both -Name and a single object context have -Name at position 0 and the object (-Document / -Page) at position 1; cmdlets with just an object context have it at position 0. Closes #143 (and supersedes the narrower #142).
• Get-VisioMaster — -Document parameter is now positional, so the natural form Get-VisioMaster "Group" $doc works as users intuit. Closes #142.

Install

Install-Module Visio

The module ships from the Visio package on the PowerShell Gallery. Bundled .NET DLLs include the underlying VisioAutomation library plus Microsoft.Msagl and GenTreeOps.

Related

• The bundled VisioAutomation NuGet is the underlying .NET library this module wraps.
• Project documentation — guides and per-cmdlet reference.
• Custom properties page — covers the new typed setters with a per-Type behavior matrix.
• Full changelog.