Nabs.Launchpad.Core.SiloClient 9.0.146

Nabs Launchpad Core Silo Client Library

A .NET 9 library providing Orleans client configuration for connecting to Orleans silos in the Nabs Launchpad framework. This library simplifies the setup of Orleans clients in web applications, APIs, and other services that need to communicate with Orleans grains.

Features

• Simple Configuration: Easy-to-use extension methods for Orleans client setup
• Azure Integration: Built-in support for Azure Table Storage clustering
• Localization Support: Automatic localization configuration
• Serialization Options: Configurable Orleans serialization settings
• Service Discovery: Compatible with .NET Aspire service discovery

Installation

This library is part of the Nabs Launchpad framework and is typically referenced as a project dependency:

<ProjectReference Include="..\Nabs.Launchpad.Core.SiloClient\Nabs.Launchpad.Core.SiloClient.csproj" />

Dependencies

• Microsoft.Orleans.Client: Orleans client framework
• Microsoft.Orleans.Clustering.AzureStorage: Azure Table Storage clustering provider
• Aspire.Azure.Data.Tables: Azure Tables integration for .NET Aspire
• Microsoft.Extensions.Localization: Localization support
• Nabs.Launchpad.Core.Interfaces: Shared grain interfaces and serialization options

Quick Start

Basic Configuration

Add the Orleans client to your application using the AddSiloClient extension method:

var builder = WebApplication.CreateBuilder(args);

builder.AddSiloClient(options =>
{
    options.SiloServiceId = "my-service";
});

var app = builder.Build();

Advanced Configuration

Configure Orleans serialization options for your specific grain interfaces:

builder.AddSiloClient(options =>
{
    options.SiloServiceId = "my-service";
    
    // Configure serialization for your grain interfaces
    options.OrleansSerializationOptions.ConfigureSerializationProviders = services =>
    {
        services.AddSerializer(builder =>
        {
            builder.AddJsonSerializer(isSupported: type => type.Namespace?.StartsWith("MyApp.Contracts") == true);
        });
    };
});

Configuration Options

SiloClientServicesOptions

OrleansSerializationOptions

Inherits from Nabs.Launchpad.Core.Interfaces.OrleansSerializationOptions and provides:

• Serialization provider configuration
• Type registration for Orleans serialization
• Custom serializer setup

Integration with Other Components

This library integrates seamlessly with other Nabs Launchpad components:

• Core.Interfaces: Provides grain interfaces and shared serialization configuration
• Core.Silo: Server-side Orleans configuration that clients connect to
• Core.ServiceDefaults: Common observability and service configuration
• Core.Portal: Blazor applications that use Orleans clients to communicate with grains

Azure Configuration

The client automatically configures Azure Table Storage for Orleans clustering. Ensure your application has access to an Azure Storage account with the connection string configured under the key "clustering".

Connection String Configuration

Configure your Azure Storage connection string in your application settings:

{
  "ConnectionStrings": {
    "clustering": "DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey;EndpointSuffix=core.windows.net"
  }
}

Usage Examples

In a Blazor Application

// Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.AddPortalServices(options => 
{
    options.PortalName = "MyPortal";
});

builder.AddSiloClient(options =>
{
    options.SiloServiceId = "launchpad-service";
});

var app = builder.Build();
app.UsePortalServices<App>();
app.Run();

In a Web API

// Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

builder.AddSiloClient(options =>
{
    options.SiloServiceId = "api-service";
});

var app = builder.Build();
app.MapControllers();
app.Run();

Using Orleans Grains in Controllers

[ApiController]
[Route("api/[controller]")]
public class UsersController : ControllerBase
{
    private readonly IClusterClient _clusterClient;

    public UsersController(IClusterClient clusterClient)
    {
        _clusterClient = clusterClient;
    }

    [HttpGet("{id}")]
    public async Task<IActionResult> GetUser(string id)
    {
        var userGrain = _clusterClient.GetGrain<IUserGrain>(id);
        var user = await userGrain.GetUserAsync();
        return Ok(user);
    }
}

Service Registration

The AddSiloClient method registers the following services:

• IClusterClient: Orleans cluster client for grain communication
• Azure Table Service Client: For Orleans clustering (keyed as "clustering")
• Localization Services: For multi-language support

Best Practices

1. Service ID Consistency: Use the same SiloServiceId for both client and silo configurations
2. Connection Management: The Orleans client manages connections automatically - no need for manual connection handling
3. Grain Interface Versioning: Use proper versioning strategies for grain interfaces to maintain compatibility
4. Error Handling: Implement proper error handling for grain calls, including timeout and unavailability scenarios
5. Resource Cleanup: The Orleans client will be disposed automatically by the DI container

Testing

For testing scenarios, use the Nabs.Launchpad.Core.Testing.Silos library which provides:

• In-memory Orleans test clusters
• Mock grain implementations
• Integration testing utilities

// In test projects
[Fact]
public async Task Should_Communicate_With_Test_Silo()
{
    using var testCluster = new TestClusterBuilder()
        .AddSiloBuilderConfigurator<TestSiloConfigurator>()
        .Build();
    
    await testCluster.DeployAsync();
    
    var grain = testCluster.Client.GetGrain<ITestGrain>(0);
    var result = await grain.DoSomethingAsync();
    
    Assert.NotNull(result);
}

Troubleshooting

Common Issues

1. Connection Failures: Verify Azure Storage connection string and network connectivity
2. Serialization Errors: Ensure all grain interface types are properly configured for serialization
3. Service ID Mismatch: Verify client and silo use the same service ID
4. Missing Dependencies: Ensure all required NuGet packages are installed

Logging

Enable Orleans client logging to troubleshoot connection issues:

builder.Logging.AddFilter("Orleans", LogLevel.Debug);

Contributing

This library follows the Nabs Launchpad coding standards:

• Use C# 13 features and latest language constructs
• Follow nullable reference types conventions (is null, is not null)
• Implement proper async/await patterns
• Include comprehensive unit tests
• Use file-scoped namespace declarations

License

Copyright � Net Advantage Business Solutions