Ok…I think this is the last of the “how to perform primitive operations in Visio” articles that I’m going to do.  Hope you’ve been enjoying them.  If you haven’t been keeping up, you can find them all here.

In this installment, I’m going to show you how to create a container in Visio.  Containers are really useful, because when you move them, you move the contents as well.  Along with connections, containers are probably the most important feature of Visio (at least for me).

Container Basics

The first thing to know is that containers are special kinds of shapes, just like the ones we used when we were dropping shapes on the page.  So if you have containers in a stencil you’re using, then you can use those.  If you don’t have any special containers you can use the built-in container stencil that you see in Visio when you go to insert a container from the ribbon:

To use the built-in stencil, though, you have to know where to find it. Fortunately, you can ask Visio where to find it. If you have a reference to Visio in a variable (we’ve been using $Visio), you do it something like this:

$stencilPath=$Visio.GetBuiltInStencilFile(2,0)

The 2 represents the constant visBuiltinStencilContainers, and 0 is visMSDefault, meaning to use the default measurement units. If you’ve been reading along, you have already seen a bunch of constants. There are tons more, and I’ll let you in on how I’m making them a bit easier to deal with in the next post.

Once we have that stencil path, we can use the OpenEx method on the Documents collection to open the stencil (hidden, of course):

$stencil=$Visio.Documents.OpenEx($stencilPath,64)

That stencil has a bunch of masters on it:

There are a couple of approaches to adding a container to a document:

1. Drop the container as a shape, and then add shapes to it.
2. Drop the container as a container, listing the shapes that are in it.

Dropping containers as shapes

For the first option, you already know how to add a shape to a page using the Drop() method.

$page=$Visio.ActivePage
$container=$page.Drop($master,5,5)

After you do that, you use the ContainerProperties property of the container (which is a special property other shapes don’t have), calling the AddMember() method to add shapes. You can also add Selection objects, but we haven’t talked about those.

Let’s draw a rectangle on the page (it’s quicker to show than a custom shape, but it works the same):

 $rec=$page.DrawRectangle(2,3,5,6)
 $container.ContainerProperties.AddMember($rec,1)

And we can see that the rectangle is inside the container. We passed a 1 to tell the container to resize to fit the shape we put in it. If you don’t do that, you will probably have shapes hanging over the edges of the container.

If you have more shapes you want in the container, you can add them as well by calling AddMember. Not very tricky.

The problem I have with this approach is that you have to know where to drop the container in the first place. Not a huge deal, but the less I have to know the better.

Dropping Containers around shapes

To use the second approach, you need to start by dropping the shapes that you want inside the container onto the page. Again, I’ll just drop a rectangle, but the idea is the same with any shapes. Once I’ve got the shape, I use the DropContainer method on the page to drop the new master shape (of the container) and tell it the shape I want it to contain.

 $rec=$page.DrawRectangle(2,3,5,6)
 $container=$page.DropContainer($master,$rec)

If you compare the output of the two approaches, you’ll see that the second give a “tighter” container, that is, since we didn’t tell Visio where to place the container, it calculated exactly how big it needed to be and where to put it.

Adding More Shapes

 
Now that you have a container you can loop through other shapes that need to be in it and use the ContainerProperties.AddMember method to add all of them (in a loop!). No need to bore you with the details. You’re sharp and can figure that out.

Let me know what you think

–Mike

P.S. If you want to add all of the shapes at once (with either method) you can use a Selection object. They’re not hard to use, but I wanted to keep this post focused on containers.

It’s been a while since the last post.  I decided that if I had to chose between writing PowerShell and writing about PowerShell, I should favor the former.

In this episode, I’ll talk about how to create connections between objects in a Visio diagram.  Turns out it’s not really that hard (just like most things with Visio so far), but there some interesting things we can do with the connections once they exist.

So, to start with, let’s get a some shapes on a page.  If this doesn’t look familiar, refer back to the earlier posts in this series here:

$visio=New-Object -ComObject Visio.Application
$Document=$Visio.Documents.Add('')
$rect1=$Visio.ActivePage.DrawRectangle(1,1,2,2)
$rect2=$Visio.ActivePage.DrawRectangle(4,4,5,5)

Here’s what that got us:

Now, we have 2 shapes ($rect1 and $rect2). To connect them, we’ll use the AutoConnect() method on one of the 2 shapes. Since Visio connectors are directional (that is, they have a start and an end), it matters which one we use.

$rect1.AutoConnect($rect2,0)

The AutoConnect() method takes three arguments:

1. The shape you want to connect to
2. The direction (relative to the first shape) you want to move the connected shape to (0 means don’t move the second shape)
3. The shape you want to use as a connector

In this example, we chose to not move the second shape, and used the default connector.

The result looks like this:

There are several interesting things about this connector:

