Autodesk Revit 2013 API Getting Started

Table of Contents Autodesk Revit 2013 API Getting Started.................................................................................................................................1 vervie!.......................................................................................................................................................................................2 "#at Can I $o "it# t#e Autodesk Revit API%.............................................................................................................................2 "#at &ou "ill 'eed to Get Started..............................................................................................................................................2 (nderstanding Autodesk Revit......................................................................................................................................................2 Installation of t#e Autodesk Revit API.........................................................................................................................................3 $evelo)*ent Re+uire*ents..........................................................................................................................................................3 (sing t#e Autodesk Revit API......................................................................................................................................................3 Autodesk Revit S$, and nline -el)....................................................................................................................................... Documentation Conventions.............................................................................................4 "#at /an 0ou do !it# t#e Autodesk Revit API%........................................................................................................................ Deployment Options........................................................................................................4 1.External commands......................................................................................................4 2.External applications....................................................................................................5 3.REX addins..................................................................................................................5 Registration of add1ins..............................................................................................................................................................2 34ternal Co**ands......................................................................................................................................................................5 T#e I34ternalCo**and Interfa/e.............................................................................................................................................5 Parameters.................................................................................................................... Return !alue.................................................................................................................." Remar#s........................................................................................................................" (sing an Autodesk Revit API 34ternal Co**and...................................................................................................................6 34ternal Co**and b7e/t 8ifeti*e.........................................................................................................................................9 34ternal A))li/ations....................................................................................................................................................................9 T#e I34ternalA))li/ation Interfa/e...........................................................................................................................................9 Parameters....................................................................................................................$ Return !alue..................................................................................................................$ 34ternal A))li/ation b7e/t 8ifeti*e.......................................................................................................................................9 Co*)atibilit0 of API a))li/ations !it# :.1bit Revit..................................................................................................................10 $ebugging &our A))li/ation in ;S <isual Studio 2010...........................................................................................................10 T#e Revit (nit S0ste*................................................................................................................................................................12 Storing and a//essing Custo* $ata for A))li/ations.................................................................................................................12 A))endi4 1 Glossar0 of Autodesk Revit ter*s....................................................................................................................13 A))endi4 2 1 =A>...................................................................................................................................................................13 %eneral&......................................................................................................................13 'utodes# Revit (tructure&..............................................................................................15

Autodesk Revit 2013 API Getting Started

Overview
'utodes# Revit 'rc)itecture 2*13+ 'utodes# Revit (tructure 2*13 and 'utodes# Revit ,EP 2*13 o--er an 'P. desi/ned to allo0 po0er users and external application developers to inte/rate t)eir applications 0it) 'utodes# Revit. 1)e 'P.s -or eac) o- t)ese t)ree products are very similar and 0ill 2e 3ointly re-erred to as t)e 'utodes# Revit 2*13 'P. or 'utodes# Revit 'P.. .t is stron/ly recommended t)at you 2ecome -amiliar 0it) 'utodes# Revit 'rc)itecture+ (tructure or ,EP and its -eatures 2e-ore attemptin/ to use t)e 'utodes# Revit 'P.. 1rainin/ can 2e -ound t)rou/) t)e 'utodes# Developer 4et0or# 5'D46.

What Can I Do With the Autodesk Revit API

1)e -ollo0in/ are /eneral areas 0)ere t)e 'P. is suita2le& Creatin/ add7ins to automate repetitive tas#s in t)e 'utodes# Revit user inter-ace En-orcin/ pro3ect desi/n standards 2y c)ec#in/ -or errors automatically Extractin/ pro3ect data -or analysis and to /enerate reports .mportin/ external data to create ne0 elements or parameter values .nte/ratin/ ot)er applications+ includin/ analysis applications+ into 'utodes# Revit products Creatin/ 'utodes# Revit pro3ect documentation automatically

What !ou Wi"" #eed to Get Started

' 0or#in/ understandin/ o- 'utodes# Revit 'rc)itecture+ 'utodes# Revit (tructure or 'utodes# Revit ,EP 2*13 'n installation o- an 'utodes# Revit72ased product+ includin/ t)e (o-t0are Development 8it ,( !isual (tudio 2*1* or ,( !isual (tudio 2*1* Express Edition+ or a -ull installation o,icroso-t !isual (tudio. (ome experience in a .4E1 2ased development lan/ua/e 5'utodes# Revit 'P. examples are provided in C9 and !isual :asic.4E1.6 2 days o- -ree time

$nderstanding Autodesk Revit

