Speckle Sharp Connectors

https://github.com/specklesystems/speckle-sharp-connectors
Admin
Speckle Sharp Connectors provides .NET desktop UI, connectors, and converters for integrating...
Tokens:35,080
Snippets:541
Trust Score:10
License:Apache-2.0
Update:5 months ago
Show doc for...
Tokens:
Raw
### Connector.Initialize Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Connector.md

Example demonstrating how to initialize the Speckle connector framework with Revit and version 2024.

```csharp
var services = new ServiceCollection();
var disposable = services.Initialize(
  HostApplications.Revit,
  HostAppVersion.v2024
);

// Use the connector...

// Clean up when done
disposable.Dispose();
```

--------------------------------

### Connector.AddOpenTelemetry Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Connector.md

Example showing how to configure OpenTelemetry with custom logging, tracing, and metrics for a connector.

```csharp
var logging = new SpeckleLogging(
  Console: true,
  File: new(),
  MinimumLevel: SpeckleLogLevel.Information
);

var tracing = new SpeckleTracing(
  Console: false,
  Otel: new[]
  {
    new("https://seq.example.com/ingest/otlp/v1/traces", 
      Headers: new() { { "X-Seq-ApiKey", "your-key" } })
  }
);

var disposable = services.AddOpenTelemetry(
  "MyConnector",
  HostApplications.Revit,
  HostAppVersion.v2024,
  logging,
  tracing,
  null
);
```

--------------------------------

### Service Initialization Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Connector.md

Demonstrates how to initialize Speckle services for a specific host application and version, and how to retrieve services like ReceiveOperation.

```csharp
var services = new ServiceCollection();
services.Initialize(HostApplications.Revit, HostAppVersion.v2024);
services.AddConnectors();

var provider = services.BuildServiceProvider();
var receiverOperation = provider.GetRequiredService<ReceiveOperation>();
```

--------------------------------

### SendConversionCache Setup

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/configuration.md

Example of registering the SendConversionCache or NullSendConversionCache with dependency injection.

```csharp
// Register caching if change tracking is available
services.AddSingleton<ISendConversionCache, SendConversionCache>();

// Or disable caching
services.AddSingleton<ISendConversionCache, NullSendConversionCache>();
```

--------------------------------

### SpeckleMetrics Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/configuration.md

An example of how to instantiate the SpeckleMetrics record with console disabled and an OpenTelemetry endpoint configured.

```csharp
var metrics = new SpeckleMetrics(
  Console: false,
  Otel: new[]
  {
    new OtelEndpoint(
      Endpoint: new Uri("https://seq.speckle.systems/ingest/otlp/v1/metrics")
    )
  }
);
```

--------------------------------

### Complete Example: Full Configuration

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/configuration.md

A comprehensive example demonstrating the full configuration process for a Speckle connector, including logging, tracing, and custom services.

```csharp
// 1. Create service collection
var services = new ServiceCollection();

// 2. Configure observability
var logging = new SpeckleLogging(
  Console: true,
  File: new FileLoggingOptions { Path = "logs/connector.log" },
  Otel: new[] {
    new OtelEndpoint(
      new Uri("https://seq.speckle.systems/ingest/otlp/v1/logs"),
      new() { { "X-Seq-ApiKey", "key" } }
    )
  },
  MinimumLevel: SpeckleLogLevel.Information
);

var tracing = new SpeckleTracing(
  Console: false,
  Otel: new[] {
    new OtelEndpoint(
      new Uri("https://seq.speckle.systems/ingest/otlp/v1/traces"),
      new() { { "X-Seq-ApiKey", "key" } }
    )
  }
);

// 3. Initialize connector
services.Initialize(HostApplications.Revit, HostAppVersion.v2024);
services.AddConnectors();

// 4. Configure custom services
services.AddSingleton<IThreadContext>(new RevitThreadContext(uiApp));
services.AddSingleton<ISendConversionCache, SendConversionCache>();
services.AddSingleton(new MixPanelEvents());

// 5. Build provider
var provider = services.BuildServiceProvider();

// 6. Use services
var receiveOp = provider.GetRequiredService<ReceiveOperation>();
var result = await receiveOp.Execute(receiveInfo, progress, cancellation);
```

--------------------------------

### Threading Configuration Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/configuration.md

Illustrates how host applications configure threading context, using Revit as an example.

```csharp
// Must be implemented per host app
public class RevitThreadContext : ThreadContext
{
  // Implement thread switching for Revit API
}

services.AddSingleton<IThreadContext>(new RevitThreadContext(uiApp));
```

--------------------------------

### NumberOfOperations Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Cancellation.md

Example of how to get the number of active operations.

```csharp
Console.WriteLine($"Active operations: {manager.NumberOfOperations}");
```

--------------------------------

### Poly3 Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/MeshTriangulation.md

Example of creating a Poly3 object.

```csharp
var polygon = new Poly3
{
  vertices = new()
  {
    (0, 0, 0), (10, 0, 0), (10, 0, 10), (0, 0, 10)
  }
};
```

--------------------------------

### PurgeInstances Method Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Instances.md

Example of how to delete all instances from a previous receive of a model named "GroundFloor".

```csharp
// Delete all instances from previous receive of model "GroundFloor"
baker.PurgeInstances("GroundFloor_");
```

--------------------------------

### Creating Activities

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Logging.md

Example of creating and using an activity scope for tracking operations.

```csharp
var activityFactory = serviceProvider.GetRequiredService<ISdkActivityFactory>();

using (var activity = activityFactory.Start("MyOperation"))
{
  activity?.SetTag("userId", userId);
  activity?.SetTag("projectId", projectId);
  
  // Do work...
  
  // Activity is automatically recorded on disposal
}
```

--------------------------------

### HostObjectBuilder Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Builders.md

Example of using the IHostObjectBuilder to build objects in the host application.

