AppSettings Configuration Guide¶

This document explains the different appsettings.*.json files and when each one is used in Cesivi.

Configuration Loading Order¶

ASP.NET Core loads configuration files in a specific order, with later files overriding earlier ones:

appsettings.json (base configuration - always loaded)
appsettings.{Environment}.json (environment-specific - depends on ASPNETCORE_ENVIRONMENT)

The ASPNETCORE_ENVIRONMENT variable determines which environment-specific file is loaded.

Available Configurations¶

appsettings.json¶

When Used: Always loaded first as the base configuration Location: Cesivi.Server/appsettings.json

Purpose: Default production-ready settings

Key Settings: - Default log level: Information - Data root: R:/MockData (RAM disk for performance) - Default ports: HTTP 5000, HTTPS 5001 - Authentication: Accept all credentials enabled - Storage provider: FileSystem

Use Case: Production deployment, default behavior

appsettings.Development.json¶

When Used: When ASPNETCORE_ENVIRONMENT=Development Location: Cesivi.Server/appsettings.Development.json

Purpose: Local development settings

Key Settings: - Data root: ../MockData (relative path) - Hostname: localhost - Ports: HTTP 5010, HTTPS 5011 (branch-aware via environment variables) - Microsoft.AspNetCore logging: Information (more verbose) - Feature flags: All enabled including detailed errors

Use Case: - Running from Visual Studio - Local development with dotnet run - F5 debugging - Default when no environment is specified

Environment Variable Overrides: The Development environment respects these environment variables: - CESIVI_HTTP_PORT - Overrides HTTP port (for multi-branch development) - CESIVI_HTTPS_PORT - Overrides HTTPS port - CESIVI_DATA_PATH - Overrides data root path

appsettings.Production.json¶

When Used: When ASPNETCORE_ENVIRONMENT=Production Location: Cesivi.Server/appsettings.Production.json

Purpose: Production deployment settings

Key Settings: - Data root: /app/MockData (container path) - Microsoft.AspNetCore logging: Warning (less verbose) - Feature flags: Detailed errors disabled

Use Case: - Production server deployment - When you need minimal logging for performance

appsettings.Docker.json¶

When Used: When ASPNETCORE_ENVIRONMENT=Docker Location: Cesivi.Server/appsettings.Docker.json

Purpose: Docker container deployment settings

Key Settings: - Data root: /app/MockData (mapped to volume) - Log path: /app/MockData/Logs - Ports: HTTP 8080, HTTPS 443 - JSON console logging with single-line format - Compression enabled - Health check and diagnostics enabled - Connection limits configured

Use Case: - Running in Docker container - Kubernetes deployment - Any containerized deployment

Docker Command:

docker run -e ASPNETCORE_ENVIRONMENT=Docker -p 8080:8080 cesivi

appsettings.Testing.json¶

When Used: When ASPNETCORE_ENVIRONMENT=Testing Location: Cesivi.Server/appsettings.Testing.json

Purpose: Automated test execution

Key Settings: - (Specific to test configuration)

Use Case: - Running automated tests - CI/CD pipelines - Test environments

Note: Request logging middleware is disabled in Testing environment to prevent file locking issues during parallel test execution.

appsettings.Test.json¶

When Used: When ASPNETCORE_ENVIRONMENT=Test Location: Cesivi.Server/appsettings.Test.json

Purpose: Manual testing

Key Settings: - (Specific to manual test configuration)

Use Case: - Manual testing scenarios - QA environments

appsettings.Staging.json¶

When Used: When ASPNETCORE_ENVIRONMENT=Staging Location: Cesivi.Server/appsettings.Staging.json

Purpose: Pre-production staging

Key Settings: - (Specific to staging configuration)

Use Case: - Staging environment testing - Pre-production validation

appsettings.Plugins.json¶

When Used: When ASPNETCORE_ENVIRONMENT=Plugins Location: Cesivi.Server/appsettings.Plugins.json

Purpose: Plugin development and testing

Key Settings: - (Plugin-specific configuration)

Use Case: - Developing custom plugins - Testing plugin integration

Command-Line Overrides (CLI Switches)¶

Both Cesivi.Server and Cesivi.WebUI support friendly command-line switches that map to configuration keys. These override all other configuration sources (environment files, appsettings.json).

Server Switches¶

Switch	Maps To	Example
`--port`	`Cesivi:HttpPort`	`--port 5070`
`--https-port`	`Cesivi:HttpsPort`	`--https-port 5071`
`--data`	`Cesivi:DataRootPath`	`--data ./MyData`
`--log`	`Cesivi:LogPath`	`--log /var/log/cesivi`
`--storage`	`Cesivi:StorageProvider`	`--storage Sqlite`
`--hostname`	`Cesivi:HostName`	`--hostname cesivi.local`
`--https`	`Cesivi:UseHttps`	`--https true`

