Orleans-Clients

Alternativ können Sie eine Client-Schnittstelle wie IGrainFactory oder IClusterClient von ISiloHost erhalten.

Stellen Sie die Konfiguration über UseOrleansClient und mehrere zusätzliche Optionsklassen bereit, die eine Hierarchie von Konfigurationseigenschaften für die programmgesteuerte Konfiguration eines Clients enthalten. Weitere Informationen finden Sie unter Clientkonfiguration.

Betrachten Sie das folgende Beispiel einer Clientkonfiguration:

// Alternatively, call Host.CreateDefaultBuilder(args) if using the 
// Microsoft.Extensions.Hosting NuGet package.
using IHost host = new HostBuilder()
    .UseOrleansClient(clientBuilder =>
    {
        clientBuilder.Configure<ClusterOptions>(options =>
        {
            options.ClusterId = "my-first-cluster";
            options.ServiceId = "MyOrleansService";
        });

        clientBuilder.UseAzureStorageClustering(
            options => options.ConfigureTableServiceClient(connectionString))
    })
    .Build();

Wenn Sie den host Client starten, wird der Client über die erstellte Serviceanbieterinstanz konfiguriert und verfügbar.

Stellen Sie die Konfiguration über ClientBuilder und mehrere zusätzliche Optionsklassen bereit, die eine Hierarchie von Konfigurationseigenschaften für die programmgesteuerte Konfiguration eines Clients enthalten. Weitere Informationen finden Sie unter Clientkonfiguration.

Beispiel für eine Clientkonfiguration:

var client = new ClientBuilder()
    .Configure<ClusterOptions>(options =>
    {
        options.ClusterId = "my-first-cluster";
        options.ServiceId = "MyOrleansService";
    })
    .UseAzureStorageClustering(
        options => options.ConnectionString = connectionString)
    .ConfigureApplicationParts(
        parts => parts.AddApplicationPart(typeof(IValueGrain).Assembly))
    .Build();

Schließlich müssen Sie die Connect() Methode für das erstellte Clientobjekt aufrufen, um sie mit dem Orleans Cluster zu verbinden. Es handelt sich um eine asynchrone Methode, die ein Task zurückgibt, sodass Sie warten müssen, bis der Vorgang mit await oder .Wait() abgeschlossen ist.

await client.Connect();

Es gibt zwei Szenarien, in denen bei einem Clusterclient Konnektivitätsprobleme auftreten können:

• Wenn der Client versucht, eine Verbindung mit einem Silo herzustellen.
• Beim Aufrufen von Kornbezügen, die von einem verbundenen Clusterclient abgerufen werden.

Im ersten Fall versucht der Client, eine Verbindung mit einem Silo herzustellen. Wenn der Client keine Verbindung mit einem Silo herstellen kann, löst er eine Ausnahme aus, die angibt, was schief gelaufen ist. Sie können ein IClientConnectionRetryFilter registrieren, um die Ausnahme zu behandeln, und entscheiden, ob ein neuer Versuch unternommen werden soll. Wenn Sie keinen Wiederholungsfilter angeben oder wenn der Wiederholungsfilter false zurückgibt, gibt der Client endgültig auf.

using Orleans.Runtime;

internal sealed class ClientConnectRetryFilter : IClientConnectionRetryFilter
{
    private int _retryCount = 0;
    private const int MaxRetry = 5;
    private const int Delay = 1_500;

    public async Task<bool> ShouldRetryConnectionAttempt(
        Exception exception,
        CancellationToken cancellationToken)
    {
        if (_retryCount >= MaxRetry)
        {
            return false;
        }

        if (!cancellationToken.IsCancellationRequested &&
            exception is SiloUnavailableException siloUnavailableException)
        {
            await Task.Delay(++ _retryCount * Delay, cancellationToken);
            return true;
        }

        return false;
    }
}

Es gibt zwei Szenarien, in denen bei einem Clusterclient Konnektivitätsprobleme auftreten können:

• Wenn die IClusterClient.Connect()-Methode anfänglich aufgerufen wird.
• Beim Aufrufen von Kornbezügen, die von einem verbundenen Clusterclient abgerufen werden.

Im ersten Fall löst die Connect Methode eine Ausnahme aus, die angibt, was schief gelaufen ist. Dies ist in der Regel (aber nicht unbedingt) eine SiloUnavailableException. In diesem Fall ist die Clusterclientinstanz unbrauchbar und sollte verworfen werden. Sie können optional eine Wiederholungsfilterfunktion für die Connect Methode bereitstellen, die z. B. auf eine angegebene Dauer warten kann, bevor Sie einen anderen Versuch ausführen. Wenn Sie keinen Wiederholungsfilter angeben oder wenn der Wiederholungsfilter false zurückgibt, gibt der Client endgültig auf.

Wenn Connect erfolgreich ausgeführt wird, kann der Clusterclient bis zum Löschen verwendet werden. Dies bedeutet, dass der Client auch bei Verbindungsproblemen unablässig versucht, die Verbindung wiederherzustellen. Sie können das genaue Wiederherstellungsverhalten für ein GatewayOptions objekt konfigurieren, das von dem ClientBuilderangegebenen Objekt bereitgestellt wird, z. B.:

var client = new ClientBuilder()
    // ...
    .Configure<GatewayOptions>(
        options =>                         // Default is 1 min.
        options.GatewayListRefreshPeriod = TimeSpan.FromMinutes(10))
    .Build();

using Microsoft.Extensions.Hosting;

namespace Client;

public sealed class ClusterClientHostedService : IHostedService
{
    private readonly IClusterClient _client;

    public ClusterClientHostedService(IClusterClient client)
    {
        _client = client;
    }

    public Task StartAsync(CancellationToken cancellationToken)
    {
        // Use the _client to consume grains...

        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken cancellationToken)
        => Task.CompletedTask;
}

public class ClusterClientHostedService : IHostedService
{
    private readonly IClusterClient _client;

    public ClusterClientHostedService(IClusterClient client)
    {
        _client = client;
    }

    public async Task StartAsync(CancellationToken cancellationToken)
    {
        // A retry filter could be provided here.
        await _client.Connect();
    }

    public async Task StopAsync(CancellationToken cancellationToken)
    {
        await _client.Close();

        _client.Dispose();
    }
}

try
{
    using IHost host = Host.CreateDefaultBuilder(args)
        .UseOrleansClient((context, client) =>
        {
            client.Configure<ClusterOptions>(options =>
            {
                options.ClusterId = "my-first-cluster";
                options.ServiceId = "MyOrleansService";
            })
            .UseAzureStorageClustering(
                options => options.ConfigureTableServiceClient(
                    context.Configuration["ORLEANS_AZURE_STORAGE_CONNECTION_STRING"]));
        })
        .UseConsoleLifetime()
        .Build();

    await host.StartAsync();

    IGrainFactory client = host.Services.GetRequiredService<IGrainFactory>();

    // Hardcoded player ID
    Guid playerId = new("{2349992C-860A-4EDA-9590-000000000006}");
    IPlayerGrain player = client.GetGrain<IPlayerGrain>(playerId);
    IGameGrain? game = null;
    while (game is null)
    {
        Console.WriteLine(
            $"Getting current game for player {playerId}...");

        try
        {
            game = await player.GetCurrentGame();
            if (game is null) // Wait until the player joins a game
            {
                await Task.Delay(TimeSpan.FromMilliseconds(5_000));
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Exception: {ex.GetBaseException()}");
        }
    }

    Console.WriteLine(
        $"Subscribing to updates for game {game.GetPrimaryKey()}...");

    // Subscribe for updates
    var watcher = new GameObserver();
    await game.ObserveGameUpdates(
        client.CreateObjectReference<IGameObserver>(watcher));

    Console.WriteLine(
        "Subscribed successfully. Press <Enter> to stop.");
}
catch (Exception e)
{
    Console.WriteLine(
        $"Unexpected Error: {e.GetBaseException()}");
}

await RunWatcherAsync();

// Block the main thread so that the process doesn't exit.
// Updates arrive on thread pool threads.
Console.ReadLine();

static async Task RunWatcherAsync()
{
    try
    {
        var client = new ClientBuilder()
            .Configure<ClusterOptions>(options =>
            {
                options.ClusterId = "my-first-cluster";
                options.ServiceId = "MyOrleansService";
            })
            .UseAzureStorageClustering(
                options => options.ConnectionString = connectionString)
            .ConfigureApplicationParts(
                parts => parts.AddApplicationPart(typeof(IValueGrain).Assembly))
            .Build();

            // Hardcoded player ID
            Guid playerId = new("{2349992C-860A-4EDA-9590-000000000006}");
            IPlayerGrain player = client.GetGrain<IPlayerGrain>(playerId);
            IGameGrain game = null;
            while (game is null)
            {
                Console.WriteLine(
                    $"Getting current game for player {playerId}...");

                try
                {
                    game = await player.GetCurrentGame();
                    if (game is null) // Wait until the player joins a game
                    {
                        await Task.Delay(TimeSpan.FromMilliseconds(5_000));
                    }
                }
                catch (Exception ex)
                {
                    Console.WriteLine($"Exception: {ex.GetBaseException()}");
                }
            }

            Console.WriteLine(
                $"Subscribing to updates for game {game.GetPrimaryKey()}...");

            // Subscribe for updates
            var watcher = new GameObserver();
            await game.SubscribeForGameUpdates(
                await client.CreateObjectReference<IGameObserver>(watcher));

            Console.WriteLine(
                "Subscribed successfully. Press <Enter> to stop.");

            Console.ReadLine(); 
        }
        catch (Exception e)
        {
            Console.WriteLine(
                $"Unexpected Error: {e.GetBaseException()}");
        }
    }
}

/// <summary>
/// Observer class that implements the observer interface.
/// Need to pass a grain reference to an instance of
/// this class to subscribe for updates.
/// </summary>
class GameObserver : IGameObserver
{
    public void UpdateGameScore(string score)
    {
        Console.WriteLine("New game score: {0}", score);
    }
}