'll 'utodes# Revit72ased products are Parametric :uildin/ .n-ormation ,odelin/ 5:.,6 tools. (uc) a tool can 2e loo#ed at as a C'D pro/ram t)at is used to 2uild a 3D model rat)er t)an a set oindividual dra0in/ -iles. 'utodes# Revit modelin/ is accomplis)ed 0it) real70orld elements li#e columns+ 0alls+ doors and 0indo0s. 1)e user can create vie0s o- t)e model+ includin/ plans+ sections and callouts. 'll t)ese vie0s are directly /enerated -rom t)e 3D p)ysical model so c)an/es made in one vie0 0ill automatically propa/ate t)rou/) all ot)er vie0s. 1)is process virtually eliminates t)e need to update multiple dra0in/s and details 0)en a c)an/e is made in t)e model. 1)e 'utodes# Revit 'P. is desi/ned to re-lect t)e same user interaction paradi/ms as t)e pro/ram;s %rap)ical <ser .nter-ace. 1)ere-ore+ t)e -irst step to understandin/ t)e 'P. is to learn )o0 to use t)e pro/ram. .- you are an 'utodes# Revit novice+ 0e su//est you -irst start 2y /oin/ t)rou/) t)e 1utorials 0)ic) you can access t)rou/) t)e pro/ram;s =elp menu. >ou may also -ind it )elp-ul to ta#e a 1rainin/ class -rom your local 'utodes# reseller. 1)is 0ill )elp you ?uic#ly /et up to speed 0it) t)e pro/ram 'utodes# Resources& )ttp&@@000.autodes#.com@revit2uildin/@ 2

Autodesk Revit 2013 API Getting Started )ttp&@@000.autodes#.com@revitstructure@ )ttp&@@000.autodes#.com@revitsystems@ )ttp&@@000.autodes#.com@2im@ )ttp&@@discussion.autodes#.com@ (elect A 'utodes# Revit :uildin/ 1)en (elect A 'utodes# Revit 'P.

External Resources& )ttp&@@000.revitcity.com@ )ttp&@@000.au/i.com@revit@ )ttp&@@000.revitinside.com@

Insta""ation o% the Autodesk Revit API

1)e 'utodes# Revit 'P. is automatically installed 0it) t)e de-ault installation o- t)e 'utodes# Revit 2ased product. 1)e 'utodes# Revit 'P. (o-t0are Development 8it is installed -rom t)e 1ools and <tilities section ot)e 'utodes# Revit installation D!D.

Deve"o&'ent Re(uire'ents
1)e 'utodes# Revit 'P. re?uires t)e ,icroso-t .4E1 Brame0or# v3.5 or 4.*. 1o edit and de2u/ your 'P. applications+ you need an interactive development environment suc) as ,icroso-t !isual (tudio 2*1* or one o- t)e ,( !isual (tudio Express Editions -or C9 or !isual :asic.4E1. C)en developin/ 0it) t)e 'utodes# Revit 'P.+ ensure t)at your pro3ect re-erences t0o DDDs& RevitAPI.dll and RevitAPIUI.dll contained in t)e 'utodes# Revit Pro/ram directory. (ome pro/rammin/ s#ills are re?uired to e--ectively use t)e 'P.. .- you are a 2e/inner in pro/rammin/+ 0e stron/ly advise you to learn ,icroso-t !isual (tudio 2*1* and one o- t)e compati2le lan/ua/es li#e C9 or !isual :asic.4E1. 1)ere are many /ood 2oo#s and classes to /et you started. Resources: Online resources :oo#s& Code Complete+ (econd Edition+ 2y (teve ,cConnell (o-t0are Pro3ect (urvival %uide+ 2y (teve ,cConnell Bree !isual (tudio E )ttp&@@msdn.microso-t.com@!(tudio@Express@ )ttp&@@000.code/uru.com@ )ttp&@@devx.com@ )ttp&@@000.msdn.microso-t.com@

$sing the Autodesk Revit API

Autodesk Revit 2013 API Getting Started

Autodesk Revit SD) and On"ine *e"&

%et t)e 'utodes# Revit (D8 -rom 'D4 or t)e installation D!D. 1)e 'utodes# Revit 2*13 (D8 can 2e unpac#ed and installed -rom t)e 1ools and <tilities option in t)e installation D!D. .n t)e (D8+ t)ere are example -iles t)at 0ill )elp you /et a 2etter understandin/ o- t)e 'P. and its use. Eac) example -ile )as a sample revit.ini -ile 0it) t)e in-ormation t)at you 0ill need to edit and place into t)e revit.ini -ile located in your 'utodes# Revit Pro/ram -older+ 0)ic) 'utodes# Revit 0ill access on launc). <nFip t)e (D8 onto a local drive Read t)e Read ,e Birst.doc in t)e (D8

Revit'P..c)m is t)e 'utodes# Revit 'P. re-erence documentation )elp -ile+ included 0it) t)e (D8 pac#a/e in t)e GRevit 2*13 (D8G -older. Resources: 000.autodes#.com@adn 7 'utodes# Developer 4et0or# )ome 5'D46 000.autodes#.com@developrevit 7 'utodes# Revit development resources )ttp&@@discussion.autodes#.com E 'utodes# product discussion /roups (elect A 'utodes# Revit 'rc)itecture 1)en (elect A 'utodes# Revit 'P. )ttp&@@t)e2uildin/coder.typepad.com@2lo/@ 7 1)e :uildin/ Coder+ an '4D 2lo/ dedicated to Revit codin/ )ttp&@@2imapps.typepad.com@ 7 :im 'pps+ a 2lo/ dedicated to :., applications Documentation Conventions 1)is document 0ill contain names in namespace -ormat+ suc) as Autodesk.Revit.DB.Element

What +an ,ou do with the Autodesk Revit API

