過去バージョン

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

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

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

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

導入（NuGet）

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

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

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

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

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

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

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

トークンはソースコードに直書きせず、環境変数や設定ファイル・シークレットストアから読み込みます。トークンの権限（読み取り専用か書き込み可か）も、用途に応じて最小限に絞るのが安全です。

Base オブジェクトの作成

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 の慣習を表し、大きな構造を効率よく保存・参照するために使われます。

send / 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 登録」は分けて扱われる傾向があります。ここでも具体的なメソッド名・引数は版に依存するため、利用バージョンの公式サンプルで確認してください。

Revit アドインからの利用

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

• Revit API で要素（壁・床など）の形状・パラメータを取得する
• 取得した情報を Base（または Speckle.Objects の型）へ変換する
• SDK で send し、Project / Model に Version を作成する
• 受信側では receive した Base をホスト側のジオメトリへ戻す

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

つまずきやすい点

• パッケージ名・名前空間の世代差：Speckle.Core 時代のサンプルがそのまま動かないことがある
• .NET ランタイムの不一致：ホストアプリの要求バージョンに合わせる
• 単位・座標系：Base は単位を強制しないため、送受信側で取り決めが必要
• 非同期処理：send / receive は async で、UI スレッドをブロックしない設計にする

Python から扱いたい場合は specklepy が選択肢になります。.NET SDK はホストアプリ組み込み、specklepy はデータ処理・自動化、と役割で使い分けると整理しやすいでしょう。