BIM Skills: Exploring the Capabilities of Revit Secondary Development and Its API Applications

Article source: CSDN

Revit and RevitAPI

Revit is a software created for building information modeling (BIM), offering tailored BIM solutions for various architectural disciplines.

Parameterization refers to the relationships among all elements within the model, enabling coordination and change management functions within Revit. These connections can be automatically generated by the software or manually defined by designers during project development.

RevitAPI

Capabilities of RevitAPI:

• Access graphical data of the model.
• Access parameter data of the model.
• Create, modify, and delete model elements.
• Design custom plugin user interfaces to enhance functionality.
• Develop plugins to automate repetitive tasks.
• Integrate third-party applications.
• Perform various types of BIM analysis.
• Automatically generate project documentation.

1. First Application: Hello World

1. Create a New Project

Choose C# – Class Library in the new project dialog and name your project “Hello World”.

2. Add References

1) Add RevitAPI.dll from the Revit installation directory.

2) After adding the reference, right-click on RevitAPI.dll, select Properties, and set Copy Local to false.

3) Repeat the above steps to add RevitAPIUI.dll. Revit projects typically reference RevitAPI.dll, RevitAPIUI.dll, and RevitAddInUtility.dll.

3. Add Code

Here is a simple example:

using System;
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;
        }
    }
}

4. Build the Program

(1) Create an .addin manifest file

Create a new text file with the following content:

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<RevitAddIns>
    <AddIn Type="Command">
        <Assembly>E:C#sampleHelloWorldHelloWorldbinDebugHelloWorld.dll</Assembly>
        <AddInId>239BD853-36E4-461f-9171-C5ACEDA4E721</AddInId>
        <FullClassName>HelloWorld.Class1</FullClassName>
        <Text>HelloWorld</Text>
        <VendorId>ADSK</VendorId>
        <VendorDescription>Autodesk, www.autodesk.com</VendorDescription>
    </AddIn>
</RevitAddIns>

Save this file with a .addin extension in the folder C:ProgramDataAutodeskRevitAddins2018 (replace “2018” with your Revit version).

Note: The ProgramData folder is hidden by default. To view it, go to Control Panel > Folder Options > View tab, then select “Show hidden files, folders, and drives”.

(2) Debug the Add-in

In Visual Studio, open the project properties, go to the Debug tab, select “Start External Program,” and enter the path to Revit.exe. When you debug, Revit will launch automatically, and your “Hello World” add-in will be available under the “Add External Tools” menu.

2. External Commands and Applications

The RevitAPI.dll assembly provides access to database-level classes such as Application, Document, Element, and Parameter. The RevitAPIUI.dll contains interfaces for customizing the Revit UI, including IExternalCommand, IExternalApplication, Ribbon panels, and menu items.

To extend or customize Revit via API, developers must implement specific interfaces in their plugins: IExternalCommand, IExternalApplication, or IExternalDBApplication.

3. IExternalCommand: External Commands

(1) Basic Principle: An ExternalCommand activates when no other commands are running and Revit is not in edit mode. Selecting the plugin creates an external command object, executes the Execute method, and then destroys the object. Since the object is short-lived, data persistence between commands must be handled externally.

(2) Implementing IExternalCommand: To expand functionality through external commands, implement this interface and override the Execute method, which serves as the main entry point.

Interface summary:

// An interface to implement external commands in Revit.
public interface IExternalCommand
{
    // Overload to implement the external command.
    Result Execute(ExternalCommandData commandData, ref string message, ElementSet elements);
}

(3) Input Parameter: ExternalCommandData

This contains references to the application and views required by the command. All Revit data can be accessed directly or indirectly through this parameter.

UIApplication uiApplication = revit.Application;
Application application = uiApplication.Application;
UIDocument uiDocument = uiApplication.ActiveUIDocument;
Document document = uiDocument.Document;

(4) Output Parameter: message

During execution, external commands can set error messages via this parameter. If the command returns Result.Failed or Result.Canceled, the message will be displayed in the UI.

(5) Output Parameter: elements (ElementSet)

If the command fails or is canceled and the message is not empty, an error dialog will appear. Clicking “Show” will highlight the elements provided in this parameter.

(6) Return Value of Execute

