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
})