Bimo.Tools
1.4.0
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
<PackageReference Include="Bimo.Tools" Version="1.4.0" />
<PackageVersion Include="Bimo.Tools" Version="1.4.0" />
<PackageReference Include="Bimo.Tools" />
paket add Bimo.Tools --version 1.4.0
#r "nuget: Bimo.Tools, 1.4.0"
#:package Bimo.Tools@1.4.0
#addin nuget:?package=Bimo.Tools&version=1.4.0
#tool nuget:?package=Bimo.Tools&version=1.4.0
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
Bimoattribute 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 | Versions 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. |
-
.NETStandard 2.0
- Newtonsoft.Json (>= 13.0.3)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.