revit二次开发必用9个最佳实践

Revit二次开发必用的9个最佳实践叶雄进Joe

YeDevTech

China,

Manager首届中国开发者训练营——DevCamp

China

1st关于讲师叶雄进Joe

YeJoe.Ye@DevTech

China，SupervisorADN

DevTech部门10+年AEC行业软件经验2007-今2002-07Autodesk软件开发咨询土木行业软件研发支持的APIsRevitAutoCAD

ArchitectureAutoCADAbout

the

author

–

Arnošt

LöbelMasters

in

structuralengineeringA

Software

programmer

for20+

yearsWith

Autodesk

and

Revit

since2006API

design,

Transactions,Events,

Updaters,

Delegates,External

Services,

DocumentExport,

Exceptions,

EditScopes,

InteroperabilityRevit

API

基础块这次课程我们将涵盖几个有关Revit

API框架的重要规则.虽我们不会深入到每一个谈到的框架，我们尽可能地指出那些很可能误解或不是不为人知道的知识点。学习目标：9个最佳实践学习完本课程后,你将会理解并知道如何使用这些:模型重生成命令的事务模式外部命令（无实践）API的界线对象和防火墙事务形态对象的有效性事件，回调和模型更新器文档的可修改性对象的生命周期1.

模型更新再也没有模型更新模式了（>=2013)自动更新模式不能再用，不可声明手动更新模式形同虚设关于模型更新，牢记:当需要的时候，程序员可以调用更新，但是要求在事务范围内调用发生修改的模型在再次读取之前需要更新（楼板开洞）智能模型更新–只刷新需要刷新的单独的模型更新有时候还是不够的一些情形下，需要提交事务方能彻底刷新模型提交事务能彻底的刷新模型2.命令的事务模式事务模式控制外部命令中的事务是如何完成的自动模式:Automatic不推荐用;保留是因为兼容性的缘故有其方便性,事实上只有缺点手动模式:Manual推荐使用客户完全控制事务和事务组一个命令中可以包含多个事务，基本事务只能是并列关系事务可有自定义的名字，在undo和Redo中可以看到的就是事务名只读模式:Read-only有效的防止文档被修改(任何人!)3.外部命令：External

Commands命令只有在如下条件下才能启动:没有命令正在执行;没有编辑模式或非编辑器模式当前模型文件没有事务或事务组处于打开状态Revit无法保证命令对象的生存期应当注意：当在全局范围使用命令类的成员变量时对API的访问只能放在命令里面(并且只能从同一个线程中)当命令返回“failed”，放弃所做的全部修改每一个命令都被一个API防火墙（Firewall）所包围违反防火墙的命令将被全部放弃4.界限对象-Transaction，StaireEditScope对象具有明确的生存期通常具有开始/结束或启动/完成或类似的方法他们都有析构函数,因此可以显示地销毁例子–所有的事务（Transaction），楼梯修改范围（StairsEditScope)将来会有更多类似的对象具有生存期的对象需要“关闭”当从API返回到Revit时，Revit会去检查析构函数隐式的关闭这些界线对象。但是他们需要被激起最好的方式来确认界线对象关闭:

“use”申命栈变量C++/CLI

（Transaction

trans;trans.Start(“command’);)using

块C#：Using（Transaction

trans=new

Transaction(doc))or

Using

&End

UsingVB(与C#类似）界线范围对象的例子using(

Transaction

trans

=

new

Transaction(doc,"task")

){trans.Start();methodModifyingDocument(doc);trans.Commit();}若需要，RollBack

仍然可以被调用Using

块可以嵌套若需要，异常（

Exceptions

）仍然可以被处理5.

API调用防火墙它能保证外部任务恰当地完成包含（但是不限于）所有的界线对象需要关闭它包容所有的API调用（所有的API调用都在防火墙的管理下）特别是那些允许拥有自己事务的API调用命令退出时，不允许当前文档中任何对象没有关闭若那种情形发生，程序会显出一个失败在切换当前文档时，若当前文档允许修改:之前的文档一定是没有活动事务5

API

上下文环境（Context）API调用可以嵌套,例如:–

Revit

可能调用一个命令…–激活一个事件处理…–激活另一个事件处理…–导致模型动态更新被调用被激活的方法可能位于不同的程序中Revit

保留了执行程序的先进后出栈（FILO)Revit知道最高级别的运行程序有时候使用它来赋予或拒绝某些特定的操作(如.修改模型更新器)第一级别可执行命令会为错误担责，如果发生错误，这个命令所做的改动也将全部回滚6.

事务APIRevit

API有3

个“事务形态”:

Transaction当修改文档时需要TransactionGroup可以把几个事务组合成一个块(一次“un-do”把几个事务的修改全部取消)只能在事务之外启动TransactionGroup.SubTransaction••在一个Transaction之内的被标记为一系列的修改(需要时，可以“un-do”)只有在一个激活事务里面才能启动.所有事物模式都必须完成(i.e.,范围必须关闭!)值得注意的不同点Transaction事务提交后驻留在文档内.他们后来可以undone和redone.（撤销和恢复）最终用户可以从Undo/Redo列表中看到事务的名字.不能嵌套.任何时刻，一个文档中只允许有一个活动事务.Groups

和Sub-Transactions他们提交后就消失了，无法跟踪，也无法回退最终用户看不到他们.可以嵌套，一个需要完整的在另一个里面事务状态TransactionStatus

