Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Bimo.Tools.csproj
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

<AssemblyVersion>1.0.0.0</AssemblyVersion>
<FileVersion>$(AssemblyVersion)</FileVersion>
<PackageVersion>1.4.0</PackageVersion>
<PackageVersion>1.4.1</PackageVersion>
<Version>$(PackageVersion)</Version>

<Authors>BIMO Tools</Authors>
Expand Down
27 changes: 15 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,15 +13,15 @@ It provides command attributes, settings metadata, and host-provided service int

## Install the SDK

For new commands targeting the **BIMO Toolbar 0.46.0** contract set, use **Bimo.Tools 1.3.0**:
The latest published package is **Bimo.Tools 1.4.1**. Use it only with an installed BIMO host verified for its contracts, including the 1.4 expected-error handling:

```xml
<PackageReference Include="Bimo.Tools" Version="[1.3.0]" />
<PackageReference Include="Bimo.Tools" Version="[1.4.1]" />
```

Restore packages from the standard NuGet feed. You do not need access to BIMO's private application source to author a command.
For the **documented BIMO Toolbar 0.46.0 baseline**, continue using SDK **1.3.0** and the matching [Hello BIMO Quick Start](docs/quick-start.md) until you have verified a newer host. Restore packages from nuget.org without private repository access.

**Match the SDK to the installed host.** Package version, .NET Standard compatibility, and an unchanged assembly version are not guarantees of runtime compatibility with an older Toolbar.
**Match the SDK to the installed host.** Package version, .NET Standard compatibility, and an unchanged assembly version do not guarantee compatibility with an older Toolbar.

### SDK and Toolbar compatibility

Expand All @@ -30,20 +30,22 @@ Restore packages from the standard NuGet feed. You do not need access to BIMO's
| **1.1.0** | Documented baseline: **Toolbar 0.45.0 beta**. Historical baseline for the original Hello BIMO sample. |
| **1.2.0** | Adds command-description and client-service authoring contracts; requires a matching SDK/host combination. Do not assume support from the 0.45.0 host. |
| **1.3.0** | Supported by **Toolbar 0.46.0**. Includes resource-backed command descriptions, invocation-scoped client services, and project-document requirements checked before settings and service activation. |
| **1.4.0** | Introduces `CommandInputException` for expected, user-correctable errors; requires an updated host that recognizes this exception as `Failed` rather than `Cancelled`. |
| **1.4.1** | Documentation/README refresh of 1.4.0. Requires the same matching 1.4-compatible host; no new SDK API is introduced by this patch release. |

