Azure Blob Storage Configuration - Quick Reference

🎯 Key Principle

EpanetConsoleCore NEVER uses appsettings.json for Azure configuration.

All Azure Blob Storage configuration MUST be passed via command-line arguments.

---

✅ Correct Setup

API appsettings.json

{
  "InputFileStorage": {
    "ContainerName": "dwd-input-files-mtw",
    "AzureBlob": {
      "ServiceUrl": "https://yourstorageaccount.blob.core.windows.net",
      "ContainerSasToken": "sv=2023-01-03&ss=b&srt=c&sp=rwdlac&se=2026-12-31T23:59:59Z&..."
    }
  },
  "ConnectionStrings": {
    "PSQLDB": "Host=localhost;Port=5432;Database=your_db;..."
  },
  "EpanetConsoleCore": {
    "Path": "C:\\path\\to\\EpanetConsoleCore.exe"
  }
}

API Automatically Launches Console Core

When the API starts a scenario, it automatically passes Azure config:

EpanetConsoleCore.exe "Host=localhost;..." 1 \
  --azure-url "https://account.blob.core.windows.net" \
  --azure-sas "sv=2023..." \
  --container "dwd-input-files-mtw"

You don't need to do anything manually - the API handles this!

---

❌ What Happens If Config Is Missing?

If you try to run a scenario that uses Azure Blob Storage without passing the required command-line arguments, EpanetConsoleCore will fail immediately with this error:

❌ AZURE BLOB STORAGE CONFIGURATION MISSING

This scenario uses Azure Blob Storage (StorageProvider=AzureBlob),
but required command-line arguments are missing:

  • --azure-url
  • --azure-sas
  • --container

EpanetConsoleCore must be launched with Azure configuration:

  EpanetConsoleCore.exe "<connection-string>" <scenario-id> \
    --azure-url "https://account.blob.core.windows.net" \
    --azure-sas "sv=2023..." \
    --container "dwd-input-files-mtw"

💡 Note: This is a shared executable serving multiple networks.
   Configuration MUST be passed via command-line arguments, not appsettings.json.

This is intentional! It prevents silent failures where the wrong network's configuration is used.

---

🔧 Command-Line Arguments Reference

Argument	Required	Description	Example
Positional 1	✅ Yes	Database connection string	"Host=localhost;Port=5432;Database=mtw;..."
Positional 2	✅ Yes	Scenario ID	1
--azure-url	⚠️ If Azure	Azure Blob Storage service URL	"https://account.blob.core.windows.net"
--azure-sas	⚠️ If Azure	Container-scoped SAS token	"sv=2023-01-03&ss=b&srt=c&sp=rl&..."
--container	⚠️ If Azure	Container name	"dwd-input-files-mtw"
--save-inp	❌ No	Export INP file path (no simulation)	"C:\output\scenario_1.inp"

"If Azure" means: Required only if the scenario's InputFile.StorageProvider = AzureBlob

---

📋 SAS Token Permissions

API Token (Read + Write)

• Permissions: rwdlac (Read, Write, Delete, List, Add, Create)
• Use: Upload, download, delete files
• Where: API's appsettings.json

Console Core Token (Read-Only)

• Permissions: rl (Read, List)
• Use: Download files only
• Where: Passed via command-line by API

Best Practice: Use the same token (with rwdlac) for both API and Console Core for simplicity. The API will pass it to Console Core automatically.

---

🧪 Testing Checklist

1. ✅ Configure API's appsettings.json with Azure settings
2. ✅ Restart API
3. ✅ Upload a file via frontend (tests API → Azure)
4. ✅ Create scenario using uploaded file
5. ✅ Start scenario (tests API → Console Core → Azure)
6. ✅ Verify in Azure Portal that file exists
7. ✅ Check logs for successful download message

---

🚨 Common Mistakes

❌ Creating appsettings.json in EpanetConsoleCore directory

Problem: Someone creates an appsettings.json in the EpanetConsoleCore published directory thinking it will be used.

Result: File is ignored. Console Core ONLY uses command-line arguments.

Solution: Configure API's appsettings.json instead. The API will pass config to Console Core.

---

❌ Forgetting to restart API after updating config

Problem: Update API's appsettings.json but don't restart the API.

Result: API still uses old configuration.

Solution: Always restart the API after changing appsettings.json.

---

❌ Using account key instead of SAS token

Problem: Configure AccountKey instead of ContainerSasToken.

Result: Works initially, but violates security best practices. Account keys have full access to ALL containers.

Solution: Always use container-scoped SAS tokens with minimal required permissions.

---

🎯 Multi-Instance Deployment

Each network instance should have:

1. Its own API with its own appsettings.json
2. Its own Azure container (e.g., dwd-input-files-mtw, dwd-input-files-xyz)
3. Its own container-scoped SAS token

All instances can share:

1. The same EpanetConsoleCore.exe (published once)
2. The same database server (different databases)
3. The same Azure Storage Account (different containers)

Example:

• MTW: API config points to dwd-input-files-mtw with Token A
• XYZ: API config points to dwd-input-files-xyz with Token B
• Both: Use the same EpanetConsoleCore.exe published at C:\Apps\EpanetConsoleCore\

Each API passes its own Azure configuration to the shared executable via command-line arguments!

---

📚 Full Documentation

For detailed information, see: _docs/azure_blob_storage_configuration.md