revit二次開發(fā)必用9個最佳實踐

Revit二次開發(fā)必用的9個最佳實踐葉雄進(jìn)Joe

YeDevTech

China,

Manager首屆中國開發(fā)者訓(xùn)練營——DevCamp

China

1st關(guān)于講師葉雄進(jìn)Joe

YeJoe.Ye@DevTech

China，SupervisorADN

DevTech部門10+年AEC行業(yè)軟件經(jīng)驗2007-今2002-07Autodesk軟件開發(fā)咨詢土木行業(yè)軟件研發(fā)支持的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

基礎(chǔ)塊這次課程我們將涵蓋幾個有關(guān)Revit

API框架的重要規(guī)則.雖我們不會深入到每一個談到的框架，我們盡可能地指出那些很可能誤解或不是不為人知道的知識點。學(xué)習(xí)目標(biāo)：9個最佳實踐學(xué)習(xí)完本課程后,你將會理解并知道如何使用這些:模型重生成命令的事務(wù)模式外部命令（無實踐）API的界線對象和防火墻事務(wù)形態(tài)對象的有效性事件，回調(diào)和模型更新器文檔的可修改性對象的生命周期1.

模型更新再也沒有模型更新模式了（>=2013)自動更新模式不能再用，不可聲明手動更新模式形同虛設(shè)關(guān)于模型更新，牢記:當(dāng)需要的時候，程序員可以調(diào)用更新，但是要求在事務(wù)范圍內(nèi)調(diào)用發(fā)生修改的模型在再次讀取之前需要更新（樓板開洞）智能模型更新–只刷新需要刷新的單獨(dú)的模型更新有時候還是不夠的一些情形下，需要提交事務(wù)方能徹底刷新模型提交事務(wù)能徹底的刷新模型2.命令的事務(wù)模式事務(wù)模式控制外部命令中的事務(wù)是如何完成的自動模式:Automatic不推薦用;保留是因為兼容性的緣故有其方便性,事實上只有缺點手動模式:Manual推薦使用客戶完全控制事務(wù)和事務(wù)組一個命令中可以包含多個事務(wù)，基本事務(wù)只能是并列關(guān)系事務(wù)可有自定義的名字，在undo和Redo中可以看到的就是事務(wù)名只讀模式:Read-only有效的防止文檔被修改(任何人!)3.外部命令：External

Commands命令只有在如下條件下才能啟動:沒有命令正在執(zhí)行;沒有編輯模式或非編輯器模式當(dāng)前模型文件沒有事務(wù)或事務(wù)組處于打開狀態(tài)Revit無法保證命令對象的生存期應(yīng)當(dāng)注意：當(dāng)在全局范圍使用命令類的成員變量時對API的訪問只能放在命令里面(并且只能從同一個線程中)當(dāng)命令返回“failed”，放棄所做的全部修改每一個命令都被一個API防火墻（Firewall）所包圍違反防火墻的命令將被全部放棄4.界限對象-Transaction，StaireEditScope對象具有明確的生存期通常具有開始/結(jié)束或啟動/完成或類似的方法他們都有析構(gòu)函數(shù),因此可以顯示地銷毀例子–所有的事務(wù)（Transaction），樓梯修改范圍（StairsEditScope)將來會有更多類似的對象具有生存期的對象需要“關(guān)閉”當(dāng)從API返回到Revit時，Revit會去檢查析構(gòu)函數(shù)隱式的關(guān)閉這些界線對象。但是他們需要被激起最好的方式來確認(rèn)界線對象關(guān)閉:

“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

仍然可以被調(diào)用Using

塊可以嵌套若需要，異常（

Exceptions

）仍然可以被處理5.

API調(diào)用防火墻它能保證外部任務(wù)恰當(dāng)?shù)赝瓿砂ǖ遣幌抻冢┧械慕缇€對象需要關(guān)閉它包容所有的API調(diào)用（所有的API調(diào)用都在防火墻的管理下）特別是那些允許擁有自己事務(wù)的API調(diào)用命令退出時，不允許當(dāng)前文檔中任何對象沒有關(guān)閉若那種情形發(fā)生，程序會顯出一個失敗在切換當(dāng)前文檔時，若當(dāng)前文檔允許修改:之前的文檔一定是沒有活動事務(wù)5

