SurrealDB Client integration reference

⭐ Community Toolkit

To get started with the Aspire SurrealDB integrations, follow the Get started with SurrealDB integrations guide.

This article includes full details about the Aspire SurrealDB Client integration.

Installation

To install the 📦 CommunityToolkit.Aspire.SurrealDb NuGet package in the client-consuming project:

.NET CLI

.NET CLI — Add CommunityToolkit.Aspire.SurrealDb package

dotnet add package CommunityToolkit.Aspire.SurrealDb

Program.cs (C# file-based app)

Program.cs

#:package CommunityToolkit.Aspire.SurrealDb@*

PackageReference (*.csproj)

XML — Add CommunityToolkit.Aspire.SurrealDb package reference

<PackageReference Include="CommunityToolkit.Aspire.SurrealDb" Version="*" />

Add SurrealDB client

In the Program.cs file of your client-consuming project, call the AddSurrealClient extension method to register a SurrealDbClient for use via the dependency injection container. The method takes a connection name parameter.

builder.AddSurrealClient(connectionName: "db");

Tipp

The connectionName parameter must match the name used when adding the SurrealDB resource in the AppHost project.

You can then retrieve the SurrealDbClient instance using dependency injection:

public class ExampleService(SurrealDbClient client)
{
    // Use client...
}

Add keyed SurrealDB client

There might be situations where you want to register multiple SurrealDbClient instances with different connection names. To register keyed SurrealDB clients, call the AddKeyedSurrealClient method:

builder.AddKeyedSurrealClient(name: "products");
builder.AddKeyedSurrealClient(name: "orders");

Then you can retrieve the SurrealDbClient instances using dependency injection:

public class ExampleService(
    [FromKeyedServices("products")] SurrealDbClient productsClient,
    [FromKeyedServices("orders")] SurrealDbClient ordersClient)
{
    // Use clients...
}

Configuration

The Aspire SurrealDB client integration provides multiple options to configure the server connection.

Use a connection string

When using a connection string from the ConnectionStrings configuration section, provide the name of the connection string:

builder.AddSurrealClient(connectionName: "db");

Then the connection string will be retrieved from the ConnectionStrings configuration section:

{
  "ConnectionStrings": {
    "db": "Endpoint=ws://localhost:19530/;Namespace=ns;Database=db;Username=root;Password=123456!@#$%"
  }
}

Use configuration providers

The Aspire SurrealDB Client integration supports configuration. It loads the settings from configuration using the Aspire:Surreal:Client key:

{
  "Aspire": {
    "Surreal": {
      "Client": {
        "Endpoint": "ws://localhost:19530/",
        "Namespace": "ns",
        "Database": "db",
        "Username": "root",
        "Password": "123456!@#$%"
      }
    }
  }
}

Client integration health checks

The Aspire SurrealDB integration uses the configured client to perform a health check.