Branch-Based Configuration Guide¶

Overview¶

Cesivi Server supports git branch-based configuration to enable running multiple working trees with different ports and isolated data directories. This is particularly useful when:

Working with multiple feature branches simultaneously
Testing different configurations in parallel
Avoiding port conflicts between working trees
Maintaining isolated test data per branch

Architecture¶

Configuration Files¶

.branch-config.json (Git-tracked)
Located at repository root
Defines port and path configuration per branch
Checked into git for team-wide consistency
Scripts/Get-BranchConfig.ps1 (PowerShell Module)
Loads configuration based on current branch
Provides functions for scripts and automation
Used by test scripts and VS2022 integration
launchSettings.json (Git-ignored)
Generated automatically based on current branch
Used by Visual Studio 2022
Not checked into git (branch-specific)

Quick Setup¶

Automatic Setup (Recommended)¶

Install git hook for automatic configuration updates:

.\Scripts\Install-GitHooks.ps1

The post-checkout hook will automatically update launchSettings.json whenever you switch branches!

Manual Setup¶

Update configuration manually:

.\Scripts\Update-LaunchSettings.ps1 -Force

This generates: - Cesivi.Server\Properties\launchSettings.json - VS2022 server configuration - Cesivi.Proxy\Properties\launchSettings.json - VS2022 proxy configuration

Both files are git-ignored and regenerated per branch or on checkout (with hook installed).

Configuration Format¶

.branch-config.json¶

{
  "defaultBranch": "main",
  "branches": {
    "main": {
      "httpPort": 5010,
      "httpsPort": 5011,
      "dataPath": "./MockData",
      "logPath": "./MockData/Logs/Server",
      "hostname": "localhost"
    },
    "main2": {
      "httpPort": 5020,
      "httpsPort": 5021,
      "dataPath": "./MockData",
      "logPath": "./MockData/Logs/Server",
      "hostname": "localhost"
    }
  },
  "fallbackConfig": {
    "httpPort": 5000,
    "httpsPort": 5001,
    "dataPath": "./MockData",
    "logPath": "./MockData/Logs/Server",
    "hostname": "localhost"
  }
}

Adding a New Branch Configuration¶

Edit .branch-config.json
Add your branch name with unique ports:

"my-feature-branch": {
  "httpPort": 5040,
  "httpsPort": 5041,
  "dataPath": "./MockData-feature",
  "logPath": "./MockData-feature/Logs/Server",
  "hostname": "localhost"
}

Commit the configuration change to git
Regenerate launchSettings.json (see below)

Usage¶

1. Visual Studio 2022 Integration¶

Initial Setup (One-Time per Branch)¶

# Navigate to repository root
cd C:\Source\_AI\Cesivi2

# Update launchSettings.json for current branch
.\Scripts\Update-LaunchSettings.ps1 -Force

This generates Cesivi.Server\Properties\launchSettings.json with: - Branch-specific ports (HTTP/HTTPS) - Branch-specific data and log paths - Environment variables for runtime configuration

Running in VS2022¶

Open solution in Visual Studio 2022
Select "Cesivi.Server" profile
Press F5 to start debugging

VS2022 will automatically: - Use the correct ports for your branch - Store data in the configured path - Set environment variables

2. PowerShell Test Scripts¶

Branch-Aware Test Script Example¶

# Import configuration module
. ".\Scripts\Get-BranchConfig.ps1"

# Get current branch configuration
$config = Get-BranchConfig

# Build URL
$mockUrl = "http://$($config.hostname):$($config.httpPort)"

# Connect to PnP
Connect-PnPOnline -Url $mockUrl -UseWebLogin

# Run tests...

Available Functions¶

Get-BranchConfig

$config = Get-BranchConfig
# Returns: branchName, httpPort, httpsPort, dataPath, logPath, hostname

Get-BranchConfigValue

$port = Get-BranchConfigValue "httpPort"

Set-BranchEnvironment

Set-BranchEnvironment
# Sets environment variables:
#   - CESIVI_HTTP_PORT
#   - CESIVI_HTTPS_PORT
#   - CESIVI_DATA_PATH
#   - CESIVI_LOG_PATH

Update-LaunchSettings

Update-LaunchSettings -Force
# Generates/updates launchSettings.json

3. Manual Server Start (PowerShell)¶

# Start with branch-aware configuration
.\Scripts\Start-MockServer-BranchAware.ps1

4. Manual Server Start (Command Line)¶

# Set environment variables
$env:CESIVI_HTTP_PORT="5020"
$env:CESIVI_HTTPS_PORT="5021"
$env:CESIVI_DATA_PATH="C:\Source\_AI\Cesivi2\MockData"
$env:CESIVI_LOG_PATH="C:\Source\_AI\Cesivi2\MockData\Logs\Server"

# Start server
cd Cesivi.Server
dotnet run --console

Unit Tests Behavior¶

