Skip to main content

What are client integrations?

Client integrations (also called components) are NuGet packages that simplify connecting your .NET services to popular databases, messaging systems, and cloud services. Each component registers the appropriate client type in your dependency injection container and automatically configures health checks, logging, telemetry, and other observability features.

Key benefits

Client integrations provide several advantages over manually configuring clients:
  • Automatic registration: Components register clients in the DI container with proper configuration
  • Built-in observability: Health checks, logging, metrics, and distributed tracing are configured automatically
  • Consistent patterns: All components follow the same configuration conventions
  • Connection string support: Works seamlessly with the Aspire app model and hosting integrations
  • Production-ready: Includes retry policies, timeouts, and other resilience features

How components work

Client integrations follow a consistent pattern:
  1. Install the package: Add the component NuGet package to your service project
  2. Register the client: Call the component’s extension method in your Program.cs file
  3. Inject and use: Access the client through dependency injection in your services

Basic example

// In your service's Program.cs
builder.AddNpgsqlDataSource("postgresdb");

// In your service class
public class ProductsService
{
    private readonly NpgsqlDataSource _dataSource;

    public ProductsService(NpgsqlDataSource dataSource)
    {
        _dataSource = dataSource;
    }

    public async Task<List<Product>> GetProducts()
    {
        await using var connection = await _dataSource.OpenConnectionAsync();
        // Use the connection...
    }
}

Available components

Databases

PostgreSQL (Npgsql)

Connect to PostgreSQL databases using the Npgsql driver

SQL Server

Connect to Azure SQL and SQL Server databases

Redis

Connect to Redis for caching and data storage

MongoDB

Connect to MongoDB databases with the .NET driver

Messaging

RabbitMQ

Connect to RabbitMQ message brokers

Apache Kafka

Produce and consume messages with Apache Kafka

Azure Services

Azure Cosmos DB

Connect to Azure Cosmos DB for NoSQL

Azure Storage

Work with Azure Blob Storage and Queue Storage

Azure Service Bus

Send and receive messages with Azure Service Bus

Configuration options

All components support three configuration approaches:

Connection strings

Use connection strings from the ConnectionStrings configuration section:
{
  "ConnectionStrings": {
    "mydb": "Host=localhost;Database=mydb"
  }
}

Configuration providers

Configure component settings using appsettings.json:
{
  "Aspire": {
    "Npgsql": {
      "DisableHealthChecks": true,
      "DisableTracing": false
    }
  }
}

Inline delegates

Configure settings directly in code:
builder.AddNpgsqlDataSource("mydb", settings => 
{
    settings.DisableHealthChecks = true;
});

Working with the app host

Client integrations work seamlessly with hosting integrations. In your app host, register a resource and reference it in your service:
// AppHost/Program.cs
var postgres = builder.AddPostgres("pg").AddDatabase("mydb");

var myService = builder.AddProject<Projects.MyService>()
                       .WithReference(postgres);
The connection string is automatically passed to your service, where you consume it:
// MyService/Program.cs
builder.AddNpgsqlDataSource("mydb");
The connection name used in WithReference must match the name used in the component registration.

Common settings

Most components support these common settings:
SettingDescriptionDefault
DisableHealthChecksDisable automatic health check registrationfalse
DisableTracingDisable distributed tracingfalse
DisableMetricsDisable metrics collectionfalse
Check each component’s documentation for specific configuration options.

Next steps

PostgreSQL

Learn how to use the Npgsql component

SQL Server

Connect to SQL Server databases

Redis

Add caching with Redis

MongoDB

Work with MongoDB databases

Build docs developers (and LLMs) love