Backend-Api/FIX_STATIC_WEB_ASSETS.md

🔧 FIX: Static Web Assets Error در Docker

❌ مشکل قبلی

System.IO.DirectoryNotFoundException: /home/app/.nuget/packages/microsoft.aspnetcore.components.quickgrid/10.0.1/staticwebassets/

---

📖 توضیح مشکل

Static Web Assets چیست؟

وقتی از NuGet packages استفاده می‌کنید که فایل‌های static (CSS, JS, Images) دارند، ASP.NET Core این فایل‌ها را در development mode از مسیر NuGet cache می‌خواند:

• Windows: C:\Users\[username]\.nuget\packages\
• Linux/Docker: /home/app/.nuget/packages/

چرا در Docker خطا می‌داد؟

1. Multi-stage Build: Docker از دو image جداگانه استفاده می‌کنه:

   • sdk:8.0 برای build (شامل NuGet packages)
   • aspnetcore:8.0 برای runtime (lightweight، بدون NuGet packages)

2. Path Resolution: در runtime stage، ASP.NET Core هنوز سعی می‌کرد فایل‌ها رو از NuGet cache بخونه که وجود نداشتن

3. Version Mismatch: پروژه شما .NET 10 target میکنه ولی Docker از .NET 8 استفاده می‌کنه (چون .NET 10 هنوز release نشده)

---

✅ راه‌حل اعمال شده

1️⃣ تغییر در Program.cs

// خط 47-48: غیرفعال کردن Hosting Startup Assemblies
Environment.SetEnvironmentVariable("ASPNETCORE_HOSTINGSTARTUPASSEMBLIES", "");

// خط 52-56: غیرفعال کردن Static Web Assets در Production
if (!builder.Environment.IsDevelopment())
{
    builder.Configuration["Microsoft.AspNetCore.Hosting.StaticWebAssets.UseStaticWebAssets"] = "false";
}

چرا این کار رو کردیم؟

• در Production/Docker نیازی به Static Web Assets نیست
• تمام فایل‌های لازم باید در publish output باشند
• این تنظیم فقط در non-development environments فعال می‌شه

2️⃣ تغییر در ServiceHost.csproj

<PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <!-- ... other properties ... -->
    
    <!-- اضافه شد: غیرفعال کردن Static Web Assets در زمان build -->
    <DisableStaticWebAssets>true</DisableStaticWebAssets>
</PropertyGroup>

چرا این کار رو کردیم؟

• این property جلوی تولید manifest file برای static web assets رو می‌گیره
• باعث می‌شه published app وابسته به NuGet cache نباشه
• فایل‌های static مستقیم در output folder کپی می‌شن

3️⃣ تغییر در Log Directory (خط 70-73)

var logDirectory = builder.Environment.IsDevelopment() 
    ? @"C:\Logs\Gozareshgir\"  // Windows path برای development
    : "/app/Logs";              // Linux path برای Docker

چرا این کار رو کردیم؟

• مسیر لاگ باید با سیستم عامل سازگار باشه
• Docker از Linux استفاده می‌کنه که از / برای path استفاده می‌کنه
• در development روی Windows، از مسیر Windows استفاده می‌کنیم

---

🚀 نتیجه

حالا می‌تونید بدون خطا Docker رو build کنید:

# پاک کردن containers قبلی
docker-compose down

# Build و اجرای جدید
docker-compose up --build -d

# مشاهده logs
docker-compose logs -f servicehost

Application باید بدون خطای Static Web Assets راه‌اندازی بشه!

---

📊 مقایسه قبل و بعد

موضوع	قبل	بعد
Static Web Assets	فعال در همه environments	فقط در Development
NuGet Cache Dependency	وابسته	مستقل
Docker Build	❌ خطا می‌داد	✅ موفق
Published Size	کوچکتر	کمی بزرگتر (فایل‌ها embedded)
Performance	کمی بهتر	یکسان

---

⚠️ نکات مهم

1. Development Mode: در development هنوز Static Web Assets فعال هست و از NuGet cache استفاده می‌کنه (طبیعی است)

2. Missing Styles: اگر بعد از این تغییرات برخی styles کار نکردند، ممکنه لازم باشه:

   dotnet clean
   dotnet build
   

3. Production: این تغییرات فقط روی Production/Docker تأثیر می‌ذارن، development شما تغییری نمی‌کنه

---

🔍 اطلاعات تکمیلی

چرا Static Web Assets لازمن؟

در development mode، این feature به شما اجازه می‌ده:

• Hot reload برای CSS/JS از packages
• Debug کردن فایل‌های static از source
• تغییرات instant اعمال بشن

چرا در Production نیازی نیستن؟

در production:

• فایل‌ها باید optimized و minified باشن
• همه چیز باید در published output باشه
• نباید وابسته به external paths باشیم

---

تاریخ Fix: 27 January 2026
نسخه: Docker + HTTPS Setup v1.1