IMPORTANT: Unit tests (Cesivi.Tests) are NOT affected by branch configuration.

Unit Test Configuration¶

Port: Random port (assigned by WebApplicationFactory)
Data Path: Path.GetTempPath() (e.g., C:\Users\user1\AppData\Local\Temp\CESIVI_Tests)
Isolation: Each test run uses isolated temporary storage
Environment: "Testing" (disables file logging to prevent file locks)

This ensures: - ✅ Tests run independently of branch configuration - ✅ No port conflicts when running tests in parallel - ✅ Clean test data for each run - ✅ No interference with development mock data

R:/ RamDisk Support (Optional)¶

If you have a RamDisk mounted at R:/, you can configure unit tests to use it:

Option 1: Environment Variable

$env:CESIVI_TEST_DATA_PATH="R:\CESIVI_Tests"
dotnet test

Option 2: Modify TestFixture.cs

// Use RamDisk if available
_testMockDataPath = Directory.Exists("R:\\")
    ? "R:\\CESIVI_Tests"
    : Path.Combine(Path.GetTempPath(), "CESIVI_Tests");

Workflow Examples¶

Scenario 1: Multiple Working Trees¶

# Working tree 1 (main branch)
cd C:\Source\_AI\Cesivi-main
.\Scripts\Update-LaunchSettings.ps1 -Force
# Runs on ports 5010/5011

# Working tree 2 (main2 branch)
cd C:\Source\_AI\Cesivi-main2
.\Scripts\Update-LaunchSettings.ps1 -Force
# Runs on ports 5020/5021

# Both can run simultaneously without conflicts!

Scenario 2: Feature Branch Development¶

# Create feature branch
git checkout -b my-new-feature

# Add configuration to .branch-config.json
# {
#   "my-new-feature": {
#     "httpPort": 5050,
#     "httpsPort": 5051,
#     ...
#   }
# }

# Update VS2022 configuration
.\Scripts\Update-LaunchSettings.ps1 -Force

# Start coding and testing!

Scenario 3: Team Collaboration¶

Developer A adds configuration for their feature branch
Commits .branch-config.json to git
Developer B checks out the feature branch
Runs .\Scripts\Update-LaunchSettings.ps1 -Force
VS2022 automatically uses the correct configuration

Environment Variable Priority¶

Cesivi Server reads configuration in this order:

Environment Variables (highest priority)
CESIVI_HTTP_PORT
CESIVI_HTTPS_PORT
CESIVI_DATA_PATH
CESIVI_LOG_PATH
appsettings.json
Cesivi:HttpPort
Cesivi:HttpsPort
Cesivi:DataRootPath
Cesivi:LogPath
Default Values (lowest priority)
HTTP: 80
HTTPS: 443
Data: ./MockData
Logs: ./MockData/Logs/Server

The launchSettings.json sets environment variables, so VS2022 will use branch-specific configuration.

Troubleshooting¶

Port Already in Use¶

Error: Address already in use: localhost:5020

Solution: - Check if another instance is running - Check .branch-config.json for port conflicts - Update ports in .branch-config.json - Regenerate launchSettings.json

Wrong Configuration Loaded¶

# Check current branch
git branch --show-current

# Check loaded configuration
. .\Scripts\Get-BranchConfig.ps1
Get-BranchConfig

launchSettings.json Not Updated¶

# Force regenerate
.\Scripts\Update-LaunchSettings.ps1 -Force

Test Script Can't Connect¶

# Verify server is running
$config = Get-BranchConfig
Test-NetConnection -ComputerName localhost -Port $config.httpPort

Best Practices¶

Commit .branch-config.json to git for team consistency
Never commit launchSettings.json (add to .gitignore)
Use unique port ranges per branch (avoid conflicts)
Document custom branches in this file
Run Update-LaunchSettings.ps1 after switching branches
Set environment variables in CI/CD pipelines for branch-specific deployments

Integration with CI/CD¶

GitHub Actions Example¶

- name: Configure Branch Environment
  run: |
    . .\Scripts\Get-BranchConfig.ps1
    Set-BranchEnvironment

- name: Start Mock Server
  run: |
    cd Cesivi.Server
    dotnet run --console &

- name: Run Tests
  run: |
    $config = Get-BranchConfig
    $mockUrl = "http://localhost:$($config.httpPort)"
    # Run tests against $mockUrl

MULTI_WORKING_TREE.md - Git worktree setup guide
DEPLOYMENT_GUIDE.md - Production deployment
TESTING.md - Test infrastructure

Summary¶

✅ Branch configuration is stored in git ✅ VS2022 automatically uses correct ports ✅ PowerShell scripts are branch-aware ✅ Unit tests remain isolated (random ports, temp storage) ✅ Multiple working trees can run simultaneously ✅ No manual port configuration needed

Last Updated: 2025-10-28 Iteration: 2022 (Branch Configuration Implementation)