枚举常量，描述当前所处的事务状态.很多方法返回这个类型的值.Unitialized

–构造了，但未初始化Started

–事务启动了（调用了Start（））事务提交了事务回滚了或不成功的提交CommittedRolledBackPending

–在无模式错误处理的提交过程中特别注意#1:从事务提交中可返回RolledBack取决于多种错误处理决定(用户输入,API回调,等.)特别注意#2:可能从Commit（）和RollBack（）中返回Pending调用方不能修改，不能启动其它事务，也不能结束一个事务组仅可以返回，如果错误处理被设置成为无模式事务特征Transactions

代表对模型的最小改动单位他们是可逆的(可以撤销和恢复)任何时刻只能有一个活动事务3类API方法1.不需要事务的方法典型的是，从模型中读取信息的API他们也可以在事务里面运行，但要获取正确的数据，更新模型可能是需要的需要活动事务基本上所有修改模型的方法其中有些不是那么明显(如：导出)–一般帮助文档会注明一定不需事务的方法例如:保存（Save）,另存为SaveAs,

Close,视图切换等.,一些族操作,一些导出操作调用这些方法之前一定要结束之前的事务自动事务模式的命令会自动处理这种情况组Assimilation（合并）vs.Committing（提交）两个方法都能结束并提交一个事务组.区别在于:TransactionGroup.Commit()对组内已经提交的transactions没有直接影响.这个组会消失如同它从来没有存在过一般.TransactionGroup.Assimilate(),将已经关闭的几个事务合并成一个事务在融合完成后，只有一个事务.融合过程“简化”了融合事务中的子项融合后的事务名字就是事务组的名字(除非组内只有一个事务–此时就保留该唯一组的名字)注意,当融合结束后,事务组将会被遗忘.没有办法使之复活.事务挂起（

Pending）挂起事务需要提交或回滚,但是由于没有解决的故障，无法立即完成。.最终客户须要决定如何解决这个失败问题.模式vs.

无模式故障处理模式是默认的，API用户被期待首先使用模式.

模式时,在事务结束之前，错误处理已经完成了,因此这个可以保证事务不能挂起.在modeless

模式,若错误处理必须要解决故障，它将会把控制权归还给调用者来做决定，但是事务的状态将会处于挂起状态直到故障都解决.事务状态会自动更新当挂起最终完成.事务挂起只能在无模式情况下才会发生事务终结者（Transaction

Finalizer）挂起事务最后完成时，为了被通知到，当提交或回退一个事务时，事务的所有者可以传入一个TransactionFinalizer接口的实例.一个非常简单的接口:a)

OnCommitted

(String

transactionName)b)

OnRolledBack

(String

transactionName)当回调函数被调用时,事务已经结束，并设置了其状态.理论上讲,这个接口可以再次重启事务.典型用法挂起事务最终完成后，关闭事务组特别注意如果终结者重启事务，,他将不会改变从Commit/RollBack方法的返回状态文档可修改性文档可以修改在一个活动事务内，并且不是只读的状态如果文档是只读的将会是永久或暂时处于只读状态文档是只读文件这个属性只是指向实际的磁盘文件为了能启动一个事务:文档不能处于只读状态并且文档不能处于可修改状态尝试事务的可用性检查修改模型现在是否可能if(

document.IsModifiable){MakeChanges();}检查事务或事务组能否启动if(

!(document.IsModifiable||document.IsReadOnly)

){using(

Transactiontrans=

newTransaction(document)){trans.Start(

"doingsomething");MakeChanges();trans.Commit();}}7.

对象有效性（Element

validity）一个对象停止存在，当:对象删除

创建未完成删除对象的撤销对象创建事务回滚了内部对象从物理上销毁了(e.g.文档关闭)对象复活当:删除的对象的命令被取消对象创建被恢复(这个复活对只对Element!)Revit将会抛出InvalidObjectException

如果企图访问一个不存在的对象(暂时或永久).测试对象可用性的例子1.private

void

ElementTest(Document

document,

Element

element)2.{string

name

=

element.Name;

//

OK,

read-only

calls

do

not

need

aTransactionusing(

Transaction

trans

=

new

Transaction

(document,

"deleting")

){trans.Start();

//

allowing

modifications

to

the

modelname

=

element.Name;

//

still

OK,

read-only

method

can

still

becalleddocument.Delete(element);

//

deletes

Revit

element,

not

the

managedobjecttry{name

=

element.Name;

//

error!

–

the

element

is

not

availableanymore;12.

}catch(

InvalidObjectException

ex

){TaskDialog.Show(

"Revit",

"Attempting

to

access

an

invalidelement."

);16.

}17.

trans.RollBack();

//

this

effectively

undoes

the

deletion18.

}19.

name

=

element.Name;

//

OK;

the

element's

back

in

the

model20.}托管对象的生命期许多对象是内部对象的封装托管对象一些例外：XYZ,UV,ElementId,WorksetId一些.NET封装对象拥有自己的内部对象，多数则没有简单通过using

块来控制对象的生命期.NET垃圾回收机制只能回收托管对象，但是无法回收内部对象…Revit不会立即删除内置对象的资源当时机成熟时，它会删除内置对象你可以明确的清理他们，调用Application.PurgeReleasedAPIObjects8.

API

事件事件处理函数调用是基于先来先处理的原则Pre-events

事件在post-events之前调用通过取消事件的进行，Pre事件过程能被停止Post-events

事件总会被启动文档级别的处理函数不再优先调用

处理函数不允许