The [Toolbar 0.46.0 release notes](https://bimo.tools/releases) document the 1.3.0 contracts. Check the release notes and your installed Toolbar version before upgrading command DLLs. The host controls which commands can be invoked by an AI agent; installing the SDK alone does **not** grant agent execution permission.
The [BIMO release notes](https://bimo.tools/releases) document installed Toolbar versions. The previously verified 0.46.0/1.3.0 pairing does **not** prove 1.4.x host compatibility. Verify the deployed host before upgrading command DLLs. Installing the SDK alone does **not** grant AI-agent execution permission.

## Developer documentation

| Start with | What you will learn |
| --- | --- |
| **[Hello BIMO Quick Start](docs/quick-start.md)** | Build a verified command DLL, register it in Revit, edit a setting and run it from the Ribbon |
| **[C# command authoring guide](docs/command-authoring.md)** | Create your own command: identity and loading, settings, presets, scoped services, reports, Revit requirements, MCP capabilities and troubleshooting |
| **[Example project](examples/HelloBimo/)** | Inspect the complete SDK 1.3.0 source and project file |
| **[Example project](examples/HelloBimo/)** | Inspect the separately pinned, verified SDK 1.3.0 sample project |

### Build your first command

**Hello BIMO with SDK 1.3.0:** The sample and the published-package smoke test both reference **[1.3.0]**. This open project is the sole home of `HelloWorldTools`, moved out of BIMO Samples; the private project no longer compiles these greeting commands. The example covers settings, scoped client services, structured reports and project-document requirements. See the [Quick Start](docs/quick-start.md) for build, loading and test instructions.
**Hello BIMO uses SDK 1.3.0 intentionally.** The example and published-package smoke consumer remain pinned to **[1.3.0]** and target the documented Toolbar 0.46.0 baseline. They demonstrate settings, scoped client services, reports and project-document requirements. They have **not** been migrated to 1.4.1 or revalidated against a 1.4-compatible installed host. Follow the [Quick Start](docs/quick-start.md) for the existing tested exercise.

In outline:

Expand All @@ -63,6 +65,7 @@ Starting with **Toolbar 0.46.0**, configured DLL commands load at Revit startup
- **Settings and input metadata:** contracts for command configuration and generated editors.
- **Host-provided services:** interfaces for notifications, settings, transactions, and progress, where supported by the installed host.
- **Structured command results:** public report and status contracts for commands that need them.
- **Correctable command errors (1.4+):** `CommandInputException` with a localized, user-safe message, classified as `Failed` by a compatible host without an entrypoint `try/catch`.

The SDK does not include the Autodesk Revit API, BIMO host internals, or an MCP server. Using Autodesk API types requires the appropriate separate Revit references and host compatibility.

Expand All @@ -73,7 +76,7 @@ dotnet build Bimo.Tools.csproj --configuration Release
dotnet run --project tests/Bimo.Tools.Smoke/Bimo.Tools.Smoke.csproj --configuration Release -p:UsePublishedPackage=false

dotnet run --project tests/Bimo.Tools.Smoke/Bimo.Tools.Smoke.csproj --configuration Release -p:UsePublishedPackage=true
dotnet pack Bimo.Tools.csproj --configuration Release
dotnet pack Bimo.Tools.csproj --configuration Release -p:GeneratePackageOnBuild=false
```

The example and smoke consumer default to published **NuGet 1.3.0**. Pass
Expand All @@ -82,15 +85,15 @@ SDK: the global property selects project references consistently in both project
Explicit `true` selects package references throughout the graph. Run the two
commands above separately to validate both providers.

Public CI tests SDK source plus an anonymous **NuGet 1.3.0** consumer. This does **not** publish NuGet packages or validate execution in an installed Revit host.
Public CI tests the current SDK source and the separately pinned **NuGet 1.3.0** Hello BIMO consumer. This is deliberate: it does **not** establish 1.4.1 compatibility with an installed Revit host, publish packages or validate live Revit execution.

### Public source snapshot vs. released package

This repository is a **reviewed public snapshot** extracted from the private BIMO monorepo, which remains the source of truth during the current extraction stage.

- The public `Bimo.Tools.csproj` now specifies **1.3.0**, synchronized from the reviewed private SDK through [public sync PR #5](https://github.com/BIMO-Tools/Bimo.Tools/pull/5).
- The Hello BIMO sample and published-package smoke test are pinned to **1.3.0**.
- The **1.3.0 NuGet/host contract** is documented by the Toolbar 0.46.0 release; the synchronized public sources do not, by themselves, prove that their bytes match the published NuGet package.
- The public `Bimo.Tools.csproj` is synchronized from reviewed private SDK source and targets **1.4.1** in this snapshot.
- The Hello BIMO sample and published-package smoke test remain pinned to **1.3.0** until a matching 1.4.x host is tested.
- **NuGet publication is independent of source synchronization.** The snapshot and its `SOURCE.json` provenance do not prove binary identity with a previously published NuGet package or compatibility with an installed host.

The extraction source commit and file hashes are recorded in [`SOURCE.json`](SOURCE.json). This snapshot is not guaranteed to be byte-for-byte equivalent to any published NuGet artifact. Keep the package version derived from the reviewed upstream SDK source; it is not an instruction to republish packages from this public repository.

Expand Down
10 changes: 5 additions & 5 deletions SOURCE.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"schema": 1,
"source_commit": "9ff2dcae19b525373b43acfd4bedbe493f586692",
"source_commit": "c9f7364d977b7dd50a1d6b453cdd00e28cfc7987",
"source_subdirectory": "src/Bimo.Tools",
"source_of_truth": "private BIMO monorepo (stage 1)",
"nuget_publication": "not performed by public snapshot CI",
Expand All @@ -20,14 +20,14 @@
"Attributes/Inputs/InputAttribute.cs": "34566784a7bc1cf2c29ba35d468647ec7a9129ce4b3e5dfcf0b0761c7883e506",
"Attributes/Inputs/ParameterInputAttribute.cs": "98e31493fc82ed09b288934b6308aaebc0b68972ed4938c0ffe659739126bba2",
"Attributes/VisibleWhenAttribute.cs": "1d309489df62f3a8c286b8ec98fdb598b647d95297b0b218ccad4b648d20cb71",
"Bimo.Tools.csproj": "fd27049a9b67ff885b40c28aac3928e7423b462b05395718ce6b842d961ab874",
"Bimo.Tools.csproj": "43dc92a4b15165d71a2389a731f8d23a1e6ed6fabc4e117a65c39f343e0da3d2",
"CONTRIBUTING.md": "88c651c54c8ead5b7f51bac0b882517522b215ee1e993c823b17dcfac1a07f15",
"Commands/CommandInputException.cs": "7dd6d30b224b47d541b008ccb697844085e7203ce55c80b424bbdad1c0fa7018",
"Commands/CommandInteraction.cs": "acd9925d6bdf6e335974bc4fbf159748b9a38b64d2a605c91945582a27350b0e",
"Commands/CommandReport.cs": "9e31109dffdcf88b12644653596eb016c8dfc4643c2d2d703789a5f0fcc10e45",
"LICENSE": "79fe8a9149a6a4810d2617af3e85d82bc2a5d1832713a9c2472e0369b1fb63e1",
"Output.cs": "2ce91f1a4ab59b2fee551c18f0114db9820c58b42264c3f2d8eae1cb3288168e",
"README.md": "2a2a071bf4e3ff4aa65bd8515857abca75c177547a175296edd7c2c92af25ec0",
"README.md": "8cd5332e5c3742278d6b659819264c83eb9456b438a6a15d8c7bef7517460967",
"Resources/TransactionResources.cs": "d1c5f5963c9b8471286a61f2aae532b686b37fb6bfba88fc03dd75b911bdb15f",
"Resources/TransactionResources.resx": "f43ba3f184bb4aeb01e01b9f971f25a77e39dd0c59478635cc4da080d7b173a9",
"Resources/TransactionResources.ru.resx": "48583ff14461c75f0fbc322fab429188ec3a04033a452d3d25fb027aa968d4b0",
Expand All @@ -40,8 +40,8 @@
"Services/TransactionExecutionResultExtensions.cs": "e3fd9a260ab5b023783d61c916576a5f6bd56c535e8168b3be10bab1c98c5cd0",
"Services/TransactionExecutionStatus.cs": "0c83931abc5b064fa5f825a9cc8bee4493736b4df850ac08f317b7b464c946eb",
"Services/TransactionManagerExtensions.cs": "935c4fa9aecce1855adc46d5d7b94c66696c24d47041847b3c2744673b177542",
"docs/command-authoring.md": "14eaeca0c85d1d9bd735b76f6a31df7ac4bb861b1a18db5adae5cb20ac05670c",
"docs/quick-start.md": "9e0006b9de9b05662bf3ec82c8f738de73c64a9d7ee3ed209792d35f6fe3b9f4",
"docs/command-authoring.md": "46a4d6b8e4efa9b346848e18b8ec67c1afd52d7f2f1e93b981d0ee5370eb09cf",
"docs/quick-start.md": "8c6a8699e292674fdf53b21c193508b3e0cccfba8f559c607c89785295d3529c",
"examples/HelloBimo/HelloBimo.csproj": "1988ccafe8394c240456db65ce1ab7264b9f02a6ea8874edbeb1ee65a5145764",
"examples/HelloBimo/HelloBimoCommand.cs": "294a353d66fa8300cac3429b7e529e305a1937ddaaf17fbe45509f0a15157c21",
"tests/Bimo.Tools.Smoke/Bimo.Tools.Smoke.csproj": "0e3f7489534f29f2057b4aa73d928bc50a19d6d5fa9f968ab600d26320fc243d",
Expand Down
34 changes: 26 additions & 8 deletions docs/command-authoring.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Author custom BIMO commands with C# (SDK 1.3.0)
# Author custom BIMO commands with C# (SDK 1.4.1)

This guide is for developers who want to build and maintain their own DLL commands for **BIMO Toolbar** in Autodesk Revit. It covers the public SDK authoring contract, not the private BIMO host implementation.

Expand All @@ -13,25 +13,28 @@ This guide is for developers who want to build and maintain their own DLL comman
| Add editable inputs and presets | [Settings and presets](#settings-and-presets) |
| Reuse logic via dependency injection | [Per-invocation services](#per-invocation-services) |
| Return useful output | [Results and reports](#results-and-reports) |
| Report correctable input errors | [Expected input errors](#expected-input-errors-sdk-14) |
| Make a command available to an AI agent | [MCP and AI-agent execution](#mcp-and-ai-agent-execution) |
| Diagnose load or build failures | [Troubleshooting](#troubleshooting) |

## Requirements and compatibility

- Install Autodesk Revit and a compatible BIMO Toolbar. For SDK **1.3.0**, the documented baseline is **BIMO Toolbar 0.46.0**.
- Use a .NET SDK capable of building a C# library targeting `netstandard2.0` (the example uses .NET 8 for building).
- Restore the publicly released [Bimo.Tools NuGet package](https://www.nuget.org/packages/Bimo.Tools/1.3.0). Private BIMO repositories are **not** required for authoring.
- Install Autodesk Revit and a **compatible BIMO Toolbar**. The documented **Toolbar 0.46.0** baseline uses **SDK 1.3.0**. The published **SDK 1.4.1** adds expected-error support and requires an updated, verified host; do not assume 0.46.0 supports the 1.4 contract.
- Use a .NET SDK capable of building a C# library targeting `netstandard2.0` (the Hello BIMO example uses .NET 8 for building).
- Restore [Bimo.Tools 1.4.1 from nuget.org](https://www.nuget.org/packages/Bimo.Tools/1.4.1), or pin 1.3.0 for the documented 0.46.0 baseline. Private BIMO repositories are **not** required for authoring.
- Build a **command DLL**, not a new Revit add-in. BIMO loads explicitly configured DLLs and generates Toolbar command adapters on Revit startup.

The [Hello BIMO Quick Start](quick-start.md) and its published-package smoke test deliberately stay on **SDK 1.3.0**; they are not proof of 1.4.1 compatibility in an installed Revit host.

The public `Bimo.Tools` assembly contains attributes and interfaces, **not** a Revit API runtime or an MCP server. Targeting .NET Standard 2.0 does not guarantee every other dependency you add will work in every installed Revit version. Check your Revit-specific references separately.

## Create your own command

For a minimal command that displays a notification, create a `netstandard2.0` class library and pin the compatible package:
For a minimal command that displays a notification, create a `netstandard2.0` class library and pin the **1.4.1** package (only if the installed BIMO host has been verified for 1.4.x):

```powershell
dotnet new classlib -n MyBimoCommands -f netstandard2.0
dotnet add MyBimoCommands/MyBimoCommands.csproj package Bimo.Tools --version 1.3.0
dotnet add MyBimoCommands/MyBimoCommands.csproj package Bimo.Tools --version 1.4.1
```

In the project, use a *unique, stable* identifier for each command:
Expand Down Expand Up @@ -212,7 +215,22 @@ A static command can return `void` for a simple operation, or return a public co

`CommandReport` also supports additional details and selectable element UniqueIds. Only report genuinely persistent elements as selectable results; an element created during a rolled-back trial must **not** be presented as a surviving model change.

For a command that requires an active Revit project, add `RequiredDocument = CommandDocumentRequirement.Project` to `[Bimo]`. This rejects no-document and family-document contexts **before** settings or client service activation. The default is `None`, and SDK 1.3.0 exposes only `None` and `Project`.
For a command that requires an active Revit project, add `RequiredDocument = CommandDocumentRequirement.Project` to `[Bimo]`. This rejects no-document and family-document contexts **before** settings or client service activation. The default is `None`; SDK 1.4.1 still exposes only `None` and `Project`.

## Expected input errors (SDK 1.4+)

Use `Bimo.Tools.Commands.CommandInputException` for an **expected input rejection that the user can correct**, for example a missing selection or a known unsupported element type:

```csharp
using Bimo.Tools.Commands;

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

The **compatible BIMO host** reports this as `Failed`, presents one localized error notification in Ribbon or a bounded agent-safe message through MCP, and records any diagnostic inner exception privately. There is no need for the entrypoint to catch and wrap the error as `OperationCanceledException`; cancellation remains `Cancelled`.

**Do not use `CommandInputException`** for actual user cancellation, unexpected Revit API errors, broken invariants, transaction faults, or other failures users cannot fix by adjusting input. The public message must be localized and safe: no filesystem paths, credentials, personally identifying values, raw exceptions or stack traces. SDK 1.3.0 does **not** contain this type, and an SDK 1.4.1 command requires a matching host that implements this classification.

## MCP and AI-agent execution

Expand All @@ -239,7 +257,7 @@ dotnet run --project tests/Bimo.Tools.Smoke/Bimo.Tools.Smoke.csproj -c Release -
dotnet run --project tests/Bimo.Tools.Smoke/Bimo.Tools.Smoke.csproj -c Release -p:UsePublishedPackage=true
```

These verify the exported source API and the **published NuGet 1.3.0** consumer independently. They do not start Revit, generate real host wrappers or verify live model changes. For your own DLL, complete an **installed-Revit acceptance check**: build, load and restart; inspect the Ribbon label; edit settings; launch the normal command; verify its result; validate no-project/family behavior if required; then separately test permitted agent trials and document rollback if relevant.
These verify the latest exported SDK source and the deliberately pinned **published NuGet 1.3.0** Hello BIMO consumer independently. A successful source build does not by itself confirm compatibility between a new 1.4.x command and an installed host. They do not start Revit, generate real host wrappers or verify live model changes. For your own DLL, complete an **installed-Revit acceptance check**: build, load and restart; inspect the Ribbon label; edit settings; launch the normal command; verify its result; validate no-project/family behavior if required; then separately test permitted agent trials and document rollback if relevant.

The public repository is a **reviewed SDK snapshot**. Its `SOURCE.json` records provenance; public CI does not publish a NuGet package. Contributions to SDK contracts are reviewed and carried to the private upstream before a controlled public sync.

Expand Down
Loading
Loading