```csharp
var hostBuilder = serviceProvider.GetRequiredService<IHostObjectBuilder>();

var result = await hostBuilder.Build(
  speckleRoot,
  "Architecture Project",
  "Ground Floor",
  new Progress<CardProgress>(p => UpdateProgress(p)),
  cancellationToken
);

Console.WriteLine($"Created {result.BakedObjectIds.Count()} objects");
foreach (var conversionResult in result.ConversionResults)
{
  if (conversionResult.Status == Status.ERROR)
  {
    Console.WriteLine($"Error: {conversionResult.Error?.Message}");
  }
}
```

--------------------------------

### IsExist Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Cancellation.md

Example of checking if an operation exists.

```csharp
if (manager.IsExist("send-op-123"))
{
  Console.WriteLine("Send operation is in progress");
}
```

--------------------------------

### Token Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Cancellation.md

Example of using the cancellation token from an ICancellationItem.

```csharp
using (var item = manager.GetCancellationItem("op-id"))
{
  await someOperation.ExecuteAsync(..., item.Token);
}
```

--------------------------------

### IHostToSpeckleUnitConverter Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Converters.md

Example of converting a host unit to a Speckle unit string using IHostToSpeckleUnitConverter.

```csharp
var converter = serviceProvider.GetRequiredService<IHostToSpeckleUnitConverter<AutoCADUnits>>();
var unit = converter.ConvertOrThrow(AutoCADUnits.Meters);
// Returns "m"
```

--------------------------------

### GetCancellationItem Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Cancellation.md

Example of getting a cancellation item and using its token.

```csharp
using (var item = manager.GetCancellationItem("send-op-123"))
{
  var token = item.Token;
  
  try
  {
    var result = await sendOperation.Send(
      objects,
      sendInfo,
      cancellationToken: token
    );
  }
  finally
  {
    // Automatically disposed and cleaned up
  }
}
```

--------------------------------

### Best Practice: Set Activity Tags

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Logging.md

Example of setting activity tags for context.

```csharp
using (var activity = factory.Start("SendOperation"))
{
  activity?.SetTag("projectId", projectId);
  activity?.SetTag("userId", userId);
  activity?.SetTag("objectCount", objects.Count);
}
```

--------------------------------

### IRootToHostConverter Convert Method Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Converters.md

An example of using the IRootToHostConverter to convert a Speckle Wall object to a Revit element.

```csharp
var converter = serviceProvider.GetRequiredService<IRootToHostConverter>();
var speckleWall = new Wall { /* properties */ };
var revitElement = converter.Convert(speckleWall);
```

--------------------------------

### Speckle Observability Initialization

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Logging.md

Example of initializing Speckle Observability with logging, tracing, and metrics configurations.

```csharp
var observability = new SpeckleObservability(
  Logging: loggingConfig,
  Tracing: tracingConfig,
  Metrics: metricsConfig
);

var (logProvider, tracingDisposable, metricsDisposable) = Observability.Initialize(
  "Connector",
  "Revit 2024",
  "revit",
  "2.0.0",
  observability
);

try
{
  // Run connector...
}
finally
{
  tracingDisposable?.Dispose();
  metricsDisposable?.Dispose();
}
```

--------------------------------

### Structured Logging Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Logging.md

Example of using ILogger for structured logging of information and errors.

```csharp
var logger = serviceProvider.GetRequiredService<ILogger<MyHandler>>();

logger.LogInformation("Starting send operation", new
{
  ProjectId = projectId,
  ObjectCount = objects.Count,
  Version = version
});

try
{
  var result = await sendOperation.Send(...);
}
catch (Exception ex)
{
  logger.LogError(ex, "Send operation failed", new
  {
    ProjectId = projectId,
    Error = ex.Message
  });
}
```

--------------------------------

### IRootObjectBuilder<T> Build Method Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Builders.md

An example demonstrating how to use the IRootObjectBuilder<T> to convert host application elements to a Speckle root object.

```csharp
var rootBuilder = serviceProvider.GetRequiredService<IRootObjectBuilder<RevitElement>>();

var result = await rootBuilder.Build(
  elements,
  "project-123",
  new Progress<CardProgress>(p => Console.WriteLine(p.Title)),
  cancellationToken
);

Console.WriteLine($"Created root: {result.RootObject.id}");
foreach (var conversionResult in result.ConversionResults)
{
  if (conversionResult.Status == Status.ERROR)
  {
    Console.WriteLine($"Failed: {conversionResult.SourceId}");
  }
}
```

--------------------------------

### CancelAllOperations Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Cancellation.md

Example of cancelling all operations.

```csharp
// User clicks "Stop All Operations"
manager.CancelAllOperations();
```

--------------------------------

### ConverterWithFallback Convert Method Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Converters.md

An example demonstrating the behavior of ConverterWithFallback, including direct conversion and fallback to display values.

```csharp
var converter = serviceProvider.GetRequiredService<ConverterWithFallback>();

// If Wall converter exists: returns converted Wall
// If Wall converter missing but displayValue exists: returns geometry from displayValue
// If both missing: throws ConversionException
var result = converter.Convert(speckleObject);
```

--------------------------------

### Secure API Keys

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/configuration.md

Example of loading API keys from secure storage instead of hardcoding them.

```csharp
// Load from secure storage, not hardcoded
var apiKey = SecureSettings.GetSeqApiKey();
Headers: new() { { "X-Seq-ApiKey", apiKey } }
```

--------------------------------

### IRootToSpeckleConverter Convert Method Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Converters.md

An example of using the IRootToSpeckleConverter to convert a Revit Wall object to a Speckle Wall object.

```csharp
var converter = serviceProvider.GetRequiredService<IRootToSpeckleConverter>();
var revitWall = new RevitWall { /* properties */ };
var speckleWall = converter.Convert(revitWall) as Wall;
```

--------------------------------

### SpeckleTracing Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/configuration.md

An example of SpeckleTracing configuration, disabling console output for production and configuring remote OpenTelemetry endpoints for trace collection.

```csharp
var tracing = new SpeckleTracing(
  Console: false,  // Don't pollute console in production
  Otel: new[]
  {
    new OtelEndpoint(
      Endpoint: new Uri("https://seq.speckle.systems/ingest/otlp/v1/traces"),
      Headers: new() { { "X-Seq-ApiKey", "your-api-key" } }
    )
  }
);
```

--------------------------------

