Speckle Plugin Basics with the .NET SDK

Overview

SpeckleCore is the .NET sdk for, you guessed it, Speckle.

Architecture

Speckle Core has the following files/classes:

1. SpeckleApiClient

This exposes a partial class that is generated from the specs using nswag. This class contains sync and async methods for directly using the REST API of a speckle server.

2. SpeckleApiClientExtensions

This class extends the above partial class and adds a websocket client, websocket message handling, and some initialisation routines. On top of that, it also adds a series of events that the client emits when something happens - OnReady, OnError, OnWsMessage, OnLogData.

To start off a client and get a stream, for example, you would do:

// get a new client
SpeckleCore.SpeckleApiClient myClient = new SpeckleApiClient(@"https://s003.speckle.works/api", false);

// get a stream's objects
var Response = myClient.GetStreamObjects("", "your-stream-id");

// convert the objects
var ConvertedObjects = Response.Objects.Select(obj => SpeckleCore.Converter.Deserialize(obj));

A more complex example, this time with a sender:

var Client = new SpeckleApiClient( restApi, true );

Client.OnError += Client_OnError;
Client.OnLogData += Client_OnLogData;
Client.OnWsMessage += Client_OnWsMessage;
Client.OnReady += Client_OnReady;

string StreamId = await Client.IntializeSender( apiToken, etc, etc);

3. BaseObjects

Again a (mostly) generated set of classes from the spec. It contains all the classes for the SpeckleObjects, ie. SpeckleCurve, SpeckleArc, SpecklePolyline, etc. These objects are extended with some convenience constructors in BaseObjectExtensions.cs.

All Speckle objects should have at two hashes: geometryHash and hash. The geometryHash is self explanatory, and the hash = geometryHash + a hash of the object's properties dictionary.

4. Conversion Flows

The converter exposes some static convenience methods, for stuff like getting byte[] out of objects, etc. It's main role though is exposed via two functions, Serialize(object) and Deserialize(object).

Essential reading: https://speckle.works/blog/schemasandstandards/

When Speckle tries to serialise an object, it will first look in the current AppDomain for an extension method called ToSpeckle for that specific object type. This extension method must be defined in a namespace that contains "Speckle" and "Converter" in its name.

If such a method is found, it will be invoked and the result passed on. If no such method is found, the converter will try and convert that object into a SpeckleAbstract object.

For example, check the rhino converter out. Here's a snippet for an arc:

    public static SpeckleArc ToSpeckle( this Arc a )
    {
      SpeckleArc arc = new SpeckleArc( a.Plane.ToSpeckle(), a.Radius, a.StartAngle, a.EndAngle, a.Angle );
      return arc;
    }

    public static ArcCurve ToNative( this SpeckleArc a )
    {
      Arc arc = new Arc( a.Plane.ToNative(), ( double ) a.Radius, ( double ) a.AngleRadians );
      var myArc = new ArcCurve( arc );
      myArc.UserDictionary.ReplaceContentsWith( a.Properties.ToNative() );
      return myArc;
    }

5. App Specific Converters

The way things stand right now allow you to separate concerns easily, and create an app specific converter like this:

namespace Speckle_YOURAPP_Converter
{
  public static class Speckle_YOURAPP_Converter
  {
    // add an extension method to SpecklePoint to convert it into a YOURAPP_Point
    public static YOURAPP_Point ToNative(this SpecklePoint object) {}
    // add an extension method to YOURAPP_Point to convert it into a SpecklePoint
    public static SpeckleObject ToSpeckle(this YourObjectType) {} 
    // etc.
  }
}

Theoretically, without further hassle, SpeckleCore should pick these methods up and use them to convert things back and forth. Just make sure the assembly containing the converter is loaded and accessible.

Plugin Architecture

...