Deployment Options 1)e 'utodes# Revit 'P. supports in7process DDDs only. 1)is means t)at your 'P. application 0ill 2e compiled as a DDD loaded into t)e 'utodes# Revit process. 1)e 'utodes# Revit 'P. supports sin/le t)readed access only. 1)is means t)at your 'P. application must per-orm all 'utodes# Revit 'P. calls in t)e main t)read 50)ic) is called 2y t)e 'utodes# Revit process at various 'P. entry points6+ and your 'P. application cannot maintain operations in ot)er t)reads and expect t)em to 2e a2le to ma#e calls to 'utodes# Revit at any time. 1)ere are t0o types o- DDDs t)at you can create 0it) t)e 'utodes# Revit 'P.& 1. E ternal commands 1)e 'utodes# Revit 'P. ena2les you to add ne0 commands to t)e user inter-ace o- 'utodes# Revit. 1)ese commands 0ill appear in t)e 'dd7ins ta2 under t)e HExternal 1ools; pulldo0n+ as seen in Bi/ure 1. 1)rou/) t)e 'P.+ external tool commands )ave access to t)e 'utodes# Revit data2ase+ as 0ell as t)e currently selected elements.

!i"ure 1 # E ternal $ool added to Revit -

Autodesk Revit 2013 API Getting Started

%. E ternal applications 1)e 'utodes# Revit 'P. ena2les you to also add external applications. 1)ese applications are invo#ed durin/ 'utodes# Revit startup and s)utdo0n. 1)ey can create ne0 panels in t)e 'dd7ins ta2+ as seen in Bi/ure 2. 1)ey can also re/ister )andlers t)at can react to events occurrin/ in t)e 'utodes# Revit user inter-ace.

!i"ure % # &e' panels and controls added to Revit (. RE) addins REX 5Revit Extensions6 is an 'P. -rame0or# t)at lets you 2uild applications -or Revit in .4E1 similar to classes t)at implement .ExternalCommand. REX is meant to /ive you a more )i/)7level development environment t)rou/) 2uilt7in resources suc) as& 'utomatic dialo/ 2ox creation and display Di2raries to 0or# 0it) units and /eometry :uilt7in command72ased arc)itecture to ma#e menu and tool2ar development easier. ' standard mec)anism -or accessin/ a re-erence to t)e Revit application o23ect. 'utomatic deployment and installation o- addins -or easy de2u//in/.

Please see t)e IGRevit 2*13 (D8GREX (D8GJ -older -or more details.

Registration o% add.ins
1)e Revit 'P. o--ers t)e a2ility to re/ister 'P. applications via a .addin mani-est -ile. ,ani-est -iles 0ill 2e read automatically 2y Revit 0)en t)ey are places in one o- t0o locations on a userKs system& In a non#user speci*ic location in +application data+ o Bor Cindo0s XP 7 C&GDocuments and (ettin/sG'll <sersG'pplication DataG'utodes#GRevitG'ddinsG2*13G o Bor !ista@Cindo0s 7 C&GPro/ramDataG'utodes#GRevitG'ddinsG2*13G In a user speci*ic location in +application data+ o Bor Cindo0s XP 7 C&GDocuments and (ettin/sGLuserMG'pplication DataG'utodes#GRevitG'ddinsG2*13G o Bor !ista@Cindo0s 7 C&G<sersGLuserMG'ppDataGRoamin/G'utodes#GRevitG'ddinsG2*13G /

Autodesk Revit 2013 API Getting Started 'll -iles named .addin in t)ese locations 0ill 2e read and processed 2y Revit durin/ startup. ' 2asic -ile addin/ one ExternalCommand loo#s li#e t)is& <?xml version="1.0" encoding="utf-16" standalone="no"?> <RevitAddIns> <AddIn !"e="#ommand"> <Assem$l!>c%&'!(rogram&'!(rogram.dll<)Assem$l!> <AddInId>*6e$*00a-+c,--.,,,-a*,d-/1.+0ecae0ed<)AddInId> <1ull#lass2ame>Revit.3am"les.3am"le#ommand<)1ull#lass2ame> < ext>3am"le command<) ext> <4isi$ilit!'ode>2ot4isi$leIn1amil!<)4isi$ilit!'ode> <4isi$ilit!'ode>2ot4isi$leIn'5(<)4isi$ilit!'ode> <Availa$ilit!#lass2ame>Revit.3am"les.3am"leAccessi$ilit!#6ec7 <)Availa$ilit!#lass2ame> <)AddIn> <)RevitAddIns> ' 2asic -ile addin/ one External'pplication loo#s li#e t)is& <?xml version="1.0" encoding="utf-16" standalone="no"?> <RevitAddIns> <AddIn !"e="A""lication"> <2ame>'! sam"le a""lication<)2ame> <Assem$l!>c%&'!(rogram&'!(rogram.dll<)Assem$l!> <AddInId>60.810-+-1*.+-.0-1-,-*6-#+619100/10*<)AddInId> <1ull#lass2ame>Revit.3am"les.3am"leA""lication<)1ull#lass2ame> <)AddIn> <)RevitAddIns> ,ultiple 'dd.n elements may 2e provided in a sin/le mani-est -ile. 1)e ne0 mec)anism currently o--ers t)e -ollo0in/ X,D ta/s& $a" Assembly FullClassName AddInId Description The full path to the add-in assembly file. Required for all ExternalCommands and ExternalApplications. The full name of the class in the assembly file which implements IExternalCommand or IExternalApplication. Required for all ExternalCommands and ExternalApplications. A GUID which represents the id of this particular application. AddInIds must be unique for a given session of Revit. Autodesk recommends you generate a unique GUID for each registered application or command. Required for all ExternalCommands and ExternalApplications. The property :IA""lication.ActiveAddInId provides programmatic access to this value, if required. The name of application. Required; for ExternalApplications only. The name of the button. Optional; use this tag for ExternalCommands only. The default is "External Tool". Short description of the command, will be used as the button tooltip. Optional; use this tag for ExternalCommands only. The default is a tooltip with just the command text. Provides the ability to specify if the command is visible in project documents, family documents, or no document at all. Also provides the ability to specify the discipline(s) where the command should be visible. Multiple values may be set for this option. Optional; use this tag for ExternalCommands only. The default is to display the command in all modes and disciplines, including when there is no active document. Previously 0