1. It doesn’t indicate direction (you can’t tell which way the connector goes)
2. It’s dynamic (it will move/route as you move the two shapes)
3. We didn’t get a reference to it as a result of the AutoConnect() method

We’ll start by addressing the last point. Since we didn’t get a reference to the connector, how can we find it? It turns out that just about everything in Visio is a shape, so we can look at the Shapes collection on the page:

$Visio.ActivePage.Shapes | Select-Object Name

In the output, you will see (at the end) a shape called “Dynamic connector”. That’s our new connector (duh).

$connector = $Visio.ActivePage.Shapes['Dynamic connector'] | select -Last 1

I picked the last one in the collection in case there were others. Visio adds to this collection as shapes are added to the list, so this should be safe.

Now that we’ve got a reference to the connector, how can we designate which end is which? In the Visio GUI, we would click the Line drop-down on the ribbon and select the arrows (or dots) that we wanted. In PowerShell, it’s a different story altogether.

First of all, there’s not an Arrows property that we can use. That would be too easy. It turns out that in Visio, everything has what’s called a ShapeSheet, which is kind of like a bunch of little spreadsheets that control every aspect of how the object behaves in Visio. Accessing cells in the ShapeSheet can be done several ways, but typically you either use the Section, Row, Column reference (SRC) or a special Named Cell. These references look something like this:

$Shape.CellsSRC($section,$row,$column) 

and

$Shape.Cells('CellName')

To set the ending arrow for a connector, there’s a “named cell” called EndArrow which tells Visio what symbol to draw at the end of the connector. We’re going to set the cell to 4. The number can apparently be anywhere from 1-45 to display different arrows.

$connector.Cells('EndArrow')=4

And the resulting arrow (zoomed in so you can see it):

If we wanted the arrow to be bi-directional, we could also set the “BeginArrow” cell.

$connector.Cells('BeginArrow')=4

Ok. Now for #2. Can we change how the connector routes? I often like to use straight lines because they’re easier to follow. Change the connector to be straight, we have to resort to the ShapeSheet again. However, there’s no named cell this time (see P.S…I found names). Now, we have to know the SRC to where the cell is. In fact, for this there are 2 cells that we have to set, so we need to know both SRCs.

 $connector.CellsSRC(1,23,10) = 16
 $connector.CellsSRC(1,23,19) = 1 

That’s pretty cryptic, right? Absolutely. It turns out with Visio, there are about 40 bajillion different constants to use. This link will help you with some, but they aren’t organized much. This page is organized a little better, but it’s still hard to know where to look. The constants in this example are:

• visSectionObject = 1
• visRowShapeLayout = 23
• visSLORouteStyle = 10
• visLORouteCenterToCenter = 16
• visSLOLineRouteExt = 19
• visLORouteExtStraight = 1

So that’s a mess (at least to me). How in the world do we figure these out? The easiest way is to record a macro and do what you want to find out about, then look at the VBA. The VBA code for setting a connector to a straight line looks like this:

Application.ActiveWindow.Page.Shapes.ItemFromID(3).CellsSRC(visSectionObject, visRowShapeLayout, visSLOLineRouteExt).FormulaU = "1"
Application.ActiveWindow.Page.Shapes.ItemFromID(3).CellsSRC(visSectionObject, visRowShapeLayout, visSLORouteStyle).FormulaU = "16"

That, with some googling, can get you what you need. I’m working on a better solution, but it’s not ready quite yet. 🙂

That’s enough about connectors.

Let me know what you think in the comments (or on Twitter)

Mike
@MikeShepard70

P.S. Found the “named cells” for making straight lines: ShapeRouteStyle and ConLineRouteExt.

Why mess with Visio from PowerShell?

I’ve got a couple of posts with some really basic code to access things in PowerShell and it occurred to me…I probably haven’t made it clear why you might want to do this (other than that you can).

So, instead of moving on to connections (which will be next, followed by containers), I thought I’d take a break and show you a really quick and practical script.

The Scenario

Imagine that you just got handed a network diagram of a bunch (dozens?) of servers that you manage.  The only problem is, the diagram only includes the server name.  Your boss needs it to include the IP Addresses for each item.  You have a choice.  You can either manually look up each name with Resolve-DNSName and copy-and-paste the IP Address into the diagram, or you can use PowerShell to solve the problem.

Here’s the script.  The funny part (to me, at least) is that the complexity is trying to get the IPV4 address out of Resolve-DNSName, the Visio part is simple.

$Visio = New-Object -ComObject Visio.Application
$Doc=$Visio.Documents.Open('c:\temp\ServerDiagram.vsdx')
$Page=$Visio.ActivePage

foreach($shape in $page.Shapes){
    if(!$shape.Text.Contains("`n")){
        $address=Resolve-DnsName $shape.text 
        $address=$address| where-object {$_.IP4Address } | select-object -First 1
        $newLabel="{0}`n{1}" -f $shape.text,$address.IP4Address
        $Shape.Text=$newLabel
    }
}

