Bimo.Tools 1.4.0

There is a newer version of this package available.
See the version list below for details.
dotnet add package Bimo.Tools --version 1.4.0
                    
NuGet\Install-Package Bimo.Tools -Version 1.4.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Bimo.Tools" Version="1.4.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Bimo.Tools" Version="1.4.0" />
                    
Directory.Packages.props
<PackageReference Include="Bimo.Tools" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Bimo.Tools --version 1.4.0
                    
#r "nuget: Bimo.Tools, 1.4.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Bimo.Tools@1.4.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Bimo.Tools&version=1.4.0
                    
Install as a Cake Addin
#tool nuget:?package=Bimo.Tools&version=1.4.0
                    
Install as a Cake Tool

Bimo.Tools

Bimo.Tools is a .NET Standard 2.0 library that provides common types, interfaces, and attributes used when writing custom commands for the BIMO plugin. This library contains reusable abstractions that simplify the development of user commands and related tool functionalities.

Learn about BIMO Toolbar for Autodesk Revit at bimo.tools.

Features

  • Common Abstractions: Provides essential interfaces such as ISettings<T> and others that help standardize how settings are defined and used across your tools.
  • Custom Attributes: Includes attributes like BimoAttribute, OriginalUserCommandAttribute, ExecuteOptionsAttribute, etc. These attributes help annotate methods and classes to specify metadata (such as GUIDs, display names, and execution options) used during runtime generation of commands.
  • Extensibility: Designed to serve as the core dependency for building extensible Revit plugins, enabling dynamic command generation and integration via a NuGet package.

Installation

Packages are delivered publicly through nuget.org. Restore uses the standard nuget.org feed without credentials or BIMO source access. A package release must be published before it can be restored; this README does not imply that the initial candidate 1.1.0 has already been published.

Pin the matching approved package version in your project, then run dotnet restore:

<PackageReference Include="Bimo.Tools" Version="[1.1.0]" />

Build dependencies do not replace the DLLs supplied by the installed BIMO Toolbar. Use the host built from the package's recorded source commit; an unchanged assembly version is not a compatibility promise for older hosts. Exclude Bimo.Tools.dll and its satellites from the client command archive. The release manifest records the source commit and package/DLL SHA-256 hashes. Bimo.Shared remains internal to the BIMO solution and is not a dependency of Trace Facade.

Getting Started

To use Bimo.Tools in your project, simply reference the package and use the provided abstractions to create your commands.

Shared command runtime (development)

Bimo.Tools.Commands supplies the public command authoring contracts: handlers, reports, status and invocation-aware selection. The execution runtime and its middleware, invocation context and settings-DI lifecycle are internal to Bimo.RevitApp; command authors do not configure or depend on them. Authors write new commands as static classes with [Bimo] entrypoints. Every supported static [Bimo] method returning void, Autodesk Result or a public CommandReport subtype receives a generated direct-call ICommandHandler and the same thin Ribbon adapter. Any ISettings<T> parameter must match BimoAttribute.SettingsType; other parameters are services. Declared settings metadata may also be used without a direct settings parameter. Generic, overloaded and by-reference entrypoints are unsupported. The runtime provides a detached settings snapshot per invocation. void produces only a success status; Autodesk succeeded/cancelled/failed outcomes retain their status in CommandStatusReport. These status-only outcomes do not add a final Ribbon dialog or manufacture operation data. Structured reports default to succeeded and own their operation data. The configured host middleware normalizes cancellation/errors once; a direct handler call can still throw. Autodesk result mapping stays in the host.

The generator translates [Bimo] into ordinary host type attributes: Guid, DisplayName, optional Presets, icon, capabilities and execution binding. Existing built-in command classes use the same attribute contract without BimoAttribute. Built-in and user command delivery share the execution contract. The host derives one internal CommandDefinition for discovery and Ribbon without constructing a command or executing its method. Wrappers have no definition property or metadata constructor. Normal host/generator fingerprint invalidation regenerates development wrappers; source method signatures remain unchanged.

The source SDK exposes optional BimoAttribute.CatalogId for static methods. Both generators emit host-owned class-level catalog metadata on wrappers; the host reads the embedded <source namespace>.Resources.<id>Catalog resource from the source assembly via the existing source-type binding. This does not publish installed user DLLs to the website. It is absent from NuGet 1.1.0; see catalog authoring and publication.