Name Text Description VisibilityMode

Autodesk Revit 2013 API Getting Started written external commands which need to run against the active document should either be modified to ensure that the code deals with invocation of the command when there is no active document, or apply the 2ot4isi$le;6en2oActive9ocument mode. AvailabilityClassName The full name of the class in the assembly file which implemented IExternalCommandAvailability. This class allows the command button to be selectively grayed out depending on context. Optional; use this tag for ExternalCommands only. The default is a command that is available whenever it is visible. The path to the icon to use for the button in the External Tools pulldown menu. The icon should be 32 x 32 pixels for best results. Optional; use this tag for ExternalCommands only. The default is to show a button without an icon. Long description of the command, will be used as part of the button's extended tooltip. This tooltip is shown when the mouse hovers over the command for a long amount of time. You can split the text of this option into multiple paragraphs by placing <p> tags around each paragraph. Optional; use this tag for ExternalCommands only. If neither of this property and TooltipImage are supplied, the button will not have an extended tooltip. The path to an image file to show as a part of the button extended tooltip, shown when the mouse hovers over the command for a longer amount of time. Optional; use this tag for ExternalCommands only. If neither of this property and TooltipImage are supplied, the button will not have an extended tooltip. Localization setting for Text, Description, LargeImage, LongDescription, and TooltipImage of external tools buttons. Revit will load the resource values from the specified language resource dll. The value can be one of the eleven languages supported by Revit. If no LanguageType is specified, the language resource which the current session of Revit is using will be automatically loaded.

LargeImage

LongDescription

TooltipImage

LanguageType

12terna" Co''ands
.mplement support -or a speci-ic inter-ace+ in t)is case 'utodes#.Revit.<...ExternalCommand. 'dds one or more entries to t)e Revit.ini -ile descri2in/ t)e external command.

1ec)nically+ an external command is an exposed .4E1 o23ect t)at supports t)e 'utodes#.Revit.<...ExternalCommand inter-ace. Burt)ermore+ in t)e Revit.ini -ile t)ere must 2e one entry -or eac) suc) o23ect in order -or Revit to 2e a2le to IseeJ and to use t)e commands.

3he I12terna"Co''and Inter%a+e

1)e declaration 5!:.4E16 o- t)e inter-ace is as -ollo0s& Function Execute(ByVal commandData As Autodesk.Revit.UI.ExternalCommandData, ByRe messa!e As "trin!, ByVal elements As Autodesk.Revit.DB.Element"et# As Result Parameters command9ata & 1)e o23ect passed in t)is parameter contains in-ormation important to t)e command t)at is 2ein/ executed. 1)is data includes t)e 'utodes# Revit 'pplication o23ect as 0ell as t)e currently active vie0.

Autodesk Revit 2013 API Getting Started message & 1)e messa/e strin/ can 2e set to supply a speci-ic messa/e to t)e user 0)en t)e command terminates. =o0 t)is messa/e is displayed is dependent upon t)e return value ot)e -unction. (ee t)e remar#s section -or more details. elements & .nitially t)is is an empty set t)at can contain 'utodes# Revit elements. C)en t)e command terminates+ t)e elements 0it)in t)is set may 2e displayed+ 2ased on t)e return value. (ee t)e remar#s section -or more details.

Return ,alue result & 1)e return value can 2e one o- t)e -ollo0in/& 3uccess & .s returned i- t)e command succeeded as expected 0it)out any un)andled error conditions. 1)e external command 0ill appear as an undoa2le operation in t)e 'utodes# Revit user inter-ace. #ancelled & 1)is value speci-ies t)at t)e user re?uested t)at t)e command 2e cancelled. 'ny c)an/es t)at 0ere made to 'utodes# Revit o23ects durin/ t)e external commands execution 0ill 2e undone. ' messa/e may 2e posted+ see t)e Remar#s section. 1ailure & Bailure si/ni-ies t)at t)e external command -ailed in some manner -rom 0)ic) it cannot recover. 'ny c)an/es made to 'utodes# Revit o23ects durin/ t)e execution o- t)e external command 0ill 2e undone. ' messa/e 0ill 2e posted+ see t)e Remar#s section.

