Skip to content

Integrate Settings Contribution Module

A contribution module is provided to declare and publish the messages that will be consumed from settings service.

It contains an API that allows the developer to specify Setting Groups, Setting Values and Frontend and Backend Setting Definitions.

Let's view an example of implementation of settings contribution in our service called 'Emailing'.

We will need to create a new module called 'EmailingSettingsModule' and it will depends on SettingsContributionModule.

The first thing to do is to add a reference to the settings contribution module project, as shown below:

XML
1
<ProjectReference Include="$(ServicesPath)Settings\ITsynch.Suite.Settings.Contribution\ITsynch.Suite.Settings.Contribution.csproj" />

And add the dependency in the settings module.

C#
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
public class EmailingSettingsModule : SuiteModule
{
    public override void SetupModule(IModuleBuilder builder)
    {
        base.SetupModule(builder);

        builder.AddOptions<EmailingSettingsOptions>();
        builder.AddOptions<EmailingSettingsModuleOptions>();
        builder.AddOptionsConfigurator<ConfigureContributeSettingsContributionModuleOptions, SettingsContributionModuleOptions>();
        builder.DependsOn<SettingsContributionModule, SettingsContributionModuleOptions>();
    }
}

Below is an example of the settings configuration using the contribution API:

C#
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
public static class SettingsContributionModuleOptionsExtensions
{
    private static readonly Guid PendingSendColorSettingDefinitionId = new("f7580000-4d23-00ff-a58a-08da64c801ef");
    private static readonly Guid EmailingSettingGroupId = new("16000000-ac11-0242-aef0-08dcf44ec2ab");

    public static void ConfigureSettings(this SettingsContributionModuleOptions options)
    {
        options.AddSettingGroup(
            correlationId: EmailingSettingGroupId,
            description: "Emailing Settings",
            order: 1);

    }

    private static void ConfigureEmailingDefinitions(SettingsContributionModuleOptions options)
    {
        const string moduleName = nameof(EmailingSettingsModule);
        options.AddFrontEndSettingDefinition<EmailingSettingsOptions>(
            correlationId: PendingSendColorSettingDefinitionId,
            displayName: "Pending Send Color",
            description: "Background color for pending send chip.",
            moduleName: moduleName,
            propertySelector: x => x.PendingSend,
            customType: "color",
            settingGroupId: EmailingSettingGroupId);
    }

    private static void ConfigureEmailingValues(SettingsContributionModuleOptions options)
    {
        options.AddSettingValue(
            correlationId: new Guid("f7580000-4d23-00ff-f72c-08da64c980a5"),
            settingDefinitionId: PendingSendColorSettingDefinitionId,
            value: EmailingSettingOptionsConstants.PendingSendColor,
            sharingLevelId: SharingLevelsConstants.RootSharingLevelId);
    }
}

Finally, let's see the IConfigureOptions of SettingsContributionModuleOptions:

C#
1
2
3
4
5
6
7
8
9
internal class ConfigureContributeSettingsContributionModuleOptions(IOptions<EmailingSettingsModuleOptions> emailingSettingsModuleOptions)
    : IConfigureOptions<SettingsContributionModuleOptions>
{
    public void Configure(SettingsContributionModuleOptions options)
    {
        options.EnableContribution = emailingSettingsModuleOptions.Value.EnableContribution;
        options.ConfigureSettings();
    }
}

Note that SettingsContributionModuleOptions has a property called 'EnableContribution'. Depending on that property, the consumer used to contribute the settings will either be registered or not. We will explain later why and when we will need to disable contribution.

This new module called 'EmailingSettingsModule' will be invoked from the application service and the bff service.

Note

The contribution must be in the services implemented in the office. This is because the configuration service is not implemented on the satellite, so if it is contributed from satellite the messages will never be consumed.

  • From the application service: Contribution starts from the service. When running the data seeder, a ContributeSettings message will be consumed and the contribution will start sending the corresponding creation and edition messages.

  • From the bff service: As we mentioned above, SettingsContribution has a 'EnableContribution' property. That property takes importance here since we just need that the EmailingSettings to be a known module. This will be needed later when contributing settings to the UI, only settings from the frontend and belonging to known modules will be contributed.

C#
1
2
3
4
5
6
7
8
9
public class AdminCenterBffModule : SuiteAspNetApplicationModule
{
    public override void SetupModule(IModuleBuilder builder)
    {
        base.SetupModule(builder);

        builder.DependsOn<EmailingSettingsModule, EmailingSettingsModuleOptions>(opts => opts.EnableContribution = false);
    }
}

Note

If the settings to be contributed are only of backend type, it is not necessary to depend on the contribution module from the bff service.