RevitToolkit

The toolkit provides several ExternalEvent implementations to allow executing Revit API code from outside the Revit execution context (e.g., from a modeless window or a different thread). The toolkit handles all initialization automatically.

• ExternalEvent: A synchronous event. Calling Raise() queues the delegate to be executed in the next Revit event-processing cycle.
• ExternalEvent<T>: A synchronous event that accepts an argument of type T via Raise(T arg).
• AsyncExternalEvent: An asynchronous event. RaiseAsync() returns a Task that completes when Revit finishes the delegate. Warning: Do not use .Wait() or .Result on the Revit main thread as it will cause a deadlock; always use await.
• AsyncExternalEvent<T>: An asynchronous event that accepts an argument of type T.
• AsyncRequestExternalEvent<TResult>: An asynchronous event that returns a result of type TResult via RaiseAsync().
• AsyncRequestExternalEvent<T, TResult>: A generic asynchronous event that accepts an argument T and returns TResult.

// AsyncRequestExternalEvent<T, TResult> Example
private readonly AsyncRequestExternalEvent<ElementId, bool> _deleteWindowRequestEvent = new((application, elementId) =>
{
    var document = application.ActiveUIDocument.Document;
    using var transaction = new Transaction(document, "Delete window");
    transaction.Start();
    document.Delete(elementId);
    transaction.Commit();
    return true;
});

private async Task DeleteWindowAsync(ElementId elementId)
{
    var result = await _deleteWindowRequestEvent.RaiseAsync(elementId);
}

The [ExternalEvent] attribute eliminates boilerplate by automatically generating event properties for annotated methods in a partial class. The generator creates properties based on the method signature:

• void method: Generates IExternalEvent and IAsyncExternalEvent properties.
• Method with return value: Generates an IAsyncRequestExternalEvent<TResult> property.
• Method with UIApplication parameter: The generated events pass the UIApplication instance to the handler.
• Method with one extra parameter: Generates typed event properties (e.g., IExternalEvent<T>).
• Method with multiple extra parameters: Generates a sealed record containing the arguments and extension methods to call RaiseAsync using individual parameters.

Use [ExternalEvent(AllowDirectInvocation = true)] to allow the handler to be invoked directly on the calling thread when Revit is in API mode.

public partial class MyViewModel
{
    [ExternalEvent]
    private void DeleteWindow(UIApplication application, ElementId elementId)
    {
        // Implementation
    }
}

// Generates:
// IExternalEvent<ElementId> DeleteWindowEvent
// IAsyncExternalEvent<ElementId> DeleteWindowAsyncEvent

The toolkit provides context objects to access global application information and manage Revit's behavior using disposable scopes.

RevitApiContext (Database Level)

• BeginFailureSuppressionScope(): Automatically resolves all failures without user interaction. Use resolveErrors: false to cancel the transaction and undo all failed changes if a failure occurs.

RevitContext (UI Level)

• Properties: UiApplication, ActiveDocument, ActiveUiDocument, ActiveView, ActiveGraphicalView, IsRevitInApiMode.
• BeginDialogSuppressionScope(): Suppresses dialogs. You can specify a resultCode (e.g., TaskDialogResult.Ok) or provide a custom handler to decide the result based on the DialogId.

// Suppress failures and undo on error
using (RevitApiContext.BeginFailureSuppressionScope(resolveErrors: false))
{
    ModifyDocument();
}

// Suppress dialogs with a custom handler
using (RevitContext.BeginDialogSuppressionScope(args =>
{
    var result = args.DialogId == "TaskDialog_ModelUpdater" ? TaskDialogResult.Ok : TaskDialogResult.Close;
    args.OverrideResult((int)result;
}))
{
    LoadFamilies();
}

The toolkit provides base classes for Revit external applications with simplified method signatures and automatic dependency resolution.

• ExternalApplication: Implement IExternalApplication. Override OnStartup() and optionally OnShutdown().
• AsyncExternalApplication: Implement asynchronous startup/shutdown. Override OnStartupAsync() and optionally OnShutdownAsync(). Ideal for I/O-bound tasks during startup.
• ExternalDBApplication: Implement IExternalDBApplication. Use this when you do not need access to the Revit UI.

public class Application : AsyncExternalApplication
{
    public override async Task OnStartupAsync()
    {
        using var httpClient = new HttpClient();
        var configuration = await httpClient.GetStringAsync("https://api.example.com/config");

        var panel = Application.CreatePanel(configuration.PanelTitle);
        panel.AddPushButton<Command>(configuration.ButtonTitle);
    }

    public override async Task OnShutdownAsync()
    {
        await SaveSettingsAsync();
    }
}

The Nice3point.Revit.Toolkit.Analyzers package includes specific Roslyn analyzer rules for the ExternalEventGenerator to ensure correct implementation of Revit external events. In version 2027.0.0, the following rules are enforced:

| Rule ID   | Category               | Severity | Notes |
|------------|------------------------|----------|--------------------------------|
| RVTTK0001 | ExternalEventGenerator | Error    | Method returns Task or Task<T> |
| RVTTK0002 | ExternalEventGenerator | Warning  | Method is async void |
| RVTTK0003 | ExternalEventGenerator | Error    | Method is generic |
| RVTTK0004 | ExternalEventGenerator | Error    | Duplicate method overloads |
| RVTTK0005 | ExternalEventGenerator | Error    | Containing type is not partial |