Speckle .NET SDK入門｜NuGet導入・認証・Base作成・send/receiveとRevitアドイン連携

本記事は Speckle カテゴリの一部として、Speckle の .NET SDK を C# 開発者向けに整理します。Revit のような .NET 製アプリのアドインから Speckle を扱う場面で中心になる SDK です。ホスト側の API と組み合わせる場合は Revit API概要 もあわせて参照してください。

1.NET SDK とは・パッケージの再編

Speckle の .NET SDK は、Speckle サーバーやローカルのデータ転送層を C# / .NET から操作するためのライブラリ群です。NuGet パッケージとして配布され、コンソールアプリ・サービス・各種 CAD/BIM アドインに組み込めます。

歴史的には Speckle.Core・Speckle.Objects といったパッケージ構成でしたが、近年は Speckle.Sdk を中心とした構成へ再編されています。名前空間やクラスの配置が版によって異なるため、サンプルコードを写す際は「どの世代の SDK か」を必ず確認してください。本記事のコードは概念を示すものであり、実際の型名・メソッド名は利用するバージョンの公式ドキュメントに合わせる必要があります。

2導入（NuGet）

.NET プロジェクトに NuGet 経由で追加します。新世代では概ね次のようなパッケージを参照します（パッケージ名は版で変わり得ます）。

dotnet add package Speckle.Sdk
dotnet add package Speckle.Objects

対象フレームワークは、組み込み先のホストアプリに合わせます。Revit アドインであれば、その Revit バージョンが要求する .NET ランタイム（.NET Framework または .NET 8 系など、年次で異なる）に一致させる必要があります。ランタイム不一致は読み込み失敗の典型原因です。

3認証（アカウント・トークン）

Speckle サーバーへアクセスするには認証情報が必要です。多くの場合、デスクトップの Speckle Manager / Connector で追加済みのローカルアカウントを SDK から取得して使うか、Personal Access Token を明示的に渡します。概念的なコードは次のようになります。

// 既定アカウントの取得（概念例・型名は版に依存）
var account = AccountManager.GetDefaultAccount();

// もしくはトークンとサーバー URL を明示
// var account = new Account { token = "xxxxx", serverInfo = ... };

4Base オブジェクトの作成

Speckle のデータはすべて Base を基底とするオブジェクトで表現されます。任意のプロパティを動的に持たせられ、これがツール間でデータをやり取りする共通の器になります。データモデルの詳細は オブジェクトモデル を参照してください。

// 動的プロパティを持つ汎用オブジェクト
var obj = new Base();
obj["name"] = "Wall-01";
obj["height"] = 3000.0;            // 単位は呼び出し側の取り決めに従う
obj["category"] = "Walls";

// 子要素を入れ子にできる
var child = new Base();
child["type"] = "Opening";
obj["@elements"] = new List<Base> { child };

@ で始まるプロパティは「分離して保存される（detach）」という Speckle の慣習を表し、大きな構造を効率よく保存・参照するために使われます。

5send / receive の基本

作成した Base をサーバーへ送る（send）と、その状態を指す Version（旧 Commit）が作られます。逆に受け取る（receive）と、指定した Version のオブジェクトツリーが復元されます。send / receive の概念は send/receive で詳しく扱います。

// 送信（概念例）
// 1) ローカルにシリアライズして保存
// 2) サーバーへ転送し Version を作成
var objectId = await Operations.Send(obj, transport);
// その後、Project(旧Stream) / Model(旧Branch) に対して Version を作成する API を呼ぶ

// 受信（概念例）
var received = await Operations.Receive(objectId, transport);

新世代の API では、転送（オブジェクトの保存・取得）と「プロジェクトへの Version 登録」は分けて扱われる傾向があります。ここでも具体的なメソッド名・引数は版に依存するため、利用バージョンの公式サンプルで確認してください。

6Revit アドインからの利用

Revit は .NET 上で動作するため、アドイン内から Speckle .NET SDK を直接呼び出せます。Revit 側 API の基礎は Revit API概要 を参照してください。典型的な流れは次のとおりです。

この「ホスト要素 ⇄ Base への双方向変換」を担うのが各コネクタの中心ロジックです。コネクタの考え方は コネクタ、Revit 連携の具体は Revit⇄Speckle で扱います。アドイン内では Revit の API 呼び出しが UI スレッド制約を持つ点に注意し、長時間の send / receive はトランザクションや実行コンテキストの扱いに気をつけてください。

→次に読む