Example:

dotnet Cesivi.dll --port 5070 --data ./MyData --storage Sqlite

WebUI Switches¶

Switch	Maps To	Example
`--port`	`WebUI:HttpPort`	`--port 5570`
`--https-port`	`WebUI:HttpsPort`	`--https-port 5571`
`--https`	`WebUI:UseHttps`	`--https true`
`--backend`	`CesiviClient:BaseUrl`	`--backend http://localhost:5070`
`--log`	`WebUI:LogPath`	`--log /var/log/cesivi-webui`
`--auth`	`WebUI:Authentication:DefaultProvider`	`--auth Windows`

Example:

dotnet Cesivi.WebUI.dll --port 5570 --backend http://localhost:5070

Notes¶

Switches follow standard .NET AddCommandLine switch mapping — they must start with --
Standard ASP.NET Core arguments (e.g., --urls, --environment) also work alongside these
When using custom config files (--config), switches still override depending on config priority mode (see below)

How to Set Environment¶

Visual Studio / Visual Studio Code¶

Edit launchSettings.json:

{
  "profiles": {
    "Cesivi.Server": {
      "commandName": "Project",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Command Line¶

# Windows (PowerShell)
$env:ASPNETCORE_ENVIRONMENT="Development"
dotnet run

# Windows (CMD)
set ASPNETCORE_ENVIRONMENT=Development
dotnet run

# Linux/Mac
export ASPNETCORE_ENVIRONMENT=Development
dotnet run

Docker¶

docker run -e ASPNETCORE_ENVIRONMENT=Docker cesivi

Azure App Service¶

Set in Application Settings: - Key: ASPNETCORE_ENVIRONMENT - Value: Production

Logging Configuration¶

All appsettings files can configure logging through the Logging section:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Cesivi": "Information"
    }
  }
}

Log Levels (from most to least verbose)¶

Trace - Very detailed, potentially sensitive information
Debug - Detailed diagnostic information (iteration markers, internal state)
Information - General informational messages (requests, startup)
Warning - Unexpected events that don't stop execution
Error - Errors and exceptions
Critical - Critical failures requiring immediate attention

Recommended Settings by Environment¶

Development:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Information",
      "Cesivi": "Debug"
    }
  }
}

Production:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Cesivi": "Information"
    }
  }
}

Troubleshooting:

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug",
      "Microsoft.AspNetCore": "Debug",
      "Cesivi": "Debug"
    }
  }
}

Request Logging¶

Cesivi uses RequestLoggingMiddleware to log HTTP requests.

Information Level Output: - Request method and path - Response status code - Processing duration - No headers or bodies

Debug Level Output: - Full request headers - Request body (for POST/PUT) - Response headers - Response body

To Disable Request Logging: Set environment to "Testing" - the middleware is automatically disabled.

Common Scenarios¶

Scenario 1: Local Development with Branch-Specific Ports¶

Environment: Development Method: Use environment variables

$env:CESIVI_HTTP_PORT="5010"
$env:CESIVI_HTTPS_PORT="5011"
$env:CESIVI_DATA_PATH="../MockData"
dotnet run

Scenario 2: Docker Deployment¶

Environment: Docker

docker run -e ASPNETCORE_ENVIRONMENT=Docker \
  -p 8080:8080 \
  -v /data/sharepoint:/app/MockData \
  cesivi

Scenario 3: Running Automated Tests¶

Environment: Testing

$env:ASPNETCORE_ENVIRONMENT="Testing"
dotnet test

Scenario 4: Production with Custom Data Path¶

Environment: Production

$env:ASPNETCORE_ENVIRONMENT="Production"
$env:CESIVI_DATA_PATH="/srv/sharepoint-data"
dotnet Cesivi.Server.dll

Troubleshooting¶

Problem: Configuration not loading¶

Check: 1. Verify ASPNETCORE_ENVIRONMENT is set correctly 2. Check file exists: appsettings.{Environment}.json 3. Ensure file is copied to output directory (Build Action: Content, Copy if newer)

Problem: Seeing too many log messages¶

Solution: - Set Microsoft.AspNetCore to Warning - Set Cesivi to Information or Warning - Use Production environment

Problem: Not seeing request details¶

Solution: - Set log level to Debug - Check that environment is NOT "Testing" (request logging disabled) - Verify RequestLoggingMiddleware is registered in Program.cs