### Best Practice: Use User Scope

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Logging.md

Example of using UserActivityScope for user context.

```csharp
using var userScope = UserActivityScope.AddUserScope(account);
// All activities in this scope are tagged with user
```

--------------------------------

### SendProgress.Report Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Operations.md

Example of using SendProgress.Report to report progress updates.

```csharp
var sendProgress = serviceProvider.GetRequiredService<ISendProgress>();
var progress = new Progress<CardProgress>(update => 
{
  progressBar.Value = (int?)(update.Percentage * 100) ?? 0;
  label.Text = update.Title;
});

sendProgress.Begin();
sendProgress.Report(progress, new ProgressArgs { 
  ProgressEvent = ProgressEvent.SerializeObject,
  Count = 42,
  Total = 100
});
```

--------------------------------

### Converter Settings Store Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Converters.md

Demonstrates how to use the IConverterSettingsStore to manage converter settings, including overriding units for nested operations.

```csharp
var settingsStore = serviceProvider.GetRequiredService<IConverterSettingsStore<ConverterSettings>>();
settingsStore.Initialize(new ConverterSettings { Units = "m" });

// Override units for nested operation
using (settingsStore.Push(prev => prev with { Units = "ft" }))
{
  // Nested converters use feet
  var ftObject = converter.Convert(obj);
}

// Back to meters
var mObject = converter.Convert(obj2);
```

--------------------------------

### SpeckleLogging Example: Development Configuration

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/configuration.md

An example of SpeckleLogging configuration suitable for development environments, enabling console logging and local file logging with debug level.

```csharp
var logging = new SpeckleLogging(
  Console: true,
  File: new FileLoggingOptions
  {
    Path: "logs/connector.log",
    MaxFileSizeBytes: 10_000_000,
    RetainedFileCountLimit: 5
  },
  Otel: null,  // No remote telemetry in development
  MinimumLevel: SpeckleLogLevel.Debug
);
```

--------------------------------

### Cancellation Configuration

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/configuration.md

Example of how to configure and use cancellation tokens for operations.

```csharp
var manager = serviceProvider.GetRequiredService<ICancellationManager>();

// Create cancellation item for operation
using (var item = manager.GetCancellationItem("operation-id"))
{
  await operation.ExecuteAsync(..., item.Token);
}

// Monitor active operations
Console.WriteLine($"Active: {manager.NumberOfOperations}");

// Cancel all on shutdown
manager.CancelAllOperations();
```

--------------------------------

### CreateBox Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/MeshTriangulation.md

Example of creating a box mesh using MeshGenerator.CreateBox.

```csharp
var box = MeshGenerator.CreateBox(10, 20, 30);
// 6 faces × 2 triangles per face = 12 triangles
```

--------------------------------

### Poly2 Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/MeshTriangulation.md

Example of creating a Poly2 object with a hole.

```csharp
// Square with a hole
var square = new Poly2
{
  vertices = new()
  {
    (0, 0), (10, 0), (10, 10), (0, 10)
  }
};

var hole = new Poly2
{
  vertices = new()
  {
    (2, 2), (8, 2), (8, 8), (2, 8)
  }
};

square.holes.Add(hole);

var mesh = triangulator.Triangulate(new[] { square });
```

--------------------------------

### ReceiveOperation.Execute Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Operations.md

An example demonstrating how to use the ReceiveOperation.Execute method to receive data from a Speckle server.

```csharp
var receiveInfo = new ReceiveInfo(
  Account: account,
  ProjectId: "project-123",
  ProjectName: "My Project",
  ModelId: "model-456",
  ModelName: "Architecture",
  SelectedVersionId: "version-789",
  ReceivingApplicationSlug: "revit"
);

var result = await receiveOperation.Execute(
  receiveInfo,
  new Progress<CardProgress>(progress => 
    Console.WriteLine($"{progress.Title} {progress.Percentage:P}")),
  cancellationToken
);

foreach (var conversionResult in result.ConversionResults)
{
  Console.WriteLine($"{conversionResult.SourceType}: {conversionResult.Status}");
}
```

--------------------------------

### CancelOperation Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Cancellation.md

Example of cancelling a specific operation.

```csharp
manager.CancelOperation("send-op-123");
```

--------------------------------

### RunOnThread<T> (synchronous, with return) Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Threading.md

Example demonstrating the usage of RunOnThread for synchronous actions with a return value.

```csharp
var documentTitle = await threadContext.RunOnThread<
  string
>(
  () => revitApp.ActiveDocument.Title,
  useMain: true
);
```

--------------------------------

### Revit Instance Baker Implementation

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Instances.md

Example implementation of IInstanceBaker for Revit, showing how it uses FamilySymbol and FamilyInstance for definitions and instances respectively.

```csharp
public class RevitInstanceBaker : IInstanceBaker<ElementId>
{
  // Creates FamilyType from InstanceDefinitionProxy
  // Creates FamilyInstance from InstanceProxy
  public BakeResult BakeInstances(...) { ... }
  
  public void PurgeInstances(string namePrefix)
  {
    // Deletes families and instances matching the prefix
  }
}
```

--------------------------------

### RunOnMainAsync<T> Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Threading.md

Example demonstrating the usage of RunOnMainAsync for executing asynchronous actions on the main thread with a return value.

```csharp
// Safely access Revit from anywhere
await threadContext.RunOnMainAsync(async () =>
{
  var activeDocument = revitApp.ActiveDocument;
  await ProcessDocumentAsync(activeDocument);
});
```

--------------------------------

### SpeckleException Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/errors.md

Example of catching a SpeckleException during a receive operation.

```csharp
try
{
  var result = await receiveOperation.Execute(...);
}
catch (SpeckleException ex)
{
  Console.WriteLine($"Speckle error: {ex.Message}");
}
```

--------------------------------

### Mesh2 Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/MeshTriangulation.md

Example of iterating through the vertices and triangles of a Mesh2 object.