Inside the host, ExternalCommand owns the common native entrypoint and exposes CreateHandler. Two sibling subclasses supply the existing authoring bindings: BimoCommandRuntimeExternalCommand<THandler> creates a generated direct-call handler; BimoCommandRuntimeExternalCommand adapts built-in OnExecute delegates and provides custom-dialog helpers. Ribbon and MCP obtain the same handler through CreateHandler. These host bases are not part of the static-command SDK.

Custom reports are optional. A compact command can return void or Result; the host supplies the standard result and available base metrics for both callers. Use a domain report only when the operation needs additional data or presentation. Use ICommandSelection for invocation element references and IUserNotifier for confirmation/errors. If returning a report, let Ribbon present its final dialog and optionally select committed result elements. The authoring contracts contain no Autodesk, host or transport dependency. All existing Ribbon command kinds and eligible approved MCP command execution use one host runtime; setup and presentation remain in the caller adapter. The host supplies the same detached settings snapshot to direct parameters and DI-created dependencies. Agent-origin invocations require explicit declared settings and cannot run Ribbon preparation. Transport admission and approval remain caller-owned.

The host runtime owns one DI scope per execution for both Ribbon and MCP, from caller setup through result handling. Handlers resolve their parameters within this scope; command instances do not retain the provider. Authors do not create scopes or manage service lifetimes. See the ownership decision in ADR-0006.

The host resolves both interaction contracts to one scoped caller implementation, including dependencies created by DI. Ribbon notifications retain the existing IUserNotifier API; Warn is a confirmation request, while Inform, SayError and DisplayResult are notifications. Agent notifications are collected with bounds instead of opening dialogs, and an additional Warn fails rather than automatically granting consent. Exact operation approval remains in the caller adapter. ICommandSelection.CanPromptForSelection denies native selection prompts in agent scopes; supplied references remain bound to the invocation document.

This is development source, not a released NuGet contract. Build the command, host and generator from the same checkout with #416/#418/#419. Existing installed void/Result user DLL entrypoints retain their signatures; the host regenerates their wrappers on the common path without rebuilding the user DLL. Generic MCP search/describe, approved trials and explicitly audited committed built-in/static execution are implemented in development; matching-artifact native acceptance remains in epic #415. See ADR-0006.

Command descriptions and client services (1.2.0)

A static [Bimo] entrypoint may set CatalogId = "example". The host generator adds its catalog marker to the wrapper; no catalog attribute is exposed by Tools. Descriptions are embedded in <source namespace>.Resources.exampleCatalog, with ShortDescription, Description, DescriptionRu and DescriptionFr keys. Use the existing English name. Setting CatalogId does not publish installed DLLs to the website.

Mark client implementation classes with [BimoService(typeof(IMyService))], or [BimoService] to resolve a concrete type. Internal implementations are supported with public constructors. Expose a public contract in the public entrypoint; keep its nested implementation graph internal. All marked client services have one instance per invocation and are disposed by the host scope on every exit. Client contracts must belong to the same configured source DLL; host replacement and duplicate mappings are errors. Constructors run only after policy/preparation, not during generation or registration. Do not use registration callbacks or resolve scoped services during startup. Registration visibility is shared across commands; each invocation has a separate lifetime.

This API requires the matching 1.2.0 package and host, not an installed 1.1.0 host. The new release is a coordinated SDK/host/client update; publication and installed Revit acceptance are recorded separately from source and candidate-package checks.

Required document for external commands (1.3.0 candidate)

An external static command may declare that it needs an active project document before BIMO opens settings or resolves the command's scoped services:

[Bimo(CommandGuid, RequiredDocument = CommandDocumentRequirement.Project)]
public static CommandReport Execute(IMyCommandService service) => service.Execute();

The generators translate this portable SDK enum to the host-owned RequiredDocumentAttribute on each generated command's base wrapper. Generated preset variants inherit the requirement. None is the default and declares no document restriction. Only None and Project are supported in this slice; unsupported values fail command generation.

This reuses the existing host document policy. If no project document is active, execution fails before opening the command settings or constructing client services. The host retains its existing Failed result and message for document admission; domain-specific errors inside the command are separate. No Document or Autodesk dependency is added to Bimo.Tools.

This is a 1.3.0 candidate, not a published or installed contract until the matching SDK, generator and BIMO host are released and validated together. The installed 1.2.0 host does not implement this metadata.

Settings input metadata

