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`:

   ```csharp
   // 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:

```csharp
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

```csharp
// 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

```csharp
// 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

```csharp
// 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:

```csharp
// 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