```csharp
var mesh = triangulator.Triangulate(polygons);

Console.WriteLine($"Vertices: {mesh.vertices.Count}");
Console.WriteLine($"Triangles: {mesh.triangles.Count}");

foreach (var (v1, v2, v3) in mesh.triangles)
{
  var p1 = mesh.vertices[v1];
  var p2 = mesh.vertices[v2];
  var p3 = mesh.vertices[v3];
  
  Console.WriteLine($"Triangle: {p1} -> {p2} -> {p3}");
}
```

--------------------------------

### ConversionException Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/errors.md

Example of catching a ConversionException when an object conversion fails.

```csharp
try
{
  var result = converter.Convert(speckleObject);
}
catch (ConversionException ex)
{
  Console.WriteLine($"Cannot convert {speckleObject.speckle_type}: {ex.Message}");
}
```

--------------------------------

### ConversionNotSupportedException Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/errors.md

Example of catching a ConversionNotSupportedException when no converter is found for a type.

```csharp
var manager = serviceProvider.GetRequiredService<IConverterManager<IToSpeckleConverter>>();

try
{
  var converter = manager.ResolveConverter(typeof(CustomType));
}
catch (ConversionNotSupportedException ex)
{
  Console.WriteLine($"No converter for CustomType: {ex.Message}");
}
```

--------------------------------

### SpeckleLogging Example: Production Configuration

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/configuration.md

An example of SpeckleLogging configuration for production, enabling console and file logging, and configuring remote telemetry to a specified OpenTelemetry endpoint with API key.

```csharp
var logging = new SpeckleLogging(
  Console: true,
  File: new FileLoggingOptions { Path = "logs/connector.log" },
  Otel: new[]
  {
    new OtelEndpoint(
      Endpoint: new Uri("https://seq.speckle.systems/ingest/otlp/v1/logs"),
      Headers: new() { { "X-Seq-ApiKey", "your-api-key" } }
    )
  },
  MinimumLevel: SpeckleLogLevel.Information
);
```

--------------------------------

### Create or Update Instances

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/README.md

Example of using IInstanceBaker to purge old instances and bake new ones.

```csharp
var baker = provider.GetRequiredService<IInstanceBaker<ElementId>>();

// Delete old instances
baker.PurgeInstances("ModelName_");

// Create new instances
var bakeResult = baker.BakeInstances(
  instanceComponents,
  appIdMap,
  "ModelName",
  progress
);

Console.WriteLine($"Created: {bakeResult.CreatedInstanceIds.Count()}");
```

--------------------------------

### IConverterManager ResolveConverter Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Converters.md

Example of resolving a converter for a specific type using IConverterManager.

```csharp
var manager = serviceProvider.GetRequiredService<IConverterManager<IToSpeckleTopLevelConverter>>();
var converterType = typeof(RevitWall);
var converter = manager.ResolveConverter(converterType);
var speckleObject = converter.Convert(revitWall);
```

--------------------------------

### Handling LoggerProvider Initialization Errors

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/errors.md

Example of how to catch exceptions during Observability (logging) initialization and fall back to console-only logging.

```csharp
try
{
  var observability = Observability.Initialize(
    "Connector",
    "Revit 2024",
    "revit",
    "2.0.0",
    config
  );
}
catch (Exception ex)
{
  Console.WriteLine($"Failed to initialize logging: {ex.Message}");
  // Fall back to console-only logging
}
```

--------------------------------

### RunOnThread (synchronous, no return) Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Threading.md

Examples demonstrating the usage of RunOnThread for synchronous actions without a return value.

```csharp
// From main thread, execute on worker
await threadContext.RunOnThread(
  () => Console.WriteLine("On worker thread"),
  useMain: false
);

// From worker thread, execute on main
await threadContext.RunOnThread(
  () => revitApp.ActiveDocument.Title,
  useMain: true
);
```

--------------------------------

### RunOnThreadAsync<T> (asynchronous, with return) Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Threading.md

Example demonstrating the usage of RunOnThreadAsync for asynchronous actions with a return value.

```csharp
var result = await threadContext.RunOnThreadAsync<
  Model
>(async () => await FetchModelAsync(),
  useMain: false
);
```

--------------------------------

### SendOperation Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Operations.md

Example of using SendOperation to send objects to Speckle.

```csharp
var sendInfo = new SendInfo(client, "project-id", "model-id");
var objects = new List<RevitElement> { element1, element2 };

try
{
  var (result, versionId, ingestionId) = await sendOperation.Send(
    objects,
    sendInfo,
    fileName: "Send from Revit",
    fileSizeBytes: null,
    versionMessage: "Architecture update",
    new Progress<CardProgress>(p => UpdateUI(p)),
    saveToCache: true,
    cancellationToken
  );

  Console.WriteLine($"Version created: {versionId}");
  if (ingestionId != null)
  {
    Console.WriteLine($"Ingestion job: {ingestionId}");
  }
}
finally
{
  sendInfo.Dispose();
}
```

--------------------------------

### Example Converter Integration

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/MeshTriangulation.md

Shows how a converter might integrate mesh triangulation for converting Polylines to a host-specific mesh format.

```csharp
public class PolylineToMeshConverter : IToHostConverter
{
  private readonly ITriangulator _triangulator;
  
  public object Convert(Polyline polyline)
  {
    var poly = new Poly2
    {
      vertices = polyline.points.Select(p => (p.x, p.y)).ToList()
    };
    
    var mesh = _triangulator.Triangulate(new[] { poly });
    return ConvertMeshToHostFormat(mesh);
  }
}
```

--------------------------------

### ITriangulator Triangulate Method Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/MeshTriangulation.md

Example of how to use the ITriangulator interface to triangulate polygons.

```csharp
var triangulator = serviceProvider.GetRequiredService<ITriangulator>();

var polygon1 = new Poly2 { /* vertices */ };
var polygon2 = new Poly2 { /* vertices */ };

var mesh = triangulator.Triangulate(new[] { polygon1, polygon2 });
```

--------------------------------

### Rhino Instance Baker Implementation

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Instances.md

Example implementation of IInstanceBaker for Rhino, indicating the use of Block definitions and instances.

```csharp
public class RhinoInstanceBaker : IInstanceBaker<Guid>
{
  // Creates RhinoObject block definition
  // Creates RhinoObject instance reference
  public BakeResult BakeInstances(...) { ... }
}
```