Static commands opt in to the first agent execution contract with [Bimo(..., SupportsAgentDryRun = true)] after auditing the operation. Business settings through SettingsType/ISettings<T> and domain reports are optional. A settings class needs no artificial DryRun property: the host owns that technical input and verifies rollback of a native outer transaction group, including inner checked commits. Use ICommandSelection, IUserNotifier and the host transaction/progress services for caller-specific behavior. MCP requires an explicit Boolean DryRun matching the declared capability, all supported primitive settings and 0–64 distinct element UniqueIds; an empty array never substitutes Ribbon selection or the whole document. External effects, edits in other documents and arbitrary direct native prompts are not intercepted by the trial group and prevent a safe opt-in. Revit checks inputs and revision before approval and execution; approval remains mandatory. Agent calls do not open setup/report dialogs, use active Ribbon selection, change the active preset or auto-confirm additional prompts. Complex/custom-converter settings remain unsupported. RoofToFloor is the first static reference; its detailed report is optional operation output, not a required authoring pattern. The built-in AllowWallJoin reference retains its compact selected-element processing call and returns only Result. The host supplies its trial and separately audited committed capabilities without a business-settings model. SupportsAgentDryRun alone enables trials only; static commands separately opt in to persistent execution with SupportsAgentCommit=true. RoofToFloor is the first static committed reference. A live descriptor with approved_execution accepts explicit DryRun=false; approved_dry_run descriptors require DryRun=true. Successful committed invocations assimilate the same outer group; canceled/failed operations roll back. These capabilities cannot be inferred from a command's presence in the catalog or Ribbon. MCP receives standard status/duration and optional middleware counters labelled as trial or execution observations, not a persistent model diff. This opt-in is development source, not a released SDK promise; see the migration inventory.

The final runtime audit records the current entrypoints, contracts and acceptance gates. Framework metrics and caller policies do not require authors to add infrastructure DTOs.

Optional warning before committed execution

Declare a fixed localized warning through the existing attribute:

[Bimo(CommandGuid,
    SupportsAgentDryRun = true,
    SupportsAgentCommit = true,
    CommitWarningResourceName = "MyCommands.Strings",
    CommitWarningResourceKey = "CreateWarning")]

Both resource fields are optional together and identify an embedded resource in the command assembly. The host captures the localized text and binds its digest to the revision. A missing, blank or oversized warning fails rather than silently omitting confirmation. Commands without warnings need no extra author code.

Ribbon confirms after settings preparation and before the handler. A declared Boolean DryRun=true skips the warning; without that property, Ribbon performs actual execution. MCP includes the installed warning in its existing approval for DryRun=false, without another dialog during execution. Additional Warn calls remain denied for agents. See the committed execution guide.

The single open Hello BIMO example combines its Message business setting, scoped client service and structured report. General settings-free void bindings remain supported and covered by generator and runtime fixtures. Optional domain reports must describe trial observations and must not expose rolled-back elements as persistent/selectable output references.

DynamoInputAttribute, DynamoInputKind, and DynamoInputMetadataKeys belong to Bimo.Tools.Attributes. They describe property editors and input metadata for generated graph settings. An audited configured graph may explicitly opt in via the host's DynCommandSource.SupportsAgentDryRun; its scalar business settings need no DryRun property or report class. First-slice limits and native checks: generated Dynamo trial.

These attributes also describe editors for static C# command settings. For example:

using Bimo.Tools.Attributes;

public sealed class FacadeSettings
{
    [DynamoInput("", DynamoInputKind.ScopeBoxSelection, "Scope Box")]
    public string ScopeBox { get; set; } = string.Empty;
}

The host provides the editor and document options. This contract does not reference Autodesk/Revit or Bimo.Shared; JSON metadata parsing uses Newtonsoft.Json 13.0.3.

The former Bimo.Shared.Attributes input types have been removed. Update imports and rebuild affected user DLLs against the matching updated BIMO host before deployment. Old binaries are not supported through forwarding or duplicate attributes. Enum numeric values and metadata/setting values remain unchanged. RevitVersionAttribute remains in Bimo.Shared.Attributes.

Correctable command input errors (1.4.0 candidate, unreleased)

The source SDK exposes Bimo.Tools.Commands.CommandInputException for expected user-correctable command input errors. Authors supply a localized, user-safe message, and may retain an inner exception for the private diagnostic log. The existing host ExceptionMiddleware classifies this as Failed (rather than Cancelled), reports the message exactly once through the caller-aware notifier, and does not open the unexpected-error dialog. There is no need to write a try/catch around the static [Bimo] entrypoint.

if (selectedElements.Count == 0)
    throw new CommandInputException("Select at least one supported element.");