All it does is look for shapes on the page that don’t contain newlines, and update those shapes with the IP Address it wrestles out of Resolve-DNSName.

Here’s “before”

And “after”

I think you can see that something like this is a handy tool to have in your back pocket. I know that when I draw server diagrams I don’t label the IP Addresses manually anymore. This script (or one just like it) has saved me hours.

And that, my friend, is what PowerShell is all about.

–Mike

This is part 3…if you haven’t read part 1 or part 2 you probably want to go back and read those.

Now that we’re all up to speed, I promised I’d talk about drawing shapes in Visio.

We’ll start with an easy one.

Drawing Circles and Rectangles

Remember that you have to open Visio with PowerShell in order to access it from a script.

$Visio= New-Object -ComObject Visio.Application

We can open a new (blank) document using the same technique we saw last time to open a document, except we will pass an empty string:

$Doc=$Visio.Documents.Add('')

Now, we can get a reference to the active (only) page in the document by accessing the ActivePage property of $Visio.  We could also have looked at the Pages collection on $Doc and referenced it either by ID (1) or name (Page-1)

$Page=$Visio.ActivePage
#Or
#$Page=$Doc.Pages(1)
#$Page=$Doc.Pages('Page-1')

Now that we’ve got a page, let’s see what Draw methods we have:

$Page | get-member Draw*

DrawOval and DrawRectangle sound pretty straightforward.  Let’s try them:

$Page.DrawRectangle(1,1,5,5)
$Page.DrawOval(6,6,8,8)

Here’s what it looks like in Visio (note that my diagrams are using US measurements, so the numbers correspond to inches):

The functions also returned the objects that were drawn to the console (which we could have saved in variables if we were paying attention).

Drawing Shapes

Notice that there weren’t any methods for drawing shapes, which is what you really want to do in Visio. Shapes in Visio are stored in what Visio calls stencils, and are typically separate files. To open a stencil and not show it in Visio you can use the OpenEx method of the application object (which we are calling $Visio) and pass the filename and the constant 64 (which means “open hidden”). Here, I’m opening a stencil which contains a bunch of shapes for different kinds of servers. The _U at the end of the filename means that it uses US measurements rather than metric.

$stencilPath='C:\Program Files (x86)\Microsoft Office\Office15\Visio Content\1033\SERVER_U.VSSX'
$stencil=$Visio.Documents.OpenEx($stencilPath,64)

I’ve stored the loaded stencil in a variable because we want to work with it.

The shapes in the stencil are stored in a collection called Masters.

Let’s put an FTP Server somewhere on the page:

$Master=$stencil.Masters('FTP Server')
$Page.Drop($Master,4,4)

And here’s the output:

That’s enough for today. Next time we’ll think about connecting objects together.

Let me know what you think in the comments!

–Mike

Last time I talked about Visio and PowerShell and told you (in broad strokes) what I wanted to get done.  Now we’ll actually get started!

Starting Visio from PowerShell

To open the Visio application from PowerShell in order to start manipulating it, you need to use the appropriate COM class.  The code looks like this:

New-Object -ComObject Visio.Application

The New-Object cmdlet returns a reference to the new instance of Visio that’s running.  If you ran that line by itself, you’d see a bunch of properties of the new Visio.Application object and you’d see that Visio started, but without putting the object in a variable you’d be kind of stuck.  So…

$Visio=New-Object -ComObject Visio.Application

Now, we can use that reference to do fun stuff.

Opening a Visio Document

To open an existing document, use the Add method of the Documents property (a collection) of the $Visio object.  Just like the last time, this outputs an object that we’ll want to capture.  For example, opening the Visio diagram stored in c:\temp\SampleVisio.vsdx you’d do this:

$doc=$Visio.Documents.Add(‘c:\temp\SampleVisio.vsdx’)

Documents are made of pages:

$doc.Pages | select-object –property Name

This document only has one page, named (by default) ‘Page-1’.  We can either refer to it by name ($doc.Pages(‘Page-1’) or by number ($doc.Pages(1)).

$page=$doc.Pages(1)

Once we’ve got the page, we can see the shapes that are found on the page:

$page.Shapes | select-object –Property Name,Text

Visio objects are interesting to work with, and the properties you want might be hard to find, but they’re probably there.  For instance, to find the location (in the current unit of the document) of a shape you have to do this:

$x=$shape.Cells(‘PinX’).ResultIU 
$y=$shape.Cells(‘PinY’).ResultIU

That should get you started looking at Visio with PowerShell. In the next post we’ll work on dropping shapes on the page and connecting them.

A reference that will help immensely is the VBA Object model reference for Visio found here.

Let me know if you have questions about this.

–Mike