--------------------------------

### Configure Logging

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/README.md

Example of configuring Speckle logging, including console, file, and OpenTelemetry endpoints.

```csharp
var logging = new SpeckleLogging(
  Console: true,
  File: new() { Path = "logs/connector.log" },
  Otel: new[] { /* endpoints */ },
  MinimumLevel: SpeckleLogLevel.Information
);

services.AddOpenTelemetry(
  "MyConnector",
  application,
  version,
  logging,
  null,  // tracing
  null   // metrics
);
```

--------------------------------

### User Scope Logging

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Logging.md

Example of using UserActivityScope to tag activities with user information.

```csharp
using var userScope = UserActivityScope.AddUserScope(account);
using var activity = activityFactory.Start("Receive");

// Activity is tagged with user information
```

--------------------------------

### ClearCache Method Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Caching.md

Clears all cached entries.

```csharp
cache.ClearCache();
```

--------------------------------

### Triggering Analytics

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Logging.md

Example of manually reporting an analytics event using IMixPanelManager.

```csharp
var analytics = serviceProvider.GetRequiredService<IMixPanelManager>();

analytics.Report(MixPanelEvents.Send, new Dictionary<string, object>
{
  { "objectCount", 42 },
  { "versionId", versionId }
});
```

--------------------------------

### Example: Disabling Caching

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Caching.md

Demonstrates how to register NullSendConversionCache to disable caching for a specific operation.

```csharp
// Disable caching for this operation
services.AddSingleton<ISendConversionCache>(new NullSendConversionCache());

var operation = services.GetRequiredService<SendOperation<T>>();
```

--------------------------------

### Best Practice: Register appropriately

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Caching.md

Example of conditionally registering SendConversionCache or NullSendConversionCache based on change tracking availability.

```csharp
// Good: only if change tracking is available
if (CanTrackChanges())
{
  services.AddSingleton<ISendConversionCache, SendConversionCache>();
}
else
{
  services.AddSingleton<ISendConversionCache, NullSendConversionCache>();
}
```

--------------------------------

### RunOnThreadAsync (asynchronous, no return) Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Threading.md

Example demonstrating the usage of RunOnThreadAsync for asynchronous actions without a return value.

```csharp
await threadContext.RunOnThreadAsync(
  async () =>
  {
    var data = await FetchDataAsync();
    SaveToDatabase(data);
  },
  useMain: false
);
```

--------------------------------

### TryGetValue Method Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Caching.md

Retrieves a cached reference by application ID.

```csharp
if (cache.TryGetValue("project-id", "wall-001", out var reference))
{
  // Use cached reference, skip conversion
  Console.WriteLine($"Found cached: {reference.referencedId}");
}
else
{
  // Perform conversion
  var newReference = await converter.Convert(wall);
}
```

--------------------------------

### AutoCAD Instance Baker Implementation

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Instances.md

Example implementation of IInstanceBaker for AutoCAD, showing the use of BlockTableRecord for definitions and BlockReference for instances.

```csharp
public class AutoCADInstanceBaker : IInstanceBaker<ObjectId>
{
  // Creates BlockTableRecord for definition
  // Creates BlockReference for instance
  public BakeResult BakeInstances(...) { ... }
}
```

--------------------------------

### Revit Implementation

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Threading.md

Example implementation of a thread context for Revit, handling UI thread interactions.

```csharp
public class RevitThreadContext : ThreadContext
{
  private readonly UIApplication _uiApp;
  
  protected override async Task RunMain(Action action)
  {
    _uiApp.UIDocument.Document.Title; // Validate main thread
    action();
  }
  
  protected override async Task<T> RunMainAsync<T>(Func<Task<T>> action)
  {
    return await action();
  }
  
  protected override Task MainToWorker<T>(Func<T> action)
  {
    return Task.Run(() => action());
  }
  
  protected override Task<T> WorkerToMain<T>(Func<T> action)
  {
    var tcs = new TaskCompletionSource<T>();
    ExternalEvent.Create(
      new ExternalEventHandler(() => {
        try { tcs.SetResult(action()); }
        catch(Exception e) { tcs.SetException(e); }
      })
    ).Raise();
    return tcs.Task;
  }
}
```

--------------------------------

### EvictObjects Method Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Caching.md

Invalidates cached references for specific objects.

```csharp
// User modifies wall-001 in the app
userEditsWall("wall-001");

// Invalidate cache for that object
cache.EvictObjects(new[] { "wall-001" });

// Next send will re-convert wall-001
```

--------------------------------

### Evicting Objects from Cache

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/errors.md

Example of how to correctly evict objects from the cache when they change to prevent cache poisoning.

```csharp
// MUST call when object changes
cache.EvictObjects(changedObjectIds);

// Not just:
var result = await sendOperation.Send(...);  // WRONG!
```

--------------------------------

### Graceful Degradation Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/errors.md

Example of graceful degradation by disabling caching when a file I/O error occurs during cache initialization.

```csharp
// Disable caching on file I/O errors
ISendConversionCache cache;
try
{
  cache = new SendConversionCache();
}
catch (IOException ex)
{
  logger.LogWarning(ex, "Cannot create cache, continuing without");
  cache = new NullSendConversionCache();
}

services.AddSingleton(cache);
```

--------------------------------

### Mixed Operations

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Threading.md

Example demonstrating alternating between main and worker threads for mixed operations.

```csharp
// Start on main thread
var elements = await threadContext.MainToWorker(() =>
{
  // Load elements on worker
  return LoadElementsFromDatabase();
});

// Use results back on main
await threadContext.WorkerToMain(() =>
{
  // Create in Revit
  foreach (var element in elements)
  {
    document.Create.NewElement(element);
  }
});
```

--------------------------------

### Enable Conversion Caching

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/README.md

Example of enabling and managing conversion caching using ISendConversionCache.

```csharp
services.AddSingleton<ISendConversionCache, SendConversionCache>();

// Later, when objects change:
var cache = provider.GetRequiredService<ISendConversionCache>();
cache.EvictObjects(changedIds);

// Clear all:
cache.ClearCache();
```

