1. technology and computing
2. programming languages
3. visual basic

Autodesk® Revit® VSTA™: Writing Your First Macro
– An Introduction to the Macro Manager
Jose Guia – NELSON
CP222-2
This class will help guide you through launching the Macro Manager and creating your
very first VB.net macro in Visual Studio Tools for Applications (VSTA). VSTA is the replacement
technology for Microsoft® Visual Basic for Applications (VBA). VSTA is a .NET development
environment built into Revit and can be used to create both VB.NET and C# macros. In Autodesk Revit
2010, the Macro Manager serves as a convenient way to keep track of your VSTA macros at either the
application level or the document level.
Key learning
•
•
•
•
•
Macros in Revit
Inside the Macro Manager
Understanding the difference between module and macro
Writing your first VB.NET macro
Introduction to the VSTA environment
About the Speaker:
Based in Dallas, TX, Jose provides customized consulting, training, and application development
services to design teams using the latest Autodesk® software. Since becoming the Senior Application
Engineer at NELSON in 2007, he has successfully implemented application solutions within a wide
variety of disciplines. Jose has developed customized solutions for AutoCAD® software for over a
decade, initially in LISP and more recently with VB.NET. He started his career as a structural designer in
AutoCAD and took to programming and automation, which led him to develop numerous enterprise-level
engineering applications, databases, and custom windows applications.
Contact:
Google Voice: (972) 292-8064
Email: [email protected]
Website: http://www.cadkicks.com
LinkedIn: http://www.linkedin.com/in/joseguia
Blog: http://blog.cadkicks.com/
Twitter: http://twitter.com/cadkicks
Autodesk® Revit® VSTA™: Writing Your First Macro – An Introduction to the Macro Manager
Intro
This session is intended to help you give you a clear picture of what REVIT VSTA is and how we can
use the REVIT VSTA Macro Manager to help you save time by automating repetitive tasks.
Unlike most macro environments REVIT VSTA provides a true development environment through the
use of Visual Studio Tools for Applications.
What is REVIT V.S.T.A.
VSTA is an abbreviation, for Visual Studio Tools for Applications, it’s a technology licensed by Microsoft
that allows applications to expose the object model to automation. In this case the application is REVIT.
•
•
•
•
VSTA is licensed by Autodesk from Microsoft (Summit Software).
A familiar interface for developers, yet simple enough for beginners.
Application integration similar to that of VBA.
Tight integration allows for unparalleled exposure to REVIT Objects.
What is the REVIT MACRO Manager?
The Macro Manager is a REVIT Add-In that provides a front end interface to the VSTA IDE (Integrated
Development Environment).
•
•
•
•
•
Discuss macros/modules and how to manage them.
The difference between app level and document level.
Create / Delete Macros.
Running a previously built macro from the list.
Launch VSTA to edit your macros.
Creating your first Macro
•
•
•
Selecting a language. (VB.net, C#, or both).
Walkthrough creating a basic “Hello World” macro.
Creating advanced macros.
Macro Security Settings
•
•
Accessing and changing security options
Security level for application-level and document-level macros
Tips and Tricks
•
•
•
SDK Samples.
Where are the macros stored on your computer?
Sharing application level macros between computers.
2
Autodesk® Revit® VSTA™: Writing Your First Macro – An Introduction to the Macro Manager
REVIT VSTA
The VSTA IDE is a lite version of Microsoft Visual Studio 2008. You can use the VSTA IDE to define
macros that run in Revit. Unlike external commands and external applications, the macro functionality is
available to REVIT through the Macro Manager “add-in” in REVIT.
We will explain the API differences later in this topic, but for experienced developers, note that you do
not need to register the macros in Revit.ini, or add RevitAPI.dll as a reference.
Beginning with the release of the REVIT 2010 product line Revit VSTA is now installed by default. Also
note that Revit uses Microsoft .NET Framework version 3.5.
BENEFITS OF USING THE REVIT VSTA
•
•
•
Seamless integration with REVIT and the IDE.
Direct access the REVIT application (and its documents) or a particular document.
Flexibility to use language of choice (VB.NET, C#, or both).
3
Autodesk® Revit® VSTA™: Writing Your First Macro – An Introduction to the Macro Manager
The REVIT Macro Manager
The Macro Manager is a REVIT Add-In that provides a front end interface to the VSTA IDE (Integrated
Development Environment).
The Macro Manager allows us to launch the Revit VSTA IDE, where you can add, edit, build and debug
your macros:
Launching the Macro Manager
4
Autodesk® Revit® VSTA™: Writing Your First Macro – An Introduction to the Macro Manager
Identify application level macros and document level macros
•
•
•
Application tab. The Application tab lists macro modules available to all opened Revit projects in
the current instance of the Revit application. It is always the first tab to the left and active
(indicated by the icon). It is always available, whether projects are open. If you send the RVT file
to a person on another computer, application level macros would not be available.
Active document tab. The active document tab represents the currently active project in Revit.
The project does not necessarily contain embedded macros as in this case, although it can. The
tab bears the name of the active project (Project1 in this case) and is indicated by the icon. This
tab is not visible when a project is not open.
Inactive document tabs. Inactive document tabs represent open projects that contain embedded
macros (see below). The tab bears the name of the project (Project2 and Project3 in this case).
You add, modify, build, and delete modules and macros from these tabs.
Application-level and Document-level Modules
Fundamentally, application-level macro tools are written to be useful in any document in nearly any Revit
session. Additionally, they do not require a project to be open in Revit to run. This allows you the
flexibility to:
•
•
•
•
•
Customize the Revit UI
Add tools to Revit Architecture
Modify documents on opening
Batch open documents
Apply new standards or settings to new documents
Should these uses be implemented, it is good practice to create application-level macros that initiate
transactions needed by the macro.
Document-level macros tools are written for specific projects and are saved in the Revit project.
Managing your existing macros
Once in the macro manager we will notice the organizational grouping of macros. Macros can be either
independent within a module when they run, or share code or utilities with each other. They are arranged
in the Macro Manager under their parent module.
Macros within a module are seen and built together.
5
Autodesk® Revit® VSTA™: Writing Your First Macro – An Introduction to the Macro Manager
Creating your First Macro
The next few steps will guide you through creating a basic macro that displays a “Hello World” message
box.
•
•
•
•
Launch the Macro Manager
Select the Application tab
Click Module under “Create” to create a module that hosts our macro, provide the info
o Give the Module a Name (“ModuleHelloWorld”)
o Select your language (VB.NET)
o Assign a brief description for your reference
Click OK to close out the Module Definition
Next we want to create the actual macro
•
•
Highlight the newly created module in the list
Click Macro under “Create” and provide the macro information
o Give the Macro a Name (“MacroHelloWorld”)
o Select your parent module (should be preselected)
o Assign a brief description for your reference
6
Autodesk® Revit® VSTA™: Writing Your First Macro – An Introduction to the Macro Manager
After defining our macro, we click OK, and the VSTA environment will launch automatically. With the new
macro preselected in the IDE and a blinking cursor ready for us, we input the following lines of code:
Public Sub MacroHelloWorld()
MsgBox("Hello World")
End Sub
The next step is very important, from the “Build” menu select “Build ModuleHelloWorld”.
After editing a macro's code, remember to build it
before opening the Macro Manager again to run it. If
your code is set up correctly, you should see a Build
Succeeded message in the lower-left corner (by
default) of Revit VSTA. You can not build macros in the
Macro Manager.
After you create a macro you would expect to
see the newly created macro listed in the
Macro Manager's categorized list, but it is not
there. Why?
You must successfully build the macro project
in the Revit VSTA IDE (use the Build menu),
before your new macros will appear in the
Macro Manager.
The icons representing the module also show
their current state.
7
Autodesk® Revit® VSTA™: Writing Your First Macro – An Introduction to the Macro Manager
After building our test code we are ready to test our new code:
•
•
•
Close the VSTA environment
Select the newly created Macro under it Parent module
Click Run
Clicking RUN will launch the macro, in this case we should receive the following message box:
In our next sample I’d like to include code from the REVIT help file. Following the steps outlined
previously we create a new module/macro at Application level and Document level. At this point we can
see the key differences between the sample code used to add text using either method.
Application Level code to add text:
Public Sub MyFirstMacroAppVB()
Dim baseVec As Autodesk.Revit.Geometry.XYZ = Me.Create.NewXYZ(1.0, 0.0, 0.0)
Dim upVec As Autodesk.Revit.Geometry.XYZ = Me.Create.NewXYZ(0.0, 0.0, 1.0)
Dim origin As Autodesk.Revit.Geometry.XYZ = Me.Create.NewXYZ(0.0, 0.0, 0.0)
Dim align As Autodesk.Revit.Enums.TextAlignFlags =
Autodesk.Revit.Enums.TextAlignFlags.TEF_ALIGN_LEFT Or
Autodesk.Revit.Enums.TextAlignFlags.TEF_ALIGN_TOP
Dim strText As String = "My First Macro, App Level, VB.NET!"
Dim lineWidth As Double = 4.0 / 12.0
Dim pView As Autodesk.Revit.Elements.View = Me.ActiveDocument.ActiveView
Me.ActiveDocument.BeginTransaction()
Me.ActiveDocument.Create.NewTextNote(pView, origin, baseVec, upVec, lineWidth, align,
strText)
Me.ActiveDocument.EndTransaction()
End Sub
8
Autodesk® Revit® VSTA™: Writing Your First Macro – An Introduction to the Macro Manager
Document Level code to add text:
Public Sub MyFirstMacroDocVB()
Dim baseVec As Autodesk.Revit.Geometry.XYZ = Me.Application.Create.NewXYZ(1.0, 0.0, 0.0)
Dim upVec As Autodesk.Revit.Geometry.XYZ = Me.Application.Create.NewXYZ(0.0, 0.0, 1.0)
Dim origin As Autodesk.Revit.Geometry.XYZ = Me.Application.Create.NewXYZ(0.0, 0.0, 0.0)
Dim align As Autodesk.Revit.Enums.TextAlignFlags =
Autodesk.Revit.Enums.TextAlignFlags.TEF_ALIGN_LEFT Or
Autodesk.Revit.Enums.TextAlignFlags.TEF_ALIGN_TOP
Dim strText As String = "My First Macro, Doc Level, VB.NET!"
Dim lineWidth As Double = 4.0 / 12.0
Dim pView As Autodesk.Revit.Elements.View = Me.ActiveView
Me.Create.NewTextNote(pView, origin, baseVec, upVec, lineWidth, align, strText)
End Sub
I have highlighted the differences in syntax between the two samples, emphasizing the need to commit
our transactions when handling documents at the application level. We must also refer to the active
document as opposed to using only the “Me” keyword in document level code.
Compiling and running the previous code snippets will result in a text note being added to your drawing
with the sample text.
Another sample is iterating through REVIT elements in a project and performing actions on those
elements. This next piece of code is designed to run at Application level and will convert text case in a
project to UPPER CASE:
Public Sub BatchProcess_CapitalizeRooms()
Dim myIterator As Autodesk.Revit.ElementIterator = Me.ActiveDocument.Elements
While myIterator.MoveNext
Dim myElement As Autodesk.Revit.Element
myElement = myIterator.Current
If TypeOf myElement Is Autodesk.Revit.Elements.TextNote Then
Dim myText As Autodesk.Revit.Elements.TextNote = myElement
Me.ActiveDocument.BeginTransaction()
myText.Text = myText.Text.ToUpper
Me.ActiveDocument.EndTransaction()
End If
End While
End Sub
In the sample above we utilize the ElementIterator built into the REVIT API which allows us to cycle
through ALL of the objects in the current file, the sample above uses a slower method of filtering out
elements, in this case “TextNote”. By making a few changes to the code above and taking advantage of
the filtering mechanism provided to us by the API we can gain a huge performance increase:
Public Sub BatchProcess_CapitalizeRooms()
Dim myIterator As Autodesk.Revit.ElementIterator =
Me.ActiveDocument.get_Elements(GetType(Autodesk.Revit.Elements.TextNote))
While myIterator.MoveNext
Dim myElement As Autodesk.Revit.Element
myElement = myIterator.Current
Dim myText As Autodesk.Revit.Elements.TextNote = myElement
Me.ActiveDocument.BeginTransaction()
myText.Text = myText.Text.ToUpper
Me.ActiveDocument.EndTransaction()
End While
End Sub
9
Autodesk® Revit® VSTA™: Writing Your First Macro – An Introduction to the Macro Manager
Macro Security
You have the option to enable and disable macros by default. This protects your work and computer from
running dangerous malicious code unexpectedly. When working with macros, it is important to be wary of
the risks involved with their vulnerabilities. Only run known macros from trustworthy sources.
•
•
Disabling Application-level macros restricts access to both the Run and StepInto tools on the
Macro Manager. You will still be able to see, edit, and build the code, but modifications will not
change the current module status.
Disabling Document-level macros restricts access to both the Run and StepInto tools on the
Macro Manager for any project opened in Revit Architecture. You will still be able to see, edit, and
build the code, but modifications will not change the current module status. In the Document
Macros Security Settings section, select one of the following:
o Ask before enabling document macros.This is the default setting. Macros are disabled,
but you will be prompted to enable them, if macros are present when a Revit project is
opened. You can then choose to enable macros whenever they are detected.
o Disable document macros. Disables document-level macros when a project is opened.
To enable macros in this state, you must close the project, adjust the Macro Security
settings, and reopen the project.
o Enable document macros. Enables document-level macros when a project is opened. To
disable macros in this state, you must close the project, adjust the Macro Security
settings, and reopen the projec
Accessing the Security Options:
10
Autodesk® Revit® VSTA™: Writing Your First Macro – An Introduction to the Macro Manager
Tips and Tricks
TIP number one is the SDK samples that can be found on Autodesk’s website, they include several
sample files and are a quick way to get started in the world of VSTA.
The SDK can be found on the Autodesk web site, at http://www.autodesk.com/revit-sdk
The SDK includes:
•
•
•
•
•
Revit_VSTA_Samples.rvt
o A Revit project containing multiple VSTA document-level macro samples.
Revit_VSTA_Family_Samples.rfa
o A Revit family containing several VSTA document-level macro samples.
Revit_VSTA_MEP_Samples.rvt
o A Revit MEP project containing MEP VSTA macro samples.
VSTA Samples Readme.doc
o A description of the available VSTA samples.
Sample projects
o Additional application-level VSTA sample projects.
TIP Number two, where are the macros stored on your computer after you create them?
Application-level macro projects are stored in a subfolder of the Revit installation directory. For example:
C:\Program Files\Autodesk Revit Architecture 2010\Program\VSTAMacros\AppHookup...
Document-level macro projects are stored within an RVT file. On disk, when the associated RVT project
opens, any built and saved macro(s) are stored temporarily in:
C:\Program Files\Autodesk Revit Architecture 2010\Program\VstaMacros\DocHookups\...
However, these Document-level macro files are deleted from your local computer when their
corresponding Revit project document (.rvt) closes. The saved document-level macros are stored in the
RVT file.
TRICK! Sharing Macros.
One of the most popular requests is the ability to share application level macros which are created locally
on a users computer. Referring back to tip number two we were able to deduce where the macro files are
stored.
We locate the directories whose names correspond to the names of the modules inside of the
“AppHookup” directory
To share these macros with other REVIT 2010 users simply copy the folders and paste them to the same
location on the second computer. When they access the Macro Manager it will now list the new module
and macros. They must be built on the individual computers before they can be ran.
Thanks and hope you enjoyed the class,
Jose Guia
11