Goal
Get a working SpeckleSharp script with the shortest path to load and analyse model data — without learning dependency injection.What you will build
A script that authenticates, loads the latest version of an existing model, counts elements by category, and prints a summary to the console.When to use this
Use this page when you write:- A one-off C# script or console app
- A Grasshopper C# Script or custom component
- A C# cell in a polyglot notebook (Jupyter, Visual Studio, Rider)
- A small automation that is not a desktop connector
client, operations, and Base objects.
If you are building a production desktop connector (Revit, Rhino, AutoCAD, and similar), start with Dependency injection (connectors) and Publish large models (connectors) instead.
Recommended approach
The recommended approach for server-facing AEC automation scripts isReceive2/Send2 — no transport factory required. Paste the bootstrap below, authenticate with a PAT from SPECKLE_TOKEN, and call IOperations methods directly.
For Grasshopper object construction without server calls, see Use SpeckleSharp in a Grasshopper C# node. For connector Publish/Load on the canvas, use the Grasshopper connector — the SDK complements those components; it does not replace them.
One-time bootstrap (copy this)
Paste this at the top of your script, notebook cell, or Grasshopper C# component. Run it once per process. This is the canonical bootstrap — other pages link here instead of repeating the full block.Complete example
Load an existing model and count elements by category:onProgressAction and cancellationToken are for long-running host applications (connectors with progress UI). For scripts, null and default are correct — not placeholders to replace.How it works
| What you want | Resolve from bootstrap | Then use |
|---|---|---|
GraphQL API (Project, Model, Version, …) | IClientFactory → Create(account) | client.Version.GetVersions(...), client.Project.Get(...) |
| Load / send object graphs | IOperations | Receive2, Send2, Serialize |
| Build an account from a PAT | IAccountFactory | CreateAccount(serverUrl, token) |
| Reuse a desktop login | IAccountManager (optional) | GetAccounts(), GetDefaultAccount() |
Send/Receive with transports instead.
Common mistakes
| Mistake | Fix |
|---|---|
Creating a new ServiceProvider on every notebook cell run | Define the static bootstrap once per session |
Using Send + IServerTransportFactory in a script | Prefer Send2/Receive2 for server work |
Reading obj["category"] on connector data | Use DataObject.properties for BIM fields |
Skipping Speckle.Objects in bootstrap assemblies | Pass typeof(Point).Assembly when receiving geometry |
What to skip (unless you are building a connector)
| Page / topic | Why scripts can skip it |
|---|---|
| Dependency injection (connectors) | Deep dive for host apps sharing a container |
| Publish large models (connectors) | SendPipeline — production connector upload only |
| Working with Proxies | Only when receiving connector data with groups/instances |
Grasshopper and hosted scripts
Speckle connector components (Publish, Load): use the components for transport. Custom analysis in Grasshopper C#: see Use SpeckleSharp in a Grasshopper C# node forDataObject construction; return here for Send2/Receive2.
Polyglot notebooks
- Paste the bootstrap in the first cell and run it once per kernel session.
- In later cells, call
SpeckleBootstrap.Operations,SpeckleBootstrap.ClientFactory, and so on directly. - Store
accountorclientin notebook variables if you reuse them —IClientisIDisposable.
Next Steps
Build your first model analysis tool
Full CSV report walkthrough
Authentication
PAT and environment variables
Load and publish model data
Send2 vs Send decision guide
FAQ
Do I have to learn Microsoft.Extensions.DependencyInjection?
Do I have to learn Microsoft.Extensions.DependencyInjection?
No. Treat
AddSpeckleSdk + BuildServiceProvider() as a required preamble — like adding using statements.Which quickstart should I follow?
Which quickstart should I follow?
Build your first model analysis tool for a complete automation. This page for the bootstrap snippet. Full send/receive tour if you want to understand publishing from scratch.