Remarks 1)e messa/e and elements parameters are used i- t)e command 0as cancelled or -ailed. #ancelled & .- t)e external command 0as cancelled and t)e messa/e parameter 0as set 2y t)e external command t)en t)e messa/e is displayed 0)en execution is returned 2ac# to 'utodes# Revit. .- t)e messa/e parameter 0as not set t)en no messa/e is displayed and t)e command 0ill exit silently. 1ailed & .- t)e external command -ailed t)en t)e contents o- t)e messa/e parameter 0ill 2e displayed. .- t)e element set contains 'utodes# Revit elements t)en t)ese elements 0ill 2e )i/)li/)ted 0)en t)e error messa/e is displayed t)us /ivin/ t)e developer t)e a2ility to s)o0 t)e user t)e pro2lem elements.

$sing an Autodesk Revit API 12terna" Co''and

1. <ser opens@creates a pro3ect in 'utodes# Revit 2. <ser selects t)e external command -rom t)e External 1ools pulldo0n on t)e 'dd7ins ta2. 3. 1)e user )ad t)e option to select a num2er o- 'utodes# Revit elements 2e-ore invo#in/ t)e External 1ools pro/ram. .- t)ey did+ t)e pro/ram can decide to only per-orm its -unction on t)e selected mem2ers. 4. 1)e 'P. pro/ram ta#es -ocus -rom 'utodes# Revit and per-orms t)e re?uired tas#. O-ten a dialo/ 2ox may 2e re?uired to o2tain user input 2e-ore t)e application can complete its 0or#. 5. Once t)e add7on tool )as completed its -unction or )as 2een dismissed 2y t)e user t)e pro/ram 0ill update t)e 'utodes# Revit model as re?uired and return -rom t)e external command+ /ivin/ -ocus 2ac# to 'utodes# Revit.

Autodesk Revit 2013 API Getting Started

12terna" Co''and O67e+t 8i%eti'e

C)en no ot)er command or edit modes are active 0it)in 'utodes# Revit+ t)e re/istered external command 0ill 2ecome ena2led. C)en pic#ed+ t)e command o23ect 0ill 2e created and t)e Execute met)od called. Once t)is met)od returns 2ac# to 'utodes# Revit t)e command o23ect 0ill 2e destroyed. Due to t)is destruction+ data cannot persist 0it)in t)e o23ect 2et0een command executions. .- you 0is) t)e data to persist you may use an external -ile or data2ase to do so. .you 0is) t)e data to persist 0it)in t)e 'utodes# Revit pro3ect you may use t)e s)ared parameters mec)anism to store t)is data.

12terna" A&&"i+ations
.mplement support -or a speci-ic inter-ace+ in t)is case 'utodes#.Revit.<...External'pplication. 'dds one or more entries to t)e Revit.ini -ile descri2in/ t)e external application.

1ec)nically+ an external application is an exposed .4E1 o23ect t)at supports t)e 'utodes#.Revit..External'pplication inter-ace. Burt)ermore+ in t)e Revit.ini -ile t)ere must 2e one entry -or eac) suc) o23ect in order -or 'utodes# Revit to 2e a2le to load t)ese applications 0)en 'utodes# Revit starts.

3he I12terna"A&&"i+ation Inter%a+e

1)e declaration 5C96 o- t)e inter-ace is as -ollo0s& 'utodes#.Revit.<...External'pplication.Result On(tartup5'utodes#.Revit.Controlled'pplication application6 'utodes#.Revit.<...External'pplication.Result On()utdo0n5'utodes#.Revit.Controlled'pplication application6 a""lication % 1)e o23ect passed in t)is parameter contains in-ormation important to t)e commands On(tartup and On()utdo0n t)at are 2ein/ called. 1)is o23ect provides limited access met)ods o- 'utodes# Revit 'pplication+ suc) as !ersion4ame+ !ersion4um2erN and dele/ates -or some events+ suc) as OnDocumentOpened+ OnDocument(aved.

Parameters

Return ,alue result & 1)e return value can 2e one o- t)e -ollo0in/& 3uccess & .s returned i- t)e external application succeeded as expected 0it)out any un)andled error conditions. 1ailure & Bailure si/ni-ies t)at t)e external application -ailed in some manner -rom 0)ic) it cannot recover. #ancelled & 1)is value speci-ies t)at t)e external application 2e cancelled.

12terna" A&&"i+ation O67e+t 8i%eti'e

C)en 'utodes# Revit starts+ t)e external application o23ect 0ill 2e created and t)e On(tartup met)od called. Once t)is met)od returns 2ac# success-ully to 'utodes# Revit t)e external application o23ect 0ill 2e )eld durin/ t)e entire 'utodes# Revit session. 1)e On()utdo0n met)od 0ill 2e called 0)en 'utodes# Revit s)uts do0n.

Autodesk Revit 2013 API Getting Started

Co'&ati6i"it, o% API a&&"i+ations with 0-.6it Revit

,ost 'P. applications can 2e 2uilt 0it) settin/s t)at allo0 t)em to 2e used eit)er 0it) 3272it Revit or O472it Revit. <se t)e -ollo0in/ settin/s to 2uild your pro3ect in t)is manner& Bor C9 pro3ect+ /o to pro3ect property7M:uild ta/+ select plat-orm tar/et as I'ny CP<J. Bor !:.4et pro3ect+ /o to pro3ect property7MCompile ta/+ select plat-orm as I'ny CP<J. Bor CPP@CD. pro3ect+ open property pa/e and /o to Con-i/uration properties7M%eneral7 MCommon Dan/ua/e Runtime support+ select @clr&sa-e.

