Hosting Multiple Modules in One Package

By default, the apimodule and msgmodule project templates host a single module in the generated zip package. Additional modules can be added to a project.

Background

This topic covers how to add additional message or API modules to an existing package.

If your architecture requires multiple related modules, it is often more convenient to host them in a single project and deploy them as one zipped package. A package can contain a combination of message modules and API modules.

Prerequisites

.NET 8 SDK or higher.
ScaleOut Active Caching Project Templates for .NET
An existing API module project or message module project with at least one registered module.

Procedure

1. Add classes for the new module

Tip

Instead of manually creating classes as described in this step, you can create a temporary API or message module project and then move the generated classes into your existing project.

A. Add message module classes

If adding a message module to an existing package, determine which classes must be defined. At a minimum, a message module consists of the following:

A state class for storing data in your message module. This is often a simple POCO object with an ID property and other relevant state properties.
A message handler class that derives from MessageProcessor. This object implements message processing logic and factory methods for module infrastructure.
One or more message classes to be sent to the message processor by clients.

See Creating a Message Module Project for details on the classes required by message modules.

B. Add API module classes

If adding an API module to an existing package, determine which classes must be defined. At a minimum, an API module consists of the following:

A state class for storing data in your API module. This is often a simple POCO object with an ID property and other relevant state properties.
An API processor class that derives from ApiProcessor and implements endpoints for the API module’s methods.

See Creating an API Module Project for details on the classes required by API modules.

2. Register the processor in Startup.Configure

In your existing module’s Startup.cs class, modify the Configure() method to add your new MessageProcessor/ApiProcessor implementation to the ModulePackage using either AddMessageModule() or AddApiModule().

public void Configure(GridConnection gridConnection, ILogger logger, byte[] reservedParam, string packageName)
{
    // Host both an API module and a message module in the same package.
    var apiRegistration = _modulePackage.AddApiModule<ShoppingCartSossObject, ShoppingCartApiProcessor>("ShoppingCart");
    _modulePackage.AddMsgModule<MyStateObject, MyMessageProcessor>("MyMessageModule");
}

3. Add the module to scaleoutPackage.json

The scaleoutPackage.json file is a manifest used by the ScaleOut service to identify modules in the zipped package. Add the new module to the modules section of the JSON file.

{
  "cmdLineParams": "MyFirstApiPackage.dll",
  "modules": [
    {
      "moduleName": "ShoppingCart",
      "runtime": "dotnet",
      "moduleType": "api"
    },
    {
      "moduleName": "MyMessageModule",
      "runtime": "dotnet",
      "moduleType": "msg"
    }
  ]
}

Set the “moduleType” to “msg” if adding a message module. Set it to “api” if adding an API module.