API

上下文環(huán)境（Context）API調(diào)用可以嵌套,例如:–

Revit

可能調(diào)用一個命令…–激活一個事件處理…–激活另一個事件處理…–導(dǎo)致模型動態(tài)更新被調(diào)用被激活的方法可能位于不同的程序中Revit

保留了執(zhí)行程序的先進(jìn)后出棧（FILO)Revit知道最高級別的運(yùn)行程序有時候使用它來賦予或拒絕某些特定的操作(如.修改模型更新器)第一級別可執(zhí)行命令會為錯誤擔(dān)責(zé)，如果發(fā)生錯誤，這個命令所做的改動也將全部回滾6.

事務(wù)APIRevit

API有3

個“事務(wù)形態(tài)”:

Transaction當(dāng)修改文檔時需要TransactionGroup可以把幾個事務(wù)組合成一個塊(一次“un-do”把幾個事務(wù)的修改全部取消)只能在事務(wù)之外啟動TransactionGroup.SubTransaction??在一個Transaction之內(nèi)的被標(biāo)記為一系列的修改(需要時，可以“un-do”)只有在一個激活事務(wù)里面才能啟動.所有事物模式都必須完成(i.e.,范圍必須關(guān)閉!)值得注意的不同點Transaction事務(wù)提交后駐留在文檔內(nèi).他們后來可以undone和redone.（撤銷和恢復(fù)）最終用戶可以從Undo/Redo列表中看到事務(wù)的名字.不能嵌套.任何時刻，一個文檔中只允許有一個活動事務(wù).Groups

和Sub-Transactions他們提交后就消失了，無法跟蹤，也無法回退最終用戶看不到他們.可以嵌套，一個需要完整的在另一個里面事務(wù)狀態(tài)TransactionStatus

枚舉常量，描述當(dāng)前所處的事務(wù)狀態(tài).很多方法返回這個類型的值.Unitialized

–構(gòu)造了，但未初始化Started

–事務(wù)啟動了（調(diào)用了Start（））事務(wù)提交了事務(wù)回滾了或不成功的提交CommittedRolledBackPending

–在無模式錯誤處理的提交過程中特別注意#1:從事務(wù)提交中可返回RolledBack取決于多種錯誤處理決定(用戶輸入,API回調(diào),等.)特別注意#2:可能從Commit（）和RollBack（）中返回Pending調(diào)用方不能修改，不能啟動其它事務(wù)，也不能結(jié)束一個事務(wù)組僅可以返回，如果錯誤處理被設(shè)置成為無模式事務(wù)特征Transactions

代表對模型的最小改動單位他們是可逆的(可以撤銷和恢復(fù))任何時刻只能有一個活動事務(wù)3類API方法1.不需要事務(wù)的方法典型的是，從模型中讀取信息的API他們也可以在事務(wù)里面運(yùn)行，但要獲取正確的數(shù)據(jù)，更新模型可能是需要的需要活動事務(wù)基本上所有修改模型的方法其中有些不是那么明顯(如：導(dǎo)出)–一般幫助文檔會注明一定不需事務(wù)的方法例如:保存（Save）,另存為SaveAs,

Close,視圖切換等.,一些族操作,一些導(dǎo)出操作調(diào)用這些方法之前一定要結(jié)束之前的事務(wù)自動事務(wù)模式的命令會自動處理這種情況組Assimilation（合并）vs.Committing（提交）兩個方法都能結(jié)束并提交一個事務(wù)組.區(qū)別在于:TransactionGroup.Commit()對組內(nèi)已經(jīng)提交的transactions沒有直接影響.這個組會消失如同它從來沒有存在過一般.TransactionGroup.Assimilate(),將已經(jīng)關(guān)閉的幾個事務(wù)合并成一個事務(wù)在融合完成后，只有一個事務(wù).融合過程“簡化”了融合事務(wù)中的子項融合后的事務(wù)名字就是事務(wù)組的名字(除非組內(nèi)只有一個事務(wù)–此時就保留該唯一組的名字)注意,當(dāng)融合結(jié)束后,事務(wù)組將會被遺忘.沒有辦法使之復(fù)活.事務(wù)掛起（

