Akka.Hosting 1.5.2

• Update Akka.NET to 1.5.2
• Bump Akka.Persistence.PostgreSql to 1.5.2
• Bump Akka.Persistence.SqlServer to 1.5.2
• Persistence: Change persistence default serializer from json to null
Major Changes
• Persistence.Hosting default value for default serializer has been changed from json to null. This only affects persistence write and not reads. All objects with no serializer mapping will now be serialized using Akka default object serializer. If you have old persistence data where they do not have their serializer ID column populated%2C you will need to change this setting.
Inherited Changes From Akka.NET Core
• Persistence will now ignore the serializer setting inside journal settings when writing new events. This setting will only be used when data retrieved from the database does not have the serializer id column unpopulated.
• Cluster.Hosting%2C by default%2C will have SplitBrainResolver enabled.

1.5.1.1

• Fix missing default DData configuration in cluster hosting extension

Akka.Hosting 1.5.1

• Update Akka.NET to 1.5.1
• Bump Akka.Persistence.PostgreSql to 1.5.1
• Bump Akka.Persistence.SqlServer to 1.5.1
• Add GetAsync method to IRequiredActor to resolve IActorRef in background services
• Add cluster Distributed Data options support for Akka.Cluster.Hosting extensions

Akka.Hosting 1.5.0

Version 1.5.0 is the RTM release of Akka.Hosting and Akka.NET v1.5.0 RTM integration.
Full changes
• Update Akka.NET to 1.5.0
• Fix missing cluster configuration on certain edge cases
• Add new Cluster.Sharding RememberEntitiesStore
• Add Cluster.Sharding journal migration adapter convenience method
• Add LogMessageFormatter formatter support to logging

Upgrading From v1.4 To v1.5

As noted in the upgrade advisories%2C there was some major changes inside Akka.NET that directly affects Akka.Hosting. To upgrade from v1.4 to v1.5%2C please watch our video here covering this process.

1.5.0-beta6

• Update Akka.NET to 1.5.0-beta6

1.5.0-beta4

Version 1.5.0-beta4 integrates Akka.NET v1.5 into Akka.Hosting
• Update Akka.NET to 1.5.0-beta4

Upgrading From v1.4 To v1.5

As noted in the upgrade advisories%2C there was a major change in Akka.Cluster.Sharding state storage. These notes contains the same documentation%2C but tailored for Akka.Hosting users
The recommended settings for maximum ease-of-use for Akka.Cluster.Sharding in new applications going forward will be:

var options = new ShardOptions
{
    StateStoreMode = StateStoreMode.DData%2C
    RememberEntitiesStore = RememberEntitiesStore.Eventsourced
}

You will need to set these options manually because the default settings are set for backward compatibility.

Migrating to New Sharding Storage From Akka.Persistence

NOTE

This section applies only to users who were using StateStoreMode = StateStoreMode.Persistence.
Switching over to using RememberEntitiesStore = RememberEntitiesStore.Eventsourced will cause an initial migration of data from the ShardCoordinator's journal into separate event journals going forward.
Upgrading to Akka.NET v1.5 will *cause an irreversible migration of Akka.Cluster.Sharding data• for users who were previously running StateStoreMode = StateStoreMode.Persistence%2C so follow the steps below carefully:

Step 1 • Upgrade to Akka.NET v1.5 With New Options Setup

Update your Akka.Cluster.Sharding options to look like the following (adjust as necessary for your custom settings):

