C# Revit二次开发基础/核心编程---RevitAPI基础
一、本节课程
yunyou.ke.qq.com 提供。
C# Revit二次开发基础/核心编程---RevitAPI基础
二、本节要讲解的知识点
Revit API的概述、基础以及第一个应用程序
- 具体内容
0.0了解Revit和Revit API
Revit三维、附加信息的三维模型
Revit API ：应用程序开发接口，Application Programming Interface ，使用.NET相关的语言来编程，VB.NET C# C++/CLI，F#。
建议进行Revit 二次开发编程之前熟悉一下Revit产品。
帮助你设计与Rebvit 产品一直的软件界面、快速理解API中的类和成员、指导不用Revit API 编程，Revit提供了哪些功能。
0.1 Revit API可以做什么
访问模型的图形数据。
访问模型的参数数据。
创建、修改、删除模型元素。
创建插件UI进行增强。
创建插件完成对重复自有工作的自动化。
集成第三个程序。
执行一切种类的BIM分析。
如何自动创建项目文档。
1、第一个应用程序Hello World
- Create a new project
选择新建项目中的C#–类库，建立项目名称为“HelloWorld”。
（2）Add Reference
1）在Revit安装路径中添加RevitAPI.dll。
2）添加引用后，右键选择 RevitAPI.dll属性，将复制本地种的true改为false。
3）RevitAPIUI.dll 按以上步骤添加。
（3）Add Code
| using System; using System.Collections.Generic; using System.Linq; using System.Text; using System.Threading.Tasks; using Autodesk.Revit.UI; using Autodesk.Revit.DB;
namespace HelloWorld { [Autodesk.Revit.Attributes.Transaction(Autodesk.Revit.Attributes.TransactionMode.Manual)] public class Class1 : IExternalCommand { public Autodesk.Revit.UI.Result Execute(ExternalCommandData revit, ref string message, ElementSet elements) { TaskDialog.Show("Revit", "Hello World"); return Autodesk.Revit.UI.Result.Succeeded; } } } |
- Build the Program
（5）Create a .addin manifest file
在C#中新建一个文本文件，将代码写入
|
<RevitAddIns> <Assembly>E:\C#\sample\HelloWorld\HelloWorld\bin\Debug\HelloWorld.dllAssembly> //此处的HelloWorld.dll在项目生成后才会有，开始看不到 <AddInId>239BD853-36E4-461f-9171-C5ACEDA4E721AddInId> //此处的ID在解决方案管理器项目中Properties的AssemblyInfo.cs中可以查看 <FullClassName>HelloWorld.Class1FullClassName> //此处的HelloWorld为项目名，Class1为类名 <Text>HelloWorldText> <VendorId>ADSKVendorId> <VendorDescription>Autodesk, www.autodesk.comVendorDescription> AddIn> RevitAddIns> |
- 将文本格式保存在.addin格式，并保存在C:\ProgramData\Autodesk\Revit\Addins\2018（2018为目前revit的版本）
注：C:\ProgramData为隐藏文件，若要显示，步骤如下：
组织–文件夹和搜索选项–查看–显示隐藏的文件、文件夹和驱动器 - Debug the Add-in
在解决方案资源管理器中，将项目的内容展示出来，点击其中的Properties，窗口会出现。
击其中的调试（Debug），选择启动外部程序，将revit.exe的路径写出来即可。
最后进行调试，调试时会自动开启revit软件，在添加外部工具中可找到helloworld。
2、外部命令和外部应用
RevitAPI.dll程序集包括了访问Revit中DB级别的Application、Document、Element、以及Parameter方法。RevitAPIUI.dll包括了所有操作和定制Revit UI的接口，包括了：IExternalCommand、IExternalApplication、Selection、菜单RibbonPanel、RibbonItem、以及其子类。想通过API 来访问或扩展Revit，需要用户在自己的插件中实现特殊的接口，就是IExternalCommand、IExternalApplication、IExternalDBApplication。
3、IExternalCommand外部命令
（1）基本原理：如果Revit没有其他命令在调用，或者是没有处于编辑模式，ExternalCommand会被激活。一旦插件被选中，外部命令对象就会被创建出来，并且执行Execute函数。执行完毕后，外部命令对象就被销毁。在两个命令之间数据不能保存在对象中，要通过其他方式来保存。
（2）IExternalCommand,用户通过外部命令来拓展功能的话，必须实现这个接口。重载Execute函数。作为外部命令的主函数来调用。
| // // 摘要: // An interface that should be implemented to provide the implementation for a Revit // add-in External Command. // // 备注: // To add an external command to Autodesk Revit the developer should implement an // object that supports the IExternalCommand interface. public interface IExternalCommand { // // 摘要: // Overload this method to implement and external command within Revit. // // 参数: // commandData: // An ExternalCommandData object which contains reference to Application and View // needed by external command. // // message: // Error message can be returned by external command. This will be displayed only // if the command status was "Failed". There is a limit of 1023 characters for this // message; strings longer than this will be truncated. // // elements: // Element set indicating problem elements to display in the failure dialog. This // will be used only if the command status was "Failed". // // 返回结果: // The result indicates if the execution fails, succeeds, or was canceled by user. // If it does not succeed, Revit will undo any changes made by the external command. Result Execute(ExternalCommandData commandData, ref string message, ElementSet elements); } |
public Autodesk.Revit.UI.Result Execute(ExternalCommandData revit, ref string message, ElementSet elements)
{
TaskDialog.Show("Revit", "Hello World");
return Autodesk.Revit.UI.Result.Succeeded;
}
（3）输入参数 ExternalCommandData
包含了外部命令所需要的Application以及一些视图的引用。在外部命令中，所有的Revit的数据都可以通过这个参数直接或者间接的取到。
UIApplication uiApplication =revit.Application;
Application application=uiApplication.Application;
UIDcument uiDocument=uiApplication.ActiveUIDocument;
Document document=uiDocument.Document;
（4）输出参数message
外部命令可以通过这个参数返回执行过程中的错误信息。这个参数作用于整个外部命令的执行过程，用户可以在外部命令执行过程中的任何时候给这个信息设值或者追加信息。当外部命令的Execute函数返回Autodesk.Revit.UI.Result.Failed或者Autodesk.Revit.UI.Result.Canceled，这个错误信息将被显示在UI上。
（5）输出参数elements（ElementSet）
当外部命令返回Autodesk.Revit.UI.Result.Failed或者Autodesk.Revit.UI.Result.Canceled并且message参数不为空的时候，错误或者警告对话框会弹出来，点击上面的显示按钮，elements参数中的元素将被高亮显示。
（6）Execute函数的返回值
表示外部命令的执行状态，有三种情况：Autodesk.Revit.UI.Result.Succeeded，Autodesk.Revit.UI.Result.Failed或者Autodesk.Revit.UI.Result.Canceled
如果返回不是Succeeded ，那么Revit会把外部命令所做的所有操作和修改都撤销。
| // 摘要: // Informs Autodesk Revit of the status of your application after execution. public enum Result { // // 摘要: // The external application was unable to complete its task. Failed = -1, // // 摘要: // The external application completed successfully. Autodesk Revit will keep this // object during the entire Revit session. Succeeded = 0, // // 摘要: // Signifies that the external application is cancelled. Cancelled = 1 } |
4、IExternalApplication外部应用
插件开发者同样可以通过IExternalApplication来添加自己的应用，Revit同样通过.addin文件来识别和加载IExternalApplication的外部插件。
IExternalApplication接口有两个抽象函数OnStartup和OnShutdown。用户可以通过在实现了IExternalApplication的外部应用中重载OnStartup和OnShutdown函数，在Revit启动和关闭的时候定制所需要的功能。
| // // 摘要: // An interface that supports addition of external applications to Revit. // // 备注: // External applications are permitted to customize the Revit UI, and to add events // and updaters to the session. public interface IExternalApplication { // // 摘要: // Implement this method to execute some tasks when Autodesk Revit shuts down. // // 参数: // application: // A handle to the application being shut down. // // 返回结果: // Indicates if the external application completes its work successfully. Result OnShutdown(UIControlledApplication application); // // 摘要: // Implement this method to execute some tasks when Autodesk Revit starts. // // 参数: // application: // A handle to the application being started. // // 返回结果: // Indicates if the external application completes its work successfully. Result OnStartup(UIControlledApplication application); } |
参数 UIControlledApplication ：提供了访问定制UI和注册事件的方法。
- 数据库DB级别的外部应用
数据库DB级别的外部应用：它用于一般事件的处理。
| // // 摘要: // An interface that supports addition of DB-level external applications to Revit, // to subscribe to DB-level events and updaters. // // 备注: // DB-level applications are permitted to add DB-level events and updaters to the // session. They cannot create or modify UI. public interface IExternalDBApplication { // // 摘要: // Implement this method to execute some tasks when Autodesk Revit shuts down. // // 参数: // application: // Handle to the Revit Application object. // // 返回结果: // Indicates if the external db application completes its work successfully. ExternalDBApplicationResult OnShutdown(ControlledApplication application); // // 摘要: // Implement this method to execute some tasks when Autodesk Revit starts. // // 参数: // application: // Handle to the Revit Application object. // // 返回结果: // Indicates if the external db application completes its work successfully. // // 备注: // Typically, event handlers and updaters are registered in this method. ExternalDBApplicationResult OnStartup(ControlledApplication application); } |
6、addin文件
（1）注册
windows 7用户，如果希望所有登录用户都可以使用的话，要把.addin文件放在C:\ProgramData\Autodesk\Revit\Addins\2018\，三种方式的插件它的addin文件是有区别的。
（2）外部命令的addin文件示例
一个.addin文件可以包含过个插件。
|
.......
.......
|
（3）外部应用类型的addin文件
|
|
（4）DB级别的外部应用
|
7、Transaction
| [Autodesk.Revit.Attributes.Transaction(Autodesk.Revit.Attributes.TransactionMode.Manual)] |
TransactionMode，控制Revit API框架如何在调用外部命令时处理其中的事务。
| public enum TransactionMode { // // 摘要: // The API framework will not create a transaction (but will create an outer group // to roll back all changes if the external command returns a failure status). Instead, // you may use combinations of transactions, sub-transactions, and groups. You will // have to follow all rules regarding use of transactions and related classes. You // will have to give your transactions names, which will then appear in the undo // menu. Revit will check that all transactions (also groups and sub-transaction) // are properly closed upon return from an external command. If not, it will discard // all changes to the model. Manual = 1, // // 摘要: // No transaction (nor group) will be created, and no transaction may be created // for the lifetime of the command. The External command may use methods that only // read from the model, but not methods that write anything to it. Exceptions will // be thrown if the command either tries to start a transaction (or group) or attempts // to write to the model. // // 备注: // A command with this transaction mode should not be associated to a command visible // when there is no active document. The command will not be permitted to be started. ReadOnly = 2 }
|
四、总结
1、Revit插件的三种实现方式：外部命令、外部应用和DB级别的外部应用。
2、三种插件的addin文件的写法。
3、写出Revit API 的HelloWorld程序。