--------------------------------

### Connector TabTitle Constant

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Connector.md

Defines the static string constant for the display title of the Speckle connector tab in the host application.

```csharp
public static readonly string TabTitle = "Speckle";
```

--------------------------------

### Usage Example: Converting a Floor Plan

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/MeshTriangulation.md

Demonstrates converting a 2D floor plan polygon with a hole into a triangulated mesh using the ITriangulator service.

```csharp
// You have a floor plan polygon from a CAD system
var floorOutline = new Poly2
{
  vertices = new()
  {
    (0, 0), (100, 0), (100, 50), (0, 50)
  }
};

var doorOpening = new Poly2
{
  vertices = new()
  {
    (40, 0), (60, 0), (60, 5), (40, 5)
  }
};

floorOutline.holes.Add(doorOpening);

var triangulator = serviceProvider.GetRequiredService<ITriangulator>();
var mesh = triangulator.Triangulate(new[] { floorOutline });

// Now you have a triangulated floor plan
Console.WriteLine($"Floor plan triangulated into {mesh.triangles.Count} triangles");

// Convert to 3D representation
var mesh3D = new Mesh3
{
  vertices = mesh.vertices.Select(v => (v.x, v.y, 0.0)).ToList(),
  triangles = mesh.triangles
};
```

--------------------------------

### Handle Cancellation

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/README.md

Example demonstrating how to handle operation cancellation using ICancellationManager.

```csharp
var manager = provider.GetRequiredService<ICancellationManager>();

using (var item = manager.GetCancellationItem("send-op-123"))
{
  try
  {
    var result = await sendOp.Send(..., item.Token);
  }
  catch (OperationCanceledException)
  {
    Console.WriteLine("Cancelled");
  }
}

// From UI: manager.CancelOperation("send-op-123");
```

--------------------------------

### IOException Handling

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/errors.md

Example of catching an IOException for I/O errors related to file or cache operations.

```csharp
try
{
  var cache = new SendConversionCache();
  cache.StoreSendResult(projectId, results);
}
catch (IOException ex)
{
  Console.WriteLine($"Cannot write cache: {ex.Message}");
  // Fall back to NullSendConversionCache
}
```

--------------------------------

### StoreSendResult Method Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Caching.md

Stores all conversion results from a send operation.

```csharp
var cache = serviceProvider.GetRequiredService<ISendConversionCache>();
var references = new Dictionary<Id, ObjectReference>
{
  ["wall-001"] = new ObjectReference { referencedId = "abc123" },
  ["wall-002"] = new ObjectReference { referencedId = "def456" }
};

cache.StoreSendResult("project-id", references);
```

--------------------------------

### AppendSendResult Method Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Caching.md

Adds a single conversion result to the cache.

```csharp
cache.AppendSendResult("project-id", "wall-003", 
  new ObjectReference { referencedId = "ghi789" });
```

--------------------------------

### Receive Objects

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/README.md

Example of how to receive objects from Speckle using the ReceiveOperation.

```csharp
var receiveOp = provider.GetRequiredService<ReceiveOperation>();
var receiveInfo = new ReceiveInfo(
  account,
  projectId,
  projectName,
  modelId,
  modelName,
  versionId,
  "revit"
);

var result = await receiveOp.Execute(
  receiveInfo,
  new Progress<CardProgress>(p => UpdateUI(p)),
  cancellationToken
);

Console.WriteLine($"Created: {result.BakedObjectIds.Count()} objects");
```

--------------------------------

### Partial Success Handling

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/errors.md

Example of how to handle partial success after a send operation, logging warnings for failed items and details for each error.

```csharp
var result = await sendOperation.Send(...);

var successful = result.sendResult.ConversionResults
  .Count(r => r.Status == Status.SUCCESS);
var failed = result.sendResult.ConversionResults
  .Count(r => r.Status == Status.ERROR);

if (failed > 0)
{
  logger.LogWarning(
    "Send completed with {success} succeeded and {failed} failed",
    successful, failed
  );
  
  foreach (var error in result.sendResult.ConversionResults
    .Where(r => r.Status == Status.ERROR))
  {
    logger.LogError("Failed: {id}: {message}",
      error.SourceId,
      error.Error?.Message);
  }
}
```

--------------------------------

### Connector TabName Constant

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Connector.md

Defines the static string constant for the UI tab identifier for Speckle connector UI elements.

```csharp
public static readonly string TabName = "Speckle";
```

--------------------------------

### Baking Instances

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Instances.md

Demonstrates how to bake Speckle instances into the host application using the IInstanceBaker service. It shows the parameters required for the BakeInstances method and how to use the returned BakeResult.

```csharp
var baker = serviceProvider.GetRequiredService<IInstanceBaker<ElementId>>();

// After converting instances, bake them
var bakeResult = baker.BakeInstances(
  instanceComponents: components,
  applicationIdMap: appIdMap,
  baseLayerName: "ModelName",
  onOperationProgressed: progress
);

Console.WriteLine($"Created {bakeResult.CreatedInstanceIds.Count()} instances");
```

--------------------------------

### MainToWorker<T> Use Case

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Threading.md

Example demonstrating the use case for MainToWorker to perform heavy computation on a worker thread.

```csharp
// Running on main thread
var data = await threadContext.MainToWorker<
  object
>(() =>
{
  // Heavy computation away from main thread
  return PerformLongCalculation();
});
```

--------------------------------

### Basic Operation with Cancellation

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Cancellation.md

Demonstrates how to use the ICancellationManager to get a cancellation token for a specific operation and handle OperationCanceledException.

```csharp
var manager = serviceProvider.GetRequiredService<ICancellationManager>();

using (var cancellationItem = manager.GetCancellationItem("send-123"))
{
  try
  {
    var result = await sendOperation.Send(
      objects,
      sendInfo,
      cancellationToken: cancellationItem.Token
    );
  }
  catch (OperationCanceledException)
  {
    Console.WriteLine("Send cancelled");
  }
}
```

--------------------------------

### Clearing Entire Cache and Resending

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/errors.md

Example of how to recover from cache poisoning by clearing the entire cache and resending the data.