The Execute method returns one of three states: Result.Succeeded, Result.Failed, or Result.Canceled. If not Succeeded, Revit will undo all changes made by the command.

public enum Result
{
    Failed = -1,
    Succeeded = 0,
    Canceled = 1
}

4. IExternalApplication: External Applications

Developers can create external applications by implementing IExternalApplication. Revit loads these plugins through .addin files.

This interface defines two methods: OnStartup and OnShutdown, allowing customization during Revit’s startup and shutdown processes.

// Interface to add external applications in Revit.
public interface IExternalApplication
{
    Result OnShutdown(UIControlledApplication application);
    Result OnStartup(UIControlledApplication application);
}

The UIControlledApplication parameter provides methods to access custom UI elements and register event handlers.

5. Database-Level External Applications

These applications handle general events at the database level. They implement the IExternalDBApplication interface, which allows subscribing to database events but not modifying the UI.

// Interface for DB-level external applications.
public interface IExternalDBApplication
{
    ExternalDBApplicationResult OnShutdown(ControlledApplication application);
    ExternalDBApplicationResult OnStartup(ControlledApplication application);
}

Typically, event handlers are registered during the OnStartup method.

6. .addin Files

(1) Registration

For Windows 7 users who want all logged-in users to access the add-ins, place the .addin files in C:ProgramDataAutodeskRevitAddins2018. The .addin files differ depending on the plugin type.

(2) Example .addin File for External Command

Replace the DLL path with your plugin location. The AddInId is obtained from the project’s AssemblyInfo.cs. The FullClassName is the namespace and class name.

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<RevitAddIns>
    <AddIn Type="Command">
        <Assembly>C:RevitProjectHelloWorldHelloWorldbinDebugHelloWorld.dll</Assembly>
        <AddInId>619fa21b-37c6-4efb-b886-91c24e30d13b</AddInId>
        <FullClassName>HelloWorld.Class1</FullClassName>
        <Name>HelloWorld</Name>
        <VendorId>ADSK</VendorId>
        <VendorDescription>Autodesk, www.autodesk.com</VendorDescription>
    </AddIn>
    <AddIn Type="Command">
        .......
    </AddIn>
    <AddIn Type="Command">
        .......
    </AddIn>
</RevitAddIns>

(3) .addin File for External Application

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<RevitAddIns>
    <AddIn Type="Application">
        <Assembly>C:Program FilesAutodeskRevit 2018RevitLookup.dll</Assembly>
        <ClientId>356CDA5A-E6C5-4c2f-A9EF-B3222116B8C8</ClientId>
        <FullClassName>RevitLookup.App</FullClassName>
        <Name>Revit Lookup</Name>
        <VendorId>ADSK</VendorId>
        <VendorDescription>Autodesk, www.autodesk.com</VendorDescription>
    </AddIn>
</RevitAddIns>

(4) .addin File for Database-Level External Application

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<RevitAddIns>
    <AddIn Type="DBApplication">
        <Assembly>C:Program FilesAutodeskRevit 2018RevitLookup.dll</Assembly>
        <ClientId>356CDA5A-E6C5-4c2f-A9EF-B3222116B8C8</ClientId>
        <FullClassName>RevitLookup.App</FullClassName>
        <Name>Revit Lookup</Name>
        <VendorId>ADSK</VendorId>
        <VendorDescription>Autodesk, www.autodesk.com</VendorDescription>
    </AddIn>
</RevitAddIns>

7. Transactions

[Autodesk.Revit.Attributes.Transaction(Autodesk.Revit.Attributes.TransactionMode.Manual)]

The TransactionMode controls how the Revit API framework manages transactions when executing external commands.

public enum TransactionMode
{
    // The API framework will not start a transaction (but will start an outer group
    // to roll back all changes if the external command fails). 
    // You must manage transactions, sub-transactions, and groups manually.
    Manual = 1,

    // No transaction or group will be started, and no transaction may be started
    // during the command's lifetime. This mode allows only read-only operations.
    ReadOnly = 2
}

Remarks: Commands with ReadOnly mode should not be visible when no document is active, as they cannot modify the model and will throw exceptions if attempting to start transactions or write data.

xuebim

Follow the latest BIM developments in the architecture industry, explore innovative building technologies, and discover cutting-edge industry insights.

← Scan with WeChat