Training
Module
Build your first Orleans app with ASP.NET Core 8.0 - Training
Learn how to build cloud-native, distributed apps with Orleans.
This browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
Orleans can be hosted on Azure Service Fabric using the Microsoft.ServiceFabric.Services and Microsoft.Orleans.Server NuGet packages. Silos should be hosted as unpartitioned, stateless services since Orleans manages the distribution of grains itself. Other hosting options, such as partitioned and stateful, are more complex and yield no benefits without additional customization on the part of the developer. It's recommended to host Orleans unpartitioned and stateless.
Whether you're creating a new Service Fabric Application or adding Orleans to an existing one, you'll need both the Microsoft.ServiceFabric.Services
and Microsoft.Orleans.Server
package references in your project. The stateless service project needs an implementation on the ICommunicationListener and a subclass of the StatelessService.
The Silo lifecycle follows the typical communication listener lifecycle:
Since Orleans Silos are capable of living within the confines of the IHost, the implementation of the ICommunicationListener
is a wrapper around the IHost
. The IHost
is initialized in the OpenAsync
method and gracefully terminated in the CloseAsync
method:
ICommunicationListener |
IHost interactions |
---|---|
OpenAsync | The IHost instance is created and a call to StartAsync is made. |
CloseAsync | A call to StopAsync on the host instance is awaited. |
Abort | A call to StopAsync is forcefully evaluated, with GetAwaiter().GetResult() . |
Official clustering support is available from various packages including:
There are also several third-party packages available for other services such as CosmosDB, Kubernetes, Redis, and Aerospike. For more information, see Cluster management in Orleans.
In the stateless service project, implement the ICommunicationListener
interface as shown in the following example:
using Microsoft.Extensions.Hosting;
using Microsoft.ServiceFabric.Services.Communication.Runtime;
namespace ServiceFabric.HostingExample;
internal sealed class HostedServiceCommunicationListener : ICommunicationListener
{
private IHost? _host;
private readonly Func<Task<IHost>> _createHost;
public HostedServiceCommunicationListener(Func<Task<IHost>> createHost) =>
_createHost = createHost ?? throw new ArgumentNullException(nameof(createHost));
/// <inheritdoc />
public async Task<string?> OpenAsync(CancellationToken cancellationToken)
{
try
{
_host = await _createHost.Invoke();
await _host.StartAsync(cancellationToken);
}
catch
{
Abort();
throw;
}
// This service does not expose any endpoints to Service Fabric for discovery by others.
return null;
}
/// <inheritdoc />
public async Task CloseAsync(CancellationToken cancellationToken)
{
if (_host is { } host)
{
await host.StopAsync(cancellationToken);
}
_host = null;
}
/// <inheritdoc />
public void Abort()
{
IHost? host = _host;
if (host is null)
{
return;
}
using CancellationTokenSource cancellation = new();
cancellation.Cancel(false);
try
{
host.StopAsync(cancellation.Token).GetAwaiter().GetResult();
}
catch
{
// Ignore.
}
finally
{
_host = null;
}
}
}
The HostedServiceCommunicationListener
class accepts a Func<Task<IHost>> createHost
constructor parameter. This is later used to create the IHost
instance in the OpenAsync
method.
The next part of the stateless service project is to implement the StatelessService
class. The following example shows the subclass of the StatelessService
class:
using System.Fabric;
using Microsoft.Extensions.Hosting;
using Microsoft.ServiceFabric.Services.Communication.Runtime;
using Microsoft.ServiceFabric.Services.Runtime;
namespace ServiceFabric.HostingExample;
public sealed class OrleansHostedStatelessService : StatelessService
{
private readonly Func<StatelessServiceContext, Task<IHost>> _createHost;
public OrleansHostedStatelessService(
Func<StatelessServiceContext, Task<IHost>> createHost, StatelessServiceContext serviceContext)
: base(serviceContext) =>
_createHost = createHost ?? throw new ArgumentNullException(nameof(createHost));
/// <inheritdoc/>
protected sealed override IEnumerable<ServiceInstanceListener> CreateServiceInstanceListeners()
{
// Create a listener which creates and runs an IHost
yield return new ServiceInstanceListener(
context => new HostedServiceCommunicationListener(() => _createHost(context)),
nameof(HostedServiceCommunicationListener));
}
}
In the preceding example, the OrleansHostedStatelessService
class is responsible for yielding an ICommunicationListener
instance. The CreateServiceInstanceListeners
method is called by the Service Fabric runtime when the service is initialized.
Pulling these two classes together, the following example shows the complete stateless service project Program.cs file:
using System.Fabric;
using Microsoft.Extensions.Hosting;
using Microsoft.ServiceFabric.Services.Runtime;
using ServiceFabric.HostingExample;
try
{
// The ServiceManifest.XML file defines one or more service type names.
// Registering a service maps a service type name to a .NET type.
// When Service Fabric creates an instance of this service type,
// an instance of the class is created in this host process.
await ServiceRuntime.RegisterServiceAsync(
"Orleans.ServiceFabric.Stateless",
context => new OrleansHostedStatelessService(
CreateHostAsync, context));
ServiceEventSource.Current.ServiceTypeRegistered(
Environment.ProcessId,
typeof(OrleansHostedStatelessService).Name);
// Prevents this host process from terminating so services keep running.
await Task.Delay(Timeout.Infinite);
}
catch (Exception ex)
{
ServiceEventSource.Current.ServiceHostInitializationFailed(
ex.ToString());
throw;
}
static async Task<IHost> CreateHostAsync(StatelessServiceContext context)
{
await Task.CompletedTask;
return Host.CreateDefaultBuilder()
.UseOrleans((_, builder) =>
{
// TODO, Use real storage, something like table storage
// or SQL Server for clustering.
builder.UseLocalhostClustering();
// Service Fabric manages port allocations, so update the
// configuration using those ports. Gather configuration from
// Service Fabric.
var activation = context.CodePackageActivationContext;
var endpoints = activation.GetEndpoints();
// These endpoint names correspond to TCP endpoints
// specified in ServiceManifest.xml
var siloEndpoint = endpoints["OrleansSiloEndpoint"];
var gatewayEndpoint = endpoints["OrleansProxyEndpoint"];
var hostname = context.NodeContext.IPAddressOrFQDN;
builder.ConfigureEndpoints(hostname,
siloEndpoint.Port, gatewayEndpoint.Port);
})
.Build();
}
In the preceding code:
OrleansHostedStatelessService
class with the Service Fabric runtime.CreateHostAsync
delegate is used to create the IHost
instance..NET feedback
.NET is an open source project. Select a link to provide feedback:
Training
Module
Build your first Orleans app with ASP.NET Core 8.0 - Training
Learn how to build cloud-native, distributed apps with Orleans.