```csharp
// Clear entire cache and resend
cache.ClearCache();
var result = await sendOperation.Send(...);
```

--------------------------------

### Host App API Access

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Threading.md

Example of accessing host application APIs that can only be used on the main thread.

```csharp
var wallId = await threadContext.WorkerToMain(() =>
{
  // Only Revit API access allowed here
  return document.Create.NewWall(...);
});
```

--------------------------------

### InvalidOperationException Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/errors.md

Example of catching an InvalidOperationException when an operation is in an invalid state.

```csharp
// ReceiveOperation throws if version.referencedObject is null
try
{
  var result = await receiveOperation.Execute(receiveInfo, ...);
}
catch (InvalidOperationException ex)
{
  if (ex.Message.Contains("referenced object"))
  {
    Console.WriteLine("Version has no data to receive");
  }
}
```

--------------------------------

### OperationCanceledException Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/errors.md

Example of catching an OperationCanceledException when an operation is cancelled via CancellationToken.

```csharp
using (var item = cancellationManager.GetCancellationItem("send-op"))
{
  try
  {
    var result = await sendOperation.Send(..., item.Token);
  }
  catch (OperationCanceledException)
  {
    Console.WriteLine("Send operation was cancelled");
  }
}
```

--------------------------------

### Best Practice: Structured Logging

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Logging.md

Comparison of structured vs. unstructured logging.

```csharp
// Good: properties are structured
logger.LogInformation("User {UserId} sent {Count} objects to {ProjectId}",
  userId, count, projectId);

// Bad: unstructured
logger.LogInformation($"User {userId} sent {count} objects");
```

--------------------------------

### Updating Instances

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Instances.md

Shows the workflow for updating instances, which involves purging old instances using a name prefix and then baking the new ones.

```csharp
var baker = serviceProvider.GetRequiredService<IInstanceBaker<ElementId>>();

// Before re-baking, delete old instances
baker.PurgeInstances("ModelName_");

// Then bake new ones
var bakeResult = baker.BakeInstances(...);
```

--------------------------------

### Receiving Instances from Revit

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Instances.md

Illustrates the process of receiving instances from Revit, where Speckle represents families as InstanceDefinitionProxy and family instances as InstanceProxy. It shows how to convert these to Revit's native types.

```csharp
// Revit has families (definitions) and family instances (instances)
// Speckle represents them as InstanceDefinitionProxy and InstanceProxy

var speckleRoot = await receiveOperation.ReceiveData(...);

// The root contains:
// - InstanceDefinitionProxy objects (the families)
// - InstanceProxy objects (the instances)

// Convert to Revit
var result = await hostObjectBuilder.Build(speckleRoot, projectName, modelName, ...);

// Result contains:
// - Created family types (from definitions)
// - Created family instances
// - Conversion results for tracking
```

--------------------------------

### RELEASE Build Default Configuration

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Logging.md

Default logging, tracing, and metrics configuration for RELEASE builds.

```csharp
new SpeckleLogging(
  Console: true,
  File: new(),
  Otel: [
    new(
      Endpoint: new Uri("https://seq.speckle.systems/ingest/otlp/v1/logs"),
      Headers: new() { { "X-Seq-ApiKey", "Y0Ya2CFVt1tCSgrbY07c" } }
    )
  ],
  MinimumLevel: SpeckleLogLevel.Information
),
new SpeckleTracing(
  Console: false,
  Otel: [
    new(
      Endpoint: new Uri("https://seq.speckle.systems/ingest/otlp/v1/traces"),
      Headers: new() { { "X-Seq-ApiKey", "Y0Ya2CFVt1tCSgrbY07c" } }
    )
  ]
)
```

--------------------------------

### Cache Lifecycle Management

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/configuration.md

Demonstrates the lifecycle of the SendConversionCache, including instantiation, reuse, eviction, clearing, and disposal.

```csharp
var cache = new SendConversionCache();

// Cache persists between sends
await sendOp1.Send(..., saveToCache: true);
await sendOp2.Send(..., saveToCache: true);  // Reuses cache from first send

// Invalidate when objects change
cache.EvictObjects(changedObjectIds);

// Clear entire cache
cache.ClearCache();

// Dispose on shutdown
cache.Dispose();
```

--------------------------------

### Format Code with CSharpier CLI

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/README.md

Instructions on how to restore and format code using CSharpier from the command line.

```bash
dotnet tool restore
dotnet csharpier format ./
```

--------------------------------

### HostApplications Class

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/types.md

Constants for host applications.

```csharp
public static class HostApplications
{
  public static Application Rhino;
  public static Application Grasshopper;
  public static Application Revit;
  public static Application Dynamo;
  public static Application Unity;
  public static Application GSA;
  public static Application Civil;
  public static Application Civil3D;
  public static Application AutoCAD;
  public static Application Plant3D;
  public static Application MicroStation;
  public static Application OpenRoads;
  public static Application OpenRail;
  public static Application OpenBuildings;
  public static Application ETABS;
  public static Application SAP2000;
  public static Application CSiBridge;
  public static Application SAFE;
  public static Application TeklaStructures;
  public static Application Dxf;
  public static Application Excel;
  public static Application Unreal;
  public static Application PowerBI;
  public static Application Blender;
  public static Application QGIS;
  public static Application ArcGIS;
  public static Application SketchUp;
  public static Application Archicad;
  public static Application TopSolid;
  public static Application Python;
  public static Application NET;
  public static Application Navisworks;
  public static Application AdvanceSteel;
  public static Application Other;
}
```

--------------------------------

### HttpRequestException Handling

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/errors.md

Example of catching an HttpRequestException for network or HTTP errors.

```csharp
try
{
  var result = await receiveOperation.Execute(...);
}
catch (HttpRequestException ex)
{
  Console.WriteLine($"Network error: {ex.Message}");
  // Retry logic, user notification, etc.
}
```

--------------------------------

### TryGetInstanceDefinitionProxy Method

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Instances.md

C# method signature for TryGetInstanceDefinitionProxy, used to retrieve a definition proxy.