Do not use the type for an actual user cancellation or an unexpected code/Revit failure. Do not put local file paths, sensitive identifiers, raw exception details or stack traces in the public message. This type is not part of the published 1.3.0 package: SDK 1.4.0, the matching host and downstream client packages must be validated and released together before external DLLs adopt it. See the host failure policy.

Transaction execution

Use the public extensions in Bimo.Tools.Services when dependent work must only continue after completion:

using Bimo.Tools.Services;

transactionManager.ExecuteAndEnsureCommitted("Create output", CreateOutput);
transactionManager.ExecuteAndEnsureRolledBack("Temporary changes", Calculate);

Both accept optional TransactionExecutionOptions. The rollback extension sets Rollback = true and copies failure-handling overrides without changing the caller's options. The commit extension rejects Rollback = true before execution. Confirmed commit rollback throws OperationCanceledException with a diagnostic cause containing the label and actual/expected status. Other unexpected statuses throw InvalidOperationException; action exceptions propagate unchanged. These extensions do not implement asynchronous completion for Pending.

Execution and result extensions, including EnsureCommitted / EnsureRolledBack, have one implementation here. English/Russian messages are embedded in this library and its ru satellite assembly. Bimo.Tools remains netstandard2.0 with no Autodesk/Revit or Bimo.RevitApp reference. The interface gains no members. Rebuilt user DLLs using these new public methods require the matching updated Bimo.Tools on the host; deploy its satellite resources as well.

Commands that receive ITransactionManager should use the result-bearing overload and verify that the operation committed. The options argument is optional; omitting it or passing null creates fresh defaults for that call: Rollback = false, ForceModalHandling = true, ClearAfterRollback = false.

TransactionExecutionResult result = transactionManager.ExecuteInTransaction(
    "Create output",
    CreateOutput
);

if (result.Status == TransactionExecutionStatus.RolledBack)
    throw new OperationCanceledException(
        "Output creation was rolled back.",
        new InvalidOperationException("Create output returned RolledBack; expected Committed.")
    );

if (!result.IsCommitted)
    throw new InvalidOperationException($"Unexpected transaction status: {result.Status}.");

For temporary changes, pass new TransactionExecutionOptions { Rollback = true } and require result.Status == TransactionExecutionStatus.RolledBack before consuming the calculation results. Other overrides remain explicit, for example new TransactionExecutionOptions { ClearAfterRollback = true }.

The cancellation example retains a cause for the BIMO command middleware to log at Warning and return Cancelled without a generic error window. Localize messages in real commands. The public result does not expose the original Revit failure details; the cause above records the transaction outcome.

Default change: ForceModalHandling changed from false to true, and ClearAfterRollback from true to false. This affects new TransactionExecutionOptions() too, including existing binaries that construct options without explicitly assigning those properties. Specify overrides to retain previous behavior. Explicit null now means defaults rather than an argument error.

The older void overload with a bool rollback parameter is retained for compiled commands, preserving its legacy nonmodal behavior. Its rollback argument is now required in source so a two-argument call selects the result-bearing overload without ambiguity. Existing compiled legacy calls already pass the boolean and keep working; newly compiled two-argument calls bind to the new overload and must inspect the result.

Explicit ForceModalHandling = false allows nonmodal handling and can return Pending; callers must manage completion before dependent operations. It does not delete or suppress Revit warnings; warning suppression requires a separate failure-processing policy.

Example: Defining a Custom Command

Below is an example of how you might define a user command using the provided attributes and interfaces:

using Bimo.Tools.Attributes;
using Bimo.Tools.Services;

public static class HelloWorldCommand
{
    [Bimo("YOUR_GUID_HERE", DisplayName = "Hello World", SettingsType = typeof(HelloWorldSettings))]
    public static void Execute(ISettings<HelloWorldSettings> settings)
    {
        // Your command logic here.
        // For example, display a message box or execute some business logic.
        Console.WriteLine(settings.Value.Message);
    }
}

public class HelloWorldSettings
{
    public string Message { get; set; } = "Hello from BIMO!";
}

In this example:

  • The Bimo attribute marks the command method with a unique identifier, display name and optional settings type.
  • The command is implemented as a static method and accepts settings of type ISettings<HelloWorldSettings>, allowing users to configure the command if needed.

License

This project is licensed under the MIT License. The full license is included in the package as LICENSE.

Contact

For questions or support, use the contact information at bimo.tools. The package is public; the BIMO source repository remains private.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.4.1 100 10/30/2026
1.4.0 94 10/30/2026
1.3.0 183 10/23/2026
1.2.0 106 10/22/2026
1.1.0 198 10/8/2026