hostBuilder.Services.AddAkka("MyActorSystem"%2C builder =>
{
    var shardOptions = new ShardOptions
    {
        // If you don't run Akka.Cluster.Sharding with RememberEntities = true%2C
        // then set this to false
        RememberEntities = true%2C
        RememberEntitiesStore = RememberEntitiesStore.Eventsourced%2C
        StateStoreMode = StateStoreMode.Persistence%2C
        //fail if upgrade doesn't succeed
        FailOnInvalidEntityStateTransition = true
    }
    // Modify these two options to suit your application%2C SqlServer used
    // only as an illustration
    var journalOptions = new SqlServerJournalOptions()%3B
    var snapshotOptions = new SqlServerSnapshotOptions()%3B
    builder
        .WithClustering()
        .WithSqlServerPersistence(journalOptions%2C snapshotOptions)
        .WithShardRegion<UserActionsEntity>(
            "userActions"%2C 
            s => UserActionsEntity.Props(s)%2C
            new UserMessageExtractor()%2C
            // shardOptions is being used here
            shardOptions)%3B
    // Add the Akka.Cluster.Sharding migration journal event adapter
    builder.WithClusterShardingJournalMigrationAdapter(journalOptions)%3B
    // you can also declare the adapter by referencing the journal ID directly
    builder.WithClusterShardingJournalMigrationAdapter("akka.persistence.journal.sql-server")%3B
})
```

With these HOCON settings in-place the following will happen:
1. The old PersitentShardCoordinator state will be broken up • Remember entities data will be distributed to each of the PersistentShard actors%2C who will now use the new RememberEntitiesStore = RememberEntitiesStore.Eventsourced setting going forward%3B
2. Old Akka.Cluster.Sharding.ShardCoordinator.IDomainEvent events will be upgraded to a new storage format via the injected Akka.Persistence event adapter%3B and
3. The PersistentShardCoordinator will migrate its journal to the new format as well.

##### Step 2 • Migrating Away From Persistence to DData

Once your cluster has successfully booted up with these settings%2C you can now optionally move to using distributed data to store sharding state by changing StateStoreMode = StateStoreMode.DData and deploying a second time:

```csharp
hostBuilder.Services.AddAkka("MyActorSystem"%2C builder =>
{
    var shardOptions = new ShardOptions
    {
        RememberEntities = true%2C
        RememberEntitiesStore = RememberEntitiesStore.Eventsourced%2C
        // Change this line of code
        StateStoreMode = StateStoreMode.DData%2C
        FailOnInvalidEntityStateTransition = true
    }%3B
    var journalOptions = new SqlServerJournalOptions()%3B
    var snapshotOptions = new SqlServerSnapshotOptions()%3B
    builder
        .WithClustering()
        .WithSqlServerPersistence(journalOptions%2C snapshotOptions)
        .WithShardRegion<UserActionsEntity>(
            "userActions"%2C 
            s => UserActionsEntity.Props(s)%2C
            new UserMessageExtractor()%2C
            shardOptions)%3B
    builder.WithClusterShardingJournalMigrationAdapter(journalOptions)%3B
})```

Now you'll be running Akka.Cluster.Sharding with the recommended settings.
#### Migrating to New Sharding Storage From Akka.DistributedData
The migration process onto Akka.NET v1.5's new Cluster.Sharding storage system is less involved for users who were already using StateStoreMode = StateStoreMode.DData. All these users need to do is change the RememberEntitiesStore option to RememberEntitiesStore.Eventsourced
csharp
hostBuilder.Services.AddAkka("MyActorSystem"%2C builder =>
{
    var shardOptions = new ShardOptions
    {
        RememberEntities = true%2C
        // Use this option setting
        RememberEntitiesStore = RememberEntitiesStore.Eventsourced%2C
        StateStoreMode = StateStoreMode.DData%2C
        FailOnInvalidEntityStateTransition = true
    }%3B
    var journalOptions = new SqlServerJournalOptions()%3B
    var snapshotOptions = new SqlServerSnapshotOptions()%3B
    builder
        .WithClustering()
        .WithSqlServerPersistence(journalOptions%2C snapshotOptions)
        .WithShardRegion<UserActionsEntity>(
            "userActions"%2C 
            s => UserActionsEntity.Props(s)%2C
            new UserMessageExtractor()%2C
            shardOptions)%3B
    builder.WithClusterShardingJournalMigrationAdapter(journalOptions)%3B
})

1.5.0-beta3

Version 1.5.0-beta3 integrates Akka.NET v1.5 into Akka.Hosting
• Update Akka.NET to 1.5.0-beta3

Upgrading From v1.4 To v1.5

As noted in the upgrade advisories%2C there was a major change in Akka.Cluster.Sharding state storage. These notes contains the same documentation%2C but tailored for Akka.Hosting users
The recommended settings for maximum ease-of-use for Akka.Cluster.Sharding in new applications going forward will be:
csharp
var options = new ShardOptions
{
StateStoreMode = StateStoreMode.DData%2C
RememberEntitiesStore = RememberEntitiesStore.Eventsourced
}%3B

You will need to set these options manually because the default settings are set for backward compatibility.

Migrating to New Sharding Storage From Akka.Persistence

NOTE

This section applies only to users who were using StateStoreMode = StateStoreMode.Persistence.
Switching over to using RememberEntitiesStore = RememberEntitiesStore.Eventsourced will cause an initial migration of data from the ShardCoordinator's journal into separate event journals going forward.
Upgrading to Akka.NET v1.5 will *cause an irreversible migration of Akka.Cluster.Sharding data• for users who were previously running StateStoreMode = StateStoreMode.Persistence%2C so follow the steps below carefully:

Step 1 • Upgrade to Akka.NET v1.5 With New Options Setup

Update your Akka.Cluster.Sharding options to look like the following (adjust as necessary for your custom settings):
csharp
hostBuilder.Services.AddAkka("MyActorSystem"%2C builder =>
{
var shardOptions = new ShardOptions
{
// If you don't run Akka.Cluster.Sharding with RememberEntities = true%2C
// then set this to false
RememberEntities = true%2C
RememberEntitiesStore = RememberEntitiesStore.Eventsourced%2C
StateStoreMode = StateStoreMode.Persistence%2C
//fail if upgrade doesn't succeed
FailOnInvalidEntityStateTransition = true
}%3B
// Modify these two options to suit your application%2C SqlServer used
// only as an illustration
var journalOptions = new SqlServerJournalOptions()%3B
var snapshotOptions = new SqlServerSnapshotOptions()%3B
builder
.WithClustering()
.WithSqlServerPersistence(journalOptions%2C snapshotOptions)
.WithShardRegion(
"userActions"%2C
s => UserActionsEntity.Props(s)%2C
new UserMessageExtractor()%2C
// shardOptions is being used here
shardOptions)%3B
// Add the Akka.Cluster.Sharding migration journal event adapter
builder.WithClusterShardingJournalMigrationAdapter(journalOptions)%3B
// you can also declare the adapter by referencing the journal ID directly
builder.WithClusterShardingJournalMigrationAdapter("akka.persistence.journal.sql-server")%3B
})

With these HOCON settings in-place the following will happen:

1. The old PersitentShardCoordinator state will be broken up • Remember entities data will be distributed to each of the PersistentShard actors%2C who will now use the new RememberEntitiesStore = RememberEntitiesStore.Eventsourced setting going forward%3B
2. Old Akka.Cluster.Sharding.ShardCoordinator.IDomainEvent events will be upgraded to a new storage format via the injected Akka.Persistence event adapter%3B and
3. The PersistentShardCoordinator will migrate its journal to the new format as well.

Step 2 • Migrating Away From Persistence to DData

Once your cluster has successfully booted up with these settings%2C you can now optionally move to using distributed data to store sharding state by changing StateStoreMode = StateStoreMode.DData and deploying a second time:
csharp
hostBuilder.Services.AddAkka("MyActorSystem"%2C builder =>
{
var shardOptions = new ShardOptions
{
RememberEntities = true%2C
RememberEntitiesStore = RememberEntitiesStore.Eventsourced%2C
// Change this line of code
StateStoreMode = StateStoreMode.DData%2C
FailOnInvalidEntityStateTransition = true
}%3B
var journalOptions = new SqlServerJournalOptions()%3B
var snapshotOptions = new SqlServerSnapshotOptions()%3B
builder
.WithClustering()
.WithSqlServerPersistence(journalOptions%2C snapshotOptions)
.WithShardRegion(
"userActions"%2C
s => UserActionsEntity.Props(s)%2C
new UserMessageExtractor()%2C
shardOptions)%3B
builder.WithClusterShardingJournalMigrationAdapter(journalOptions)%3B
})

Now you'll be running Akka.Cluster.Sharding with the recommended settings.

Migrating to New Sharding Storage From Akka.DistributedData

The migration process onto Akka.NET v1.5's new Cluster.Sharding storage system is less involved for users who were already using StateStoreMode = StateStoreMode.DData. All these users need to do is change the RememberEntitiesStore option to RememberEntitiesStore.Eventsourced
csharp
hostBuilder.Services.AddAkka("MyActorSystem"%2C builder =>
{
var shardOptions = new ShardOptions
{
RememberEntities = true%2C
// Use this option setting
RememberEntitiesStore = RememberEntitiesStore.Eventsourced%2C
StateStoreMode = StateStoreMode.DData%2C
FailOnInvalidEntityStateTransition = true
}%3B
var journalOptions = new SqlServerJournalOptions()%3B
var snapshotOptions = new SqlServerSnapshotOptions()%3B
builder
.WithClustering()
.WithSqlServerPersistence(journalOptions%2C snapshotOptions)
.WithShardRegion(
"userActions"%2C
s => UserActionsEntity.Props(s)%2C
new UserMessageExtractor()%2C
shardOptions)%3B
builder.WithClusterShardingJournalMigrationAdapter(journalOptions)%3B
})

Akka.Hosting v1.5.0-alpha4

[1.5.0-alpha4] / 17 February 2023

Version 1.5.0-alpha4 integrates Akka.NET v1.5 into Akka.Hosting

• Implement new cluster sharding options
• Add cluster sharding migration journal event adapter extension method
• Update Akka.NET to 1.5.0-alpha4

Upgrading From v1.4 To v1.5

As noted in the upgrade advisories, there was a major change in Akka.Cluster.Sharding state storage. These notes contains the same documentation, but tailored for Akka.Hosting users

The recommended settings for maximum ease-of-use for Akka.Cluster.Sharding in new applications going forward will be:

var options = new ShardOptions
{
    StateStoreMode = StateStoreMode.DData,
    RememberEntitiesStore = RememberEntitiesStore.Eventsourced
};

You will need to set these options manually because the default settings are set for backward compatibility.

Migrating to New Sharding Storage From Akka.Persistence

NOTE

This section applies only to users who were using StateStoreMode = StateStoreMode.Persistence.

Switching over to using RememberEntitiesStore = RememberEntitiesStore.Eventsourced will cause an initial migration of data from the ShardCoordinator's journal into separate event journals going forward.

Upgrading to Akka.NET v1.5 will cause an irreversible migration of Akka.Cluster.Sharding data for users who were previously running StateStoreMode = StateStoreMode.Persistence, so follow the steps below carefully:

Step 1 - Upgrade to Akka.NET v1.5 With New Options Setup

Update your Akka.Cluster.Sharding options to look like the following (adjust as necessary for your custom settings):

hostBuilder.Services.AddAkka("MyActorSystem", builder =>
{
    var shardOptions = new ShardOptions
    {
        // If you don't run Akka.Cluster.Sharding with `RememberEntities = true`,
        // then set this to false
        RememberEntities = true,
        RememberEntitiesStore = RememberEntitiesStore.Eventsourced,
        StateStoreMode = StateStoreMode.Persistence,
    
        //fail if upgrade doesn't succeed
        FailOnInvalidEntityStateTransition = true
    };

    // Modify these two options to suit your application, SqlServer used
    // only as an illustration
    var journalOptions = new SqlServerJournalOptions();
    var snapshotOptions = new SqlServerSnapshotOptions();

    builder
        .WithClustering()
        .WithSqlServerPersistence(journalOptions, snapshotOptions)
        .WithShardRegion<UserActionsEntity>(
            "userActions", 
            s => UserActionsEntity.Props(s),
            new UserMessageExtractor(),
            // shardOptions is being used here
            shardOptions);
    
    // Add the Akka.Cluster.Sharding migration journal event adapter
    builder.WithClusterShardingJournalMigrationAdapter(journalOptions);
    
    // you can also declare the adapter by referencing the journal ID directly
    builder.WithClusterShardingJournalMigrationAdapter("akka.persistence.journal.sql-server");
})

With these HOCON settings in-place the following will happen:

1. The old PersitentShardCoordinator state will be broken up - Remember entities data will be distributed to each of the PersistentShard actors, who will now use the new RememberEntitiesStore = RememberEntitiesStore.Eventsourced setting going forward;
2. Old Akka.Cluster.Sharding.ShardCoordinator.IDomainEvent events will be upgraded to a new storage format via the injected Akka.Persistence event adapter; and
3. The PersistentShardCoordinator will migrate its journal to the new format as well.

Step 2 - Migrating Away From Persistence to DData

Once your cluster has successfully booted up with these settings, you can now optionally move to using distributed data to store sharding state by changing StateStoreMode = StateStoreMode.DData and deploying a second time:

hostBuilder.Services.AddAkka("MyActorSystem", builder =>
{
    var shardOptions = new ShardOptions
    {
        RememberEntities = true,
        RememberEntitiesStore = RememberEntitiesStore.Eventsourced,
        // Change this line of code
        StateStoreMode = StateStoreMode.DData,
    
        FailOnInvalidEntityStateTransition = true
    };

    var journalOptions = new SqlServerJournalOptions();
    var snapshotOptions = new SqlServerSnapshotOptions();

    builder
        .WithClustering()
        .WithSqlServerPersistence(journalOptions, snapshotOptions)
        .WithShardRegion<UserActionsEntity>(
            "userActions", 
            s => UserActionsEntity.Props(s),
            new UserMessageExtractor(),
            shardOptions);
    
    builder.WithClusterShardingJournalMigrationAdapter(journalOptions);
})

Now you'll be running Akka.Cluster.Sharding with the recommended settings.

Migrating to New Sharding Storage From Akka.DistributedData

The migration process onto Akka.NET v1.5's new Cluster.Sharding storage system is less involved for users who were already using StateStoreMode = StateStoreMode.DData. All these users need to do is change the RememberEntitiesStore option to RememberEntitiesStore.Eventsourced

hostBuilder.Services.AddAkka("MyActorSystem", builder =>
{
    var shardOptions = new ShardOptions
    {
        RememberEntities = true,
        // Use this option setting
        RememberEntitiesStore = RememberEntitiesStore.Eventsourced,
        StateStoreMode = StateStoreMode.DData,
    
        FailOnInvalidEntityStateTransition = true
    };

    var journalOptions = new SqlServerJournalOptions();
    var snapshotOptions = new SqlServerSnapshotOptions();

    builder
        .WithClustering()
        .WithSqlServerPersistence(journalOptions, snapshotOptions)
        .WithShardRegion<UserActionsEntity>(
            "userActions", 
            s => UserActionsEntity.Props(s),
            new UserMessageExtractor(),
            shardOptions);
    
    builder.WithClusterShardingJournalMigrationAdapter(journalOptions);
})

1.0.3

• Update Akka.NET from 1.4.45 to 1.4.46
• Remove default HoconAddMode value from AddHocon and AddHoconFile
• First release of Akka.Hosting.TestKit NuGet package

1.0.2

Version 1.0.2 introduces a new method to the ActorRegistry.GetAsync in order to allow users to force parts of their application to wait until a specific IActorRef has been started and added to the ActorRegistry.

// arrange
var registry = new ActorRegistry();

// act
var task = registry.GetAsync<Nobody>();
task.IsCompletedSuccessfully.Should().BeFalse();

registry.Register<Nobody>(Nobody.Instance);
var result = await task;

// assert
result.Should().Be(Nobody.Instance);

This method is designed to allow users to wait via async Task<IActorRef> for an actor to be registered in the event that a specific IRequiredActor<TKey> is needed before Akka.Hosting can start the ActorSystem inside its IHostedService.