4ote t)at t)ere are some ,icroso-t components 5suc) as OleD: provider -or ,icroso-t Qet6 t)at are not supported -or O472it. 'll (D8 samples are set up to 0or# 0it) eit)er 3272it or O472it Revit+ except t)ose samples t)at )ave dependencies to unsupported ,icroso-t components. !or more in*ormation see t-is .icroso*t resource: )ttp&@@msdn.microso-t.com@en7us@li2rary@ms241*O45!(."*6.aspx

De6ugging !our A&&"i+ation in :S ;isua" Studio 2010

1)ere are a -e0 di--erences 2et0een de2u//in/ a standalone application 5EXE6 and an external application 5DDD6 t)at needs anot)er pro/ram to launc) it. 1o de2u/ an application t)at is usin/ t)e 'utodes# Revit 'P. it needs to 2e activated 2y 'utodes# Revit. 1o do t)is in t)e developer environment -or de2u//in/ you 0ill need to& 1. Open up t)e !isual (tudio pro3ect -or t)e 'P. application. 5Bor example 'nalytical(upportDataR.n-o.cspro3 -rom t)e (amples -older6 2. Brom t)e Pro3ect menu select 'nalytical(upportDataR.n-o Properties

3. (elect t)e De2u/ ta2 on t)e le-t 4. (elect t)e I(tart external pro/ram&J radio 2utton 5. Press t)e 2ro0se 2utton and -ind t)e Revit.exe -ile and press Open

10

Autodesk Revit 2013 API Getting Started O. (et some 2rea# points in your source code. . Brom !isual (tudio+ select I(tart De2u//in/J. 'utodes# Revit 0ill launc). ". 1o )it a 2rea# point select t)e option -or your pro/ram -rom t)e External 1ools menu. Once t)e compiler reac)es one o- your 2rea# points it 0ill stop to let you de2u/ your pro/ram.

11

Autodesk Revit 2013 API Getting Started

3he Revit $nit S,ste'

1)e Revit <nit (ystem uses t)e -ollo0in/ 2ase units& Base Unit Unit In Revit Unit /ystem Den/t) Beet 5-t6 .mperial 'n/le Radian ,etric ,ass 8ilo/ram 5#/6 ,etric 1ime (econds 5s6 ,etric Electric Current 'mpere 5'6 ,etric 1emperature 8elvin 586 ,etric Duminous .ntensity Candela 5cd6 ,etric &ote& :ecause Revit stores len/t)s in -eet and ot)er ?uantities in metric+ a derived unit involvin/ len/t) uses a non7standard unit usin/ t)e .mperial and t)e ,etric systems. Bor example+ -orce is measured in mass7len/t) per time s?uared and is stored in #/7-t@s 2.

Storing and a++essing Custo' Data %or A&&"i+ations

O-ten pro/rams lin#ed to 'utodes# Revit re?uire in-ormation t)at is not availa2le in t)e 'utodes# Revit model data2ase. 1)ere are a num2er o- 0ays -or t)e user to enter suc) additional in-ormation. =o0 and 0)ere t)e in-ormation is entered depends on its use& C)en t)e in-ormation is o- a /eneral type and t)e user 0ill 0ant to see and edit it inside 'utodes# Revit+ t)en it s)ould 2e stored as a visi2le Pro3ect or ()ared Parameter. .- t)e in-ormation needs to 2e #ept 0it) t)e 'utodes# Revit model as it evolves 2ut does not need to 2e visi2le t)en it can 2e stored in t)e 'utodes# Revit model as a non7visi2le Pro3ect or ()ared Parameter. .- t)e in-ormation is speci-ic to a sin/le add7on pro/ram+ and is too lar/e to practically store 0it)in t)e 'utodes# Revit model suc) as speci-ications -or a multitude o- 2uildin/ products su23ect to c)an/e+ t)en t)e 2est solution may 2e to create a concurrent model data2ase t)at stores t)e pro/ram speci-ic in-ormation. .n t)is case it may 2e use-ul to use t)e element <ni?ue.d property -or eac) element as a #ey -or t)e data2ase+ 2ecause t)e element;s <ni?ue.d is sta2le 0it)in a model.

12

Autodesk Revit 2013 API Getting Started

A&&endi2 1 G"ossar, o% Autodesk Revit ter's

Family
' Bamily is a collection o- o23ects called types. ' -amily /roups elements 0it) a common set oparameters+ identical use+ and similar /rap)ical representation. Di--erent types 0it)in a -amily may )ave di--erent values o- some or all parameters+ 2ut t)e set o- parameters 7 t)eir names and t)eir meanin/ 7 are t)e same.

Parameter
1)ere are a num2er o- 'utodes# Revit parameter types. /-ared Parameters can 2e t)ou/)t o- as user de-ined varia2les. /ystem Parameters are varia2les t)at are )ard coded in 'utodes# Revit. !amily parameters are varia2les t)at are de-ined 0)en a -amily is created or modi-ied.