```csharp
bool TryGetInstanceDefinitionProxy(
  string definitionId,
  [NotNullWhen(true)] out InstanceDefinitionProxy? instanceDefinitionProxy);
```

--------------------------------

### Connector.Initialize Parameters

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/configuration.md

Defines the parameters for initializing the Speckle connector within a .NET dependency injection container.

```csharp
public static IDisposable Initialize(
  this IServiceCollection serviceCollection,
  Application application,
  HostAppVersion version
)
```

--------------------------------

### Deep Clean Build

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/README.md

Command to delete bin and obj directories and restore all projects for a clean build.

```powershell
.\build.ps1 deep-clean
```

--------------------------------

### ReceiveConversionResult with Error Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/errors.md

Iterating through ConversionResults to handle errors during a receive operation.

```csharp
var result = await hostObjectBuilder.Build(...);

foreach (var conversionResult in result.ConversionResults)
{
  if (conversionResult.Status == Status.ERROR)
  {
    var speckleObjectId = conversionResult.SourceId;
    var errorMessage = conversionResult.Error?.Message;
    
    Console.WriteLine($"Failed to convert {speckleObjectId}: {errorMessage}");
  }
}
```

--------------------------------

### SendConversionResult with Error Example

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/errors.md

Iterating through ConversionResults to handle errors during a send operation.

```csharp
var result = await sendOperation.Send(...);

foreach (var conversionResult in result.sendResult.ConversionResults)
{
  if (conversionResult.Status == Status.ERROR)
  {
    Console.WriteLine($"Failed: {conversionResult.SourceId}");
    Console.WriteLine($"Error: {conversionResult.Error?.Message}");
    Console.WriteLine($"Stack: {conversionResult.Error?.StackTrace}");
  }
}
```

--------------------------------

### Initialize the Connector

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/README.md

Initializes the connector framework with application and version, and registers common services.

```csharp
var services = new ServiceCollection();

// Initialize with application and version
var disposable = services.Initialize(
  HostApplications.Revit,
  HostAppVersion.v2024
);

// Register common services
services.AddConnectors();

// Add host-app-specific services
services.AddSingleton<IThreadContext>(new RevitThreadContext(uiApp));

var provider = services.BuildServiceProvider();
```

--------------------------------

### DEBUG/LOCAL Build Default Configuration

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Logging.md

Default logging, tracing, and metrics configuration for DEBUG/LOCAL builds.

```csharp
new SpeckleLogging(
  Console: true,
  File: new(),
  MinimumLevel: SpeckleLogLevel.Debug
),
new SpeckleTracing(Console: false),
new SpeckleMetrics(Console: false)
```

--------------------------------

### Handling OperationCanceledException

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/errors.md

Example of how to catch and handle OperationCanceledException when an operation is cancelled via a CancellationToken.

```csharp
using (var item = manager.GetCancellationItem("op-id"))
{
  try
  {
    // Operation checks token
    await operation.ExecuteAsync(..., item.Token);
  }
  catch (OperationCanceledException ex)
  {
    // Handle cancellation
    logger.LogInformation("Operation {id} was cancelled", "op-id");
  }
}

// From another thread:
manager.CancelOperation("op-id");  // Signals token
```

--------------------------------

### Deep Clean Local Build

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/README.md

Command for Local.slnx users to delete bin and obj directories and restore projects for a clean local build.

```powershell
.\build.ps1 deep-clean-local
```

--------------------------------

### AddInstanceProxy Method

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Instances.md

C# method signature for AddInstanceProxy, used to register an instance proxy.

```csharp
void AddInstanceProxy(string objectId, InstanceProxy instanceProxy);
```

--------------------------------

### AddDefinitionProxy Method

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Instances.md

C# method signature for AddDefinitionProxy, used to register an instance definition proxy.

```csharp
void AddDefinitionProxy(string objectId, InstanceDefinitionProxy instanceDefinitionProxy);
```

--------------------------------

### Handle Conversion Errors

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/README.md

Example of handling conversion errors during the send operation.

```csharp
var result = await sendOp.Send(...);

var errors = result.sendResult.ConversionResults
  .Where(r => r.Status == Status.ERROR);

foreach (var error in errors)
{
  logger.LogError(
    "Failed: {id}: {msg}",
    error.SourceId,
    error.Error?.Message
  );
}
```

--------------------------------

### Development vs Production Builds

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/configuration.md

Conditional logging configuration based on build type (DEBUG or Release).

```csharp
#if DEBUG
var logging = new SpeckleLogging(..., MinimumLevel: SpeckleLogLevel.Debug, ...);
#else
var logging = new SpeckleLogging(..., MinimumLevel: SpeckleLogLevel.Information, ...);
#endif
```

--------------------------------

### Honeycomb OTLP Endpoint

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/configuration.md

Configuration for sending traces to Honeycomb, including the API key.

```csharp
new OtelEndpoint(
  Endpoint: new Uri("https://api.honeycomb.io/v1/traces"),
  Headers: new() { { "x-honeycomb-team", "your-api-key" } }
)
```

--------------------------------

### Thread Context Per App

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/configuration.md

Ensuring each host application has its own thread context implementation.

```csharp
// Each host app needs its own implementation
services.AddSingleton<IThreadContext>(hostAppThreadContext);
```

--------------------------------

### SpeckleTracing Configuration

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Logging.md

Configuration object for enabling and setting up console and OpenTelemetry tracing.

```csharp
var tracing = new SpeckleTracing(
  Console: false,
  Otel: new[]
  {
    new OtelEndpoint(
      new Uri("https://seq.speckle.systems/ingest/otlp/v1/traces"),
      Headers: new() { { "X-Seq-ApiKey", "key" } }
    )
  }
);
```

--------------------------------

### Heavy Computation

Source: https://github.com/specklesystems/speckle-sharp-connectors/blob/dev/_autodocs/api-reference/Threading.md

Example of performing CPU-intensive work on a worker thread while keeping the UI thread responsive.

```csharp
var result = await threadContext.MainToWorker(() =>
{
  // CPU-intensive work
  return ConvertLargeModel(objects);
});
```
Tokens:
Raw