Pending）掛起事務(wù)需要提交或回滾,但是由于沒有解決的故障，無法立即完成。.最終客戶須要決定如何解決這個失敗問題.模式vs.

無模式故障處理模式是默認(rèn)的，API用戶被期待首先使用模式.

模式時,在事務(wù)結(jié)束之前，錯誤處理已經(jīng)完成了,因此這個可以保證事務(wù)不能掛起.在modeless

模式,若錯誤處理必須要解決故障，它將會把控制權(quán)歸還給調(diào)用者來做決定，但是事務(wù)的狀態(tài)將會處于掛起狀態(tài)直到故障都解決.事務(wù)狀態(tài)會自動更新當(dāng)掛起最終完成.事務(wù)掛起只能在無模式情況下才會發(fā)生事務(wù)終結(jié)者（Transaction

Finalizer）掛起事務(wù)最后完成時，為了被通知到，當(dāng)提交或回退一個事務(wù)時，事務(wù)的所有者可以傳入一個TransactionFinalizer接口的實例.一個非常簡單的接口:a)

OnCommitted

(String

transactionName)b)

OnRolledBack

(String

transactionName)當(dāng)回調(diào)函數(shù)被調(diào)用時,事務(wù)已經(jīng)結(jié)束，并設(shè)置了其狀態(tài).理論上講,這個接口可以再次重啟事務(wù).典型用法掛起事務(wù)最終完成后，關(guān)閉事務(wù)組特別注意如果終結(jié)者重啟事務(wù)，,他將不會改變從Commit/RollBack方法的返回狀態(tài)文檔可修改性文檔可以修改在一個活動事務(wù)內(nèi)，并且不是只讀的狀態(tài)如果文檔是只讀的將會是永久或暫時處于只讀狀態(tài)文檔是只讀文件這個屬性只是指向?qū)嶋H的磁盤文件為了能啟動一個事務(wù):文檔不能處于只讀狀態(tài)并且文檔不能處于可修改狀態(tài)嘗試事務(wù)的可用性檢查修改模型現(xiàn)在是否可能if(

document.IsModifiable){MakeChanges();}檢查事務(wù)或事務(wù)組能否啟動if(

!(document.IsModifiable||document.IsReadOnly)

){using(

Transactiontrans=

newTransaction(document)){trans.Start(

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

對象有效性（Element

validity）一個對象停止存在，當(dāng):對象刪除

創(chuàng)建未完成刪除對象的撤銷對象創(chuàng)建事務(wù)回滾了內(nèi)部對象從物理上銷毀了(e.g.文檔關(guān)閉)對象復(fù)活當(dāng):刪除的對象的命令被取消對象創(chuàng)建被恢復(fù)(這個復(fù)活對只對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.}托管對象的生命期許多對象是內(nèi)部對象的封裝托管對象一些例外：XYZ,UV,ElementId,WorksetId一些.NET封裝對象擁有自己的內(nèi)部對象，多數(shù)則沒有簡單通過using

塊來控制對象的生命期.NET垃圾回收機(jī)制只能回收托管對象，但是無法回收內(nèi)部對象…Revit不會立即刪除內(nèi)置對象的資源當(dāng)時機(jī)成熟時，它會刪除內(nèi)置對象你可以明確的清理他們，調(diào)用Application.PurgeReleasedAPIObjects8.

API

事件事件處理函數(shù)調(diào)用是基于先來先處理的原則Pre-events

事件在post-events之前調(diào)用通過取消事件的進(jìn)行，Pre事件過程能被停止Post-events

事件總會被啟動文檔級別的處理函數(shù)不再優(yōu)先調(diào)用

處理函數(shù)不允許