diff --git a/Bimo.Tools.csproj b/Bimo.Tools.csproj index 950b34f..7c66b9e 100644 --- a/Bimo.Tools.csproj +++ b/Bimo.Tools.csproj @@ -8,7 +8,7 @@ 1.0.0.0 $(AssemblyVersion) - 1.4.0 + 1.4.1 $(PackageVersion) BIMO Tools diff --git a/README.md b/README.md index 597e28b..3eba8d0 100644 --- a/README.md +++ b/README.md @@ -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 - + ``` -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 @@ -30,8 +30,10 @@ 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 @@ -39,11 +41,11 @@ The [Toolbar 0.46.0 release notes](https://bimo.tools/releases) document the 1.3 | --- | --- | | **[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: @@ -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. @@ -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 @@ -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. diff --git a/SOURCE.json b/SOURCE.json index 7de79ad..5642fc4 100644 --- a/SOURCE.json +++ b/SOURCE.json @@ -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", @@ -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", @@ -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", diff --git a/docs/command-authoring.md b/docs/command-authoring.md index 4bf1530..05ac5ee 100644 --- a/docs/command-authoring.md +++ b/docs/command-authoring.md @@ -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. @@ -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: @@ -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 @@ -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. diff --git a/docs/quick-start.md b/docs/quick-start.md index 3044627..263a756 100644 --- a/docs/quick-start.md +++ b/docs/quick-start.md @@ -2,6 +2,8 @@ This walkthrough builds the **Hello BIMO** sample against the published [Bimo.Tools 1.3.0 package](https://www.nuget.org/packages/Bimo.Tools/1.3.0). It illustrates settings, an invocation-scoped client service, a structured report, and project-document admission without a Revit API reference. Use **BIMO Toolbar 0.46.0 or a verified compatible host**. +**Why 1.3.0?** [Bimo.Tools 1.4.1](https://www.nuget.org/packages/Bimo.Tools/1.4.1) is published, but this runnable example is intentionally pinned to the documented 0.46.0/1.3.0 host pairing. Do not change the sample's package reference solely because a newer SDK exists: verify the installed host supports the 1.4 expected-error contract first. For new SDK features, use the [authoring guide](command-authoring.md). + Use this page to complete your **first** command in Revit. For the full SDK authoring contract, including creating a different command, settings, presets, dependency injection, reports and MCP, see the [C# developer guide](command-authoring.md). ## Requirements @@ -74,6 +76,6 @@ Change the message, rebuild and restart Revit. Keep the existing GUID when updat ## Validation boundary -The public CI builds this sample using **published Bimo.Tools 1.3.0** and runs the smoke consumer against both the extracted source SDK and anonymous NuGet 1.3.0. Tests verify metadata, settings, the client service declaration and direct report production. They **do not** instantiate the real BIMO generator/DI host or replace a manual installed-Revit acceptance test. +The public CI builds this sample using **published Bimo.Tools 1.3.0** and runs the smoke consumer against both the latest exported source SDK and anonymous NuGet 1.3.0. Tests verify metadata, settings, the client service declaration and direct report production. They **do not** instantiate the real BIMO generator/DI host or replace a manual installed-Revit acceptance test. The SDK's source of truth currently remains the private BIMO monorepo; public changes are synchronized through reviewed pull requests. The example never publishes NuGet or changes the SDK runtime.