Input File Naming Strategy

Date: October 21, 2025 Status: ✅ Implemented

🎯 Final Decisions

1. Blob Naming: User Name + Timestamp

{sanitized-user-name}-{yyyyMMdd-HHmmss}.inp

2. Container Naming: Instance-Level Configuration

Configured in appsettings.json (not in database)

---

📊 How It Works

User Uploads a File:

User Input:

• File: network.inp (original filename - ignored)
• Name: "My Network Model" (display name)
• Description: "Updated hydraulic model" (optional)

System Generates:

• Name → Stored as-is: "My Network Model"
• BlobName → Generated: "My Network Model-20251021-143022.inp"
• ContainerName → From config: "hydrotrek-inputfiles"

Storage Location:

LocalFileSystem: C:\HydroTrek\InputFiles\hydrotrek-inputfiles\My Network Model-20251021-143022.inp
Azure Blob:      https://account.blob.core.windows.net/hydrotrek-inputfiles/My Network Model-20251021-143022.inp

Database Record:

{
  "id": 1,
  "name": "My Network Model",
  "description": "Updated hydraulic model",
  "blobName": "My Network Model-20251021-143022.inp",
  "storageProvider": 2,
  "fileSizeBytes": 245678,
  "uploadedAt": "2025-10-21T14:30:22Z"
}

---

🔄 Versioning Example

Scenario: User Uploads Multiple Versions

Upload 1 (Oct 21, 2:30 PM):

Name: "Main Network"
BlobName: "Main Network-20251021-143022.inp"
ID: 1

Upload 2 (Oct 22, 9:15 AM) - Same display name:

Name: "Main Network"
BlobName: "Main Network-20251022-091540.inp"
ID: 2

Upload 3 (Oct 23, 3:45 PM) - Same display name:

Name: "Main Network"
BlobName: "Main Network-20251023-154500.inp"
ID: 3

Database View:

ID	Name	BlobName	Uploaded	Active
1	Main Network	Main Network-20251021-143022.inp	2025-10-21 14:30	❌
2	Main Network	Main Network-20251022-091540.inp	2025-10-22 09:15	❌
3	Main Network	Main Network-20251023-154500.inp	2025-10-23 15:45	✅

Storage View:

hydrotrek-inputfiles/
  ├── Main Network-20251021-143022.inp  (215 KB)
  ├── Main Network-20251022-091540.inp  (218 KB)
  └── Main Network-20251023-154500.inp  (220 KB)

User Workflow:

1. User uploads v1 → DB ID=1, active
2. User uploads v2 with same name → DB ID=2, active
3. User deactivates ID=1 (soft delete) → Only v2 visible in UI
4. Scenarios can reference either version by ID
5. Old versions remain in storage for audit/recovery

---

🔑 Key Design Principles

Separation of Concerns:

1. Name (Database) = User-facing display name

   • What users see in the UI
   • Can be duplicated (multiple versions)
   • Searchable, sortable

2. BlobName (Database) = Unique storage identifier

   • How file is stored on disk/blob
   • Guaranteed unique (database constraint)
   • Never changes after creation

3. ContainerName (Configuration) = Instance-specific

   • Where files are stored (which container/directory)
   • Configured per deployment
   • Not stored in database

Why This Works:

• ✅ Users think in terms of names ("My Network")
• ✅ System manages unique identifiers automatically
• ✅ Timestamps provide natural versioning
• ✅ No collision handling needed
• ✅ No user input for container selection

---

📋 Implementation Details

Code Location:

dwd-api-aspnet/DwdApiAspNet/Controllers/InputFileController.cs - Line ~129-133

// Generate unique blob name: {UserName}-{Timestamp}.inp
// This ensures uniqueness while keeping human-readable names
var timestamp = DateTime.UtcNow.ToString("yyyyMMdd-HHmmss");
var sanitizedName = SanitizeFileName(name);
var blobName = $"{sanitizedName}-{timestamp}.inp";

Sanitization:

private string SanitizeFileName(string fileName)
{
  if (string.IsNullOrWhiteSpace(fileName))
  {
    return "file";
  }

  var invalidChars = Path.GetInvalidFileNameChars();
  var sanitized = new string(fileName.Select(c =>
    invalidChars.Contains(c) ? '_' : c
  ).ToArray());

  return sanitized;
}

Examples:

• "My Network!" → "My Network_"
• "Test/Model" → "Test_Model"
• "Network:v2" → "Network_v2"

---

🎯 Benefits of This Approach

For Users:

• ✅ Simple upload process (just name + description)
• ✅ No need to think about versioning
• ✅ No need to know about containers or blob names
• ✅ Natural version management (upload again = new version)

For Admins:

• ✅ Easy to identify files in storage browser
• ✅ Chronological ordering in storage
• ✅ Audit trail built-in (timestamp)
• ✅ No collision resolution needed

For Developers:

• ✅ No complex versioning logic
• ✅ No conflict resolution needed
• ✅ Guaranteed uniqueness (database constraint + timestamp)
• ✅ Simple implementation

---

🔍 Alternatives Considered

❌ Option 1: Original Filename Only

network.inp

• Problem: Not unique, multiple uploads would fail

❌ Option 2: User Name Only

My Network Model.inp

• Problem: Still not unique if user uploads same name twice

⚠️ Option 3: User Name + Short GUID

My Network Model-a3f8c912.inp

• Pro: Shorter than timestamp
• Con: Less meaningful for humans
• Why not chosen: Timestamp provides audit trail

❌ Option 4: Pure GUID

e7f3c2a1-4b5d-4e8f-9c1a-2d3e4f5a6b7c.inp

• Pro: Guaranteed unique
• Con: Not human-readable, hard to manage

✅ Option 5: User Name + Timestamp (CHOSEN)

My Network Model-20251021-143022.inp

• Pro: Unique + human-readable + audit trail
• Pro: Natural versioning
• Pro: Sortable by time
• Why chosen: Best balance of uniqueness and readability

---

🧪 Testing Scenarios

Test 1: Upload Same Name Twice

Upload 1: Name="Test" → BlobName="Test-20251021-100000.inp"
Upload 2: Name="Test" → BlobName="Test-20251021-100030.inp"
Result: ✅ Both files saved successfully

Test 2: Special Characters in Name

Upload: Name="Network/Test:v2!" → BlobName="Network_Test_v2_-20251021-100000.inp"
Result: ✅ Sanitized automatically

Test 3: Rapid Uploads (Same Second)

Upload 1: Name="Test" → BlobName="Test-20251021-143022.inp"
Upload 2: Name="Test" (1 second later) → BlobName="Test-20251021-143023.inp"
Result: ✅ Different timestamps, both unique

Test 4: Empty Name

Upload: Name="" (user doesn't provide name)
Fallback: Uses original filename: "network.inp"
BlobName: "network-20251021-143022.inp"
Result: ✅ Still unique with timestamp

---

📚 Related Documentation

• _docs/input_file_blob_storage_design.md - Complete blob storage design
• _docs/remove_container_name_migration.md - Container name removal migration
• _docs/blob_storage_implementation_plan.md - Implementation phases

---

✅ Summary

What users see:

• Upload form with Name + Description fields
• Table showing user-friendly names
• No technical details about storage

What system manages:

• Unique blob names with timestamps
• Container configuration per instance
• Storage provider abstraction
• Automatic versioning

Result:

• Simple UX + Robust backend
• No naming conflicts
• Natural version management
• Easy to understand and maintain