Masterarbeit/QuellCode/CentronERP/docs/guides/development/settings-management.md

Settings Management in c-entron.NET

This guide explains how application settings are managed in the c-entron.NET project, covering both legacy and current approaches, and providing best practices for working with settings.

Overview

The c-entron.NET application uses two separate database tables for storing application settings:

1. Stammdat - Legacy settings table with historical settings
2. ApplicationSettings - Current table for new settings

This dual-table approach exists for historical reasons, and all new settings should be added to the ApplicationSettings table.

Settings Tables

Legacy: Stammdat Table

The Stammdat table contains many historical settings that are accessed through the AppSettingsConst enum.

• Enum File: src/backend/Centron.BL/Administration/Settings/AppSettingsConst.cs
• Access: Settings are accessed through the AppSettingsBL.GetSettings(AppSettingsConst) method
• Updates: Although we maintain these settings, no new settings should be added to this table

Current: ApplicationSettings Table

The ApplicationSettings table is the current standard for all new application settings.

• Enum File: src/backend/Centron.Interfaces/Administration/Settings/ApplicationSettingID.cs
• Next Free ID: Tracked in a comment at line 15 of ApplicationSettingID.cs
• Access: Settings are accessed through the AppSettingsBL.GetSettings(ApplicationSettingID) method
• Settings Descriptions: Defined in src/backend/Centron.Interfaces/Administration/Settings/ApplicationSettingDefinitions.cs

ID Management

When adding new settings, you must:

1. Check the next available ID from the comment in ApplicationSettingID.cs:

   // Next Centron Settings ID : 10370
   // Current Riverbird Settings ID : 50035
   

2. Use the next ID in sequence (in this case, 10370)

3. Update the comment with the next available ID after adding your setting

The Riverbird setting IDs (starting with 50xxx) are not used by c-entron.NET.

Setting Definitions

For each new setting in ApplicationSettingID.cs, you must add a corresponding description in the ApplicationSettingDefinitions.cs file:

case ApplicationSettingID.YourNewSetting:
    return "Description of what this setting does and how it's used.";

The description should clearly explain:

• The purpose of the setting
• What data it stores
• Any relevant format or validation constraints

Accessing Settings

Group Setting Classes

The client never accesses settings tables directly. Instead, we use "group setting classes" to manage related settings. These classes:

1. Load settings from the database
2. Provide a strongly-typed interface for accessing settings
3. Manage updating settings back to the database

Example: Loading Settings

// Example from ReceiptWebServiceBL.GetReceiptInvoiceSettings()
var appSettings = this._appSettingsBL.GetSettings
(
    ApplicationSettingID.InvoiceArchiveActive,
    ApplicationSettingID.IsZugferdInvoiceActive,
    // additional settings...
);

var settings = new ReceiptInvoiceSettingsDTO
{
    IsInvoiceArchiveActive = appSettings.GetBool(ApplicationSettingID.InvoiceArchiveActive, false),
    IsZugferdInvoiceActive = appSettings.GetBool(ApplicationSettingID.IsZugferdInvoiceActive, false),
    // map other settings...
};

return Result<ReceiptInvoiceSettingsDTO>.AsSuccess(settings);

Example: Saving Settings

// Example from ReceiptWebServiceBL.SaveReceiptInvoiceSettings()
var updateSettings = this._appSettingsBL.GetSettingsForUpdate
(
    ApplicationSettingID.InvoiceArchiveActive,
    ApplicationSettingID.IsZugferdInvoiceActive,
    // additional settings...
);

// Update values
updateSettings.UpdateBool(ApplicationSettingID.InvoiceArchiveActive, settings.IsInvoiceArchiveActive.Value);
updateSettings.UpdateBool(ApplicationSettingID.IsZugferdInvoiceActive, settings.IsZugferdInvoiceActive.Value);
// update other settings...

// Save all changes
updateSettings.SaveSettings();

return Result<bool>.AsSuccess(true);

API Integration

Settings are exposed through API methods, allowing client applications to retrieve and update settings.

API Patterns

1. All setting API methods must use HTTP POST
2. Get methods return a DTO containing the settings
3. Save methods accept a DTO with the settings to update

Example API Methods

// In ICentronRestService.cs
[WebInvoke(Method = "POST", ResponseFormat = WebMessageFormat.Json)]
Result<ReceiptInvoiceSettingsDTO> GetReceiptInvoiceSettings();

[WebInvoke(Method = "POST", ResponseFormat = WebMessageFormat.Json)]
Result<bool> SaveReceiptInvoiceSettings(ReceiptInvoiceSettingsDTO settings);

Best Practices

Adding New Settings

1. Use the next available ID from the comment in ApplicationSettingID.cs
2. Add your setting to the ApplicationSettingID enum
3. Update the "Next Centron Settings ID" comment
4. Add a detailed description in ApplicationSettingDefinitions.cs
5. Create or update group setting classes to access your setting

Setting Types

Application settings support multiple data types:

• Boolean: Use GetBool() / UpdateBool() methods
• Integer: Use GetInt() / UpdateInt() methods
• String: Use GetString() / UpdateString() methods
• Large String: Use GetLargeString() / UpdateLargeString() methods
• Enum: Use GetEnum<T>() / UpdateEnum<T>() methods
• Decimal: Use GetDecimal() / UpdateDecimal() methods

Default Values

When retrieving settings, always provide a default value in case the setting doesn't exist:

// Example with default value
bool isActive = appSettings.GetBool(ApplicationSettingID.SomeSetting, false);

Common Scenarios

Creating a New Group Settings Class

1. Define a DTO class to hold the settings
2. Create Get method that loads settings from AppSettingsBL
3. Create Save method that updates settings with AppSettingsBL
4. Add corresponding API methods

Migrating Legacy Settings

When migrating settings from Stammdat to ApplicationSettings:

1. Add the new setting to ApplicationSettingID
2. Add its description to ApplicationSettingDefinitions
3. Update code to read from both sources during transition
4. Eventually remove the old setting access after migration