Type
' 1ype is a mem2er o- a Bamily. Eac) 1ype )as speci-ic parameters t)at are constant -or all instance o- t)e 1ype t)at exist in your model. 1)ese are called 1ype Properties. 1ypes )ave ot)er parameters called .nstance parameters+ 0)ic) may vary over t)e various instances o- t)is type in your model.

A&&endi2 2 . <A=
0eneral: 1: =o0 do . re-erence an element in 'utodes# RevitS A: Eac) element )as .d and <ni?ue.d properties t)at can 2e used to re-erence t)e element. 1: 're element .Ds universally uni?ue and can t)ey ever c)an/eS A: 't any /iven time+ element .Ds in a Revit model are uni?ue. =o0ever+ multi7user interactions in Revit can result in an element;s .D c)an/in/. 'lso+ anot)er element in a di--erent model may )ave an element 0it) t)e same .D. .- you need to store an .D 5especially an .D o- an element t)at 0as ne0ly created6 in order to -ind t)e element later+ store <ni?ue.d. 1: Can a model only use one s)ared parameter -ileS A: ()ared parameter -iles are used to store a parameter speci-ication. 1)e most important portion o- t)ese parameter descriptions is t)e %<.D t)at is used to insure t)e uni?ueness o- a parameter 2ot) in a sin/le model -ile and across multiple models. 'utodes# Revit can 0or# 0it) multiple s)ared parameter -iles 2ut can only read parameters -rom one -ile at a time. .t is t)en up to you to c)oose t)e same s)ared parameter -ile -or all models or a di--erent one -or eac). 'n 'P. application s)ould avoid inter-erin/ 0it) t)e user;s o0n parameter -ile. >our application s)ould s)ip 0it) a parameter -ile containin/ t)e parameters it re?uires. 1o load t)e parameter5s6 into an 'utodes# Revit -ile+ an application s)ould& (tore t)e name o- t)e user;s parameter -ile+ ,a#e t)e applications parameter -ile current+ Doad t)e re?uired parameter5s6 and+ 13

Autodesk Revit 2013 API Getting Started ,a#e t)e user;s parameter -ile current.

1: Do . need to distri2ute t)e s)ared parameters -ile 0it) t)e model so ot)er pro/rams can use t)e s)ared parametersS A: 4o+ you do not need to distri2ute s)ared parameter -iles. 1)e s)ared parameters -ile is only used to load s)ared parameters. '-ter t)ey are loaded t)e -ile is no lon/er needed -or t)at model. 1: Do s)ared parameter values /et copied 0)en t)e correspondin/ element is copiedS A: >es t)ey do. 1)ere-ore i- you )ave a s)ared parameter t)at )olds a uni?ue .D -or an item in your data2ase it is recommended t)at you ma#e t)is .D include t)e 'utodes# Revit element;s <ni?ue.d property. 1)is 0ill allo0 you to identi-y elements t)at 0ere copied -rom existin/ elements in your application. 1: 'utodes# Revit ta#es a lon/ time to update 0)en my application sends data 2ac# to t)e model. C)at do . need to do to speed it upS A: >ou s)ould use t)e ,anual re/eneration mode to prevent t)e 'P. -rame0or# -rom re/eneratin/ a-ter every model level c)an/e. 1)en+ you 0ill use t)e re/eneration 'P.s to -orce update o- t)e document a-ter a /roup o- c)an/es. Per-ormance o- multiple modi-ications o- t)e Revit document s)ould 2e -aster t)an Re/enerationOption.'utomatic. :ecause t)is mode suspends all updates to t)e document+ your application s)ould not read data -rom t)e document a-ter it )as 2een modi-ied until t)e document )as 2een re/enerated+ or it runs t)e ris# o- accessin/ stale data. 1: C)at do . do i- . 0ant to add s)ared parameters to elements t)at do not )ave t)e a2ility to )ave s)ared parameters 2ound to t)emS Bor example& %rids or ,aterials. A: .- an element type does not )ave t)e a2ility to contain s)ared parameters+ you 0ill need to add a pro3ect parameter. 1)is does ma#e it a 2it more complicated as you 0ill need di--erent code to access t)e value o- t)e parameter on t)ese elements. 1: C)en exportin/ a model containin/ /roups to an external pro/ram+ t)e user receives an error at t)e end o- t)e export& TC)an/es to /roup T%roup 1T are allo0ed only in /roup edit mode. <se t)e Edit %roup command to ma#e t)e c)an/e to all instances o- t)e /roup. >ou may use t)e T<n/roupT option to proceed 0it) t)is c)an/e 2y un/roupin/ t)e c)an/ed /roup instances.T A: Currently t)e 'P. does not permit c)an/es to mem2ers o- /roups. >ou can pro/rammatically un/roup+ ma#e t)e c)an/e+ re/roup and t)en s0ap t)e ot)er instances o- t)e old /roup to t)e ne0 /roup to /et t)e same e--ect. 1: C)y do t0o di--erent Bamily(ym2ols )ave t)e same name in my 'utodes# Revit documentS A: .n t)e 'utodes# Revit 'P.+ (ym2ols represent /eometry. Consider t)at t0o 0indo0 instances o- t)e same type are inserted into 0alls o- di--erent types. 4o0+ t)ese t0o 0indo0 instances re-er to t)e same Bamily(ym2ol and count as 2ein/ o- t)e same type+ 2ut it is clear t)at t)ey cannot possi2ly use t)e same sym2ol;s /eometry+ since insertin/ t)em into 0alls o- di--erent t)ic#ness c)an/es eac) 0indo0;s /eometry to matc). 1o trac# individual instances o- Bamily(ym2ols+ 'utodes# Revit employs a ImasterJ and IslaveJ -unctionality 0it) IslaveJ Bamily(ym2ols localiFin/ t)eir /eometry to surroundin/ conditions accordin/ to t)e ImasterJ Bamily(ym2ol template. 1-

Autodesk Revit 2013 API Getting Started .- t)ere is no door instance in a model+ t)ere is only one ImasterJ Bamily(ym2ol -or a 3OJx"4J door+ 2ut i- a door is inserted+ 'utodes# Revit 0ill create a IslaveJ Bamily(ym2ol -or t)e ne0 3OJx"4J Door. (u2se?uent doors placed in t)e model 0ill cause 'utodes# Revit to /enerate additional IslaveJ Bamily(ym2ols. 1: .s t)e order o- vertices or t)e trian/les in an 'utodes# Revit /eometry mes) o23ect relia2ly sorted in counter7cloc#0ise directionS A: >es. 1: C)y a-ter -lippin/ a 0all or door 52ot) external and internal6 do its properties BromRoom and 1oRoom do not c)an/eS A: External Doors U External Cindo0s )ave only eit)er a BromRoom or a 1oRoom. <sers can decide 0)ic) property exists 0)en locatin/ doors or 0indo0s. .- external doors or 0indo0s are -lipped t)eir BromRoom or 1oRoom properties do not c)an/e automatically+ 2ut can 2e manually c)an/ed.

Autodesk Revit /tructure: 1: (ometimes t)e de-ault end releases o- structural elements render t)e model unsta2le. A: .n some cases t)e user may not )ave paid attention to t)e element end release 0)en modelin/ t)e elements. 1)e 'nalytical ,odel C)ec# -eature 0ill -ind some o- t)ese issues. C)en exportin/ t)e analytical model+ as# t)e user 0)et)er t)ey 0ant to retain t)e release conditions -rom R(1 or t)ey 0ant to set all 2eams and columns to 2e -ixed. C)en re7importin/ t)e model to R(1+ al0ays update t)e end releases and do not over0rite t)e end releases on su2se?uent exports to analysis pro/rams. 1: .Km rotatin/ t)e orientation o- t)e 2eam so it is rotated in t)e 0ea# direction+ i.e. t)e . o- a C14X3* is rotated to loo# li#e an = 2y a $* de/ree rotation. =o0 is t)at rotation an/le accessed in t)e 'P.S :ecause t)e location is a DocationCurve not a DocationPoint . do not )ave access to t)e Rotation value so 0)at is it . need to c)ec#S .Kve /ot a Bamily.nstance element to c)ec# so 0)at do . do 0it) itS A: 1a#e a loo# at t)e RotateBramin/O23ect example in t)e (D8. .t )as examples o- )o0 to /et and c)an/e t)e rotation an/le o- 2eams+ 2races and columns. 1: =o0 do . add ne0 concrete 2eam and column siFes to a modelS A: 1a#e a loo# at t)e Brame:uilder sample code in t)e (D8.

1/

Autodesk Revit 2013 API Getting Started 1: =o0 to vie0 true dec# layerS A: 1)ere is an example called Dec#Properties t)at provides t)e in-ormation on )o0 to /et t)e layer in-ormation -or t)e dec#. 1)e dec# in-ormation is reported in exactly t)e same 0ay as t)e <.. 1)e dec# dimension parameters are s)o0n in t)e -ollo0in/ -i/ure.

1: =o0 do . tell 0)en . )ave a 2eam 0it) a cantileverS A: 1)ere is no direct 0ay in t)e 'utodes# Revit data2ase to tell i- a 2eam )as a cantilever. =o0ever one or more o- t)e options 2elo0 can /ive you a /ood /uess at 0)et)er a 2eam is a cantilever& Options 1. 1)ere are t0o parameters called ,oment Connection (tart and ,oment Connection End. .t)e value t)at is set -or t)ese t0o is not 4one t)en you s)ould loo# and see i- t)ere is a 2eam t)at is co7linear and also )as t)e value set to somet)in/ ot)er t)an 4one. >ou could also as# t)e user to ma#e sure to select t)e Cantilever ,oment option rat)er t)an ,oment Brame option. 2. 1race t)e connectivity 2ac# 2eyond t)e element say one or t0o elements. 3. Doo# at element release conditions. 1: =o0 do . model a -oundation 0it) end over)an/s under a 0allS A: 1)e 0all -oundation capa2ility in 'utodes# Revit (tructure does not support an over)an/ at its ends. 1)e 2est solution is to use t)e -oundation sla2 -eature in t)e %<. or 'P.. >ou can create t)em usin/ t)e 'utodes#.Revit.Creation.Document.4e0Bloor56 met)ods. Bor t)e (1R<C1<R'DRBDOORR'4'D>VE(R'(. >ou 0ill 0ant to use ''R,at or ''R(la2On%rade -or -oundation or ''R(la2 i- it is a -loor.

10