المشكلة: «شغّل المشروع» بقت 7 خطوات
الـ Capstone فيه API و ingestion worker و Angular app و Postgres بـ pgvector و Redis و mock LLM. عشان مطور جديد يشغله: يثبت Postgres، يعمل extension، يشغل Redis، يظبط 6 connection strings، يشغل 4 processes بالترتيب، ويدور على الـ logs في 4 terminals. Aspire بيحوّل ده لملف C# واحد (AppHost) وأمر واحد، وبيضيف dashboard فيه traces و logs و metrics لكل الخدمات من أول يوم.
تغيير الاسم: من نسخة 13 (نوفمبر 2025) المشروع بقى اسمه Aspire بس (من غير .NET) لأنه بقى بيدعم Python و JavaScript كـ first-class، وفيه aspire CLI (aspire new، aspire run، aspire update، aspire publish/deploy) و AppHost ممكن بـ TypeScript كمان. المفاهيم ثابتة، لكن أسماء الـ APIs اتغيرت بين النسخ (مثلًا AddPythonScript ← AddPythonApp في 13.1) — راجع aspire.dev لنسختك.
AppHost للـ Capstone
aspire new # pick a template, or add an AppHost to an existing solution:
aspire init
aspire run # starts everything + opens the dashboardvar builder = DistributedApplication.CreateBuilder(args);
var pgPassword = builder.AddParameter("pg-password", secret: true); // from user-secrets / env, never hard-coded
var postgres = builder.AddPostgres("postgres", password: pgPassword)
.WithImage("pgvector/pgvector", "pg17") // image with the pgvector extension
.WithDataVolume() // keep data between runs
.WithPgAdmin();
var db = postgres.AddDatabase("knowledge");
var redis = builder.AddRedis("redis").WithDataVolume();
var mockLlm = builder.AddProject<Projects.MockLlm>("mock-llm"); // swap for a real endpoint via a parameter
var api = builder.AddProject<Projects.Knowledge_Api>("api")
.WithReference(db).WaitFor(db) // ConnectionStrings__knowledge injected
.WithReference(redis).WaitFor(redis)
.WithReference(mockLlm) // service discovery: http://mock-llm
.WithExternalHttpEndpoints();
builder.AddProject<Projects.Knowledge_Ingestion>("ingestion")
.WithReference(db).WaitFor(db)
.WithReference(redis)
.WithReference(mockLlm);
builder.AddNpmApp("web", "../web", "start") // Angular dev server (JS integration package)
.WithReference(api)
.WithHttpEndpoint(env: "PORT")
.WithExternalHttpEndpoints();
builder.Build().Run();- Resources: كل حاجة في النظام (project، container، executable، parameter) resource ليها اسم.
- WithReference: بيحقن الـ connection string أو عنوان الخدمة في الـ resource التاني كـ environment variables (
ConnectionStrings__knowledge،services__mock-llm__http__0). - WaitFor: الـ API ما يبدأش قبل ما الـ DB تبقى healthy — بيحل مشكلة «startup لا يعني readiness» من Docker Compose.
- Parameters: للأسرار والإعدادات اللي بتختلف بين البيئات، بتتقري من user-secrets أو env.
ServiceDefaults: الـ cross-cutting مرة واحدة
var builder = WebApplication.CreateBuilder(args);
builder.AddServiceDefaults(); // OpenTelemetry (traces/metrics/logs to OTLP), health checks, service discovery, HttpClient resilience
builder.AddNpgsqlDbContext<AppDb>("knowledge", configureDbContextOptions: o => o.UseNpgsql(x => x.UseVector()));
builder.AddRedisDistributedCache("redis");
builder.Services.AddHttpClient<MockLlmClient>(c => c.BaseAddress = new("https+http://mock-llm")); // resolved by service discovery
var app = builder.Build();
app.MapDefaultEndpoints(); // /health and /alive in developmentمشروع ServiceDefaults هو كود بتاعك (مش black box): بيضيف OTel instrumentation لـ ASP.NET Core و HttpClient و runtime، الـ health checks، والـ standard resilience handler لكل HttpClient. عدّله حسب احتياجك. والـ integrations (Aspire.Npgsql.EntityFrameworkCore.PostgreSQL، Aspire.StackExchange.Redis…) بتضيف الـ client + health check + telemetry لكل dependency بسطر.
الـ dashboard: observability من أول يوم
الـ dashboard بيستقبل OTLP من كل الخدمات. طلب chat واحد من Angular هتشوفه trace واحد: الـ API ← Redis (budget) ← Postgres (vector search) ← mock-llm ← الرد — بالـ durations لكل span. ده نفس الـ trace اللي هتشوفه في الإنتاج في Application Insights أو Grafana، فالـ instrumentation اللي كتبته وانت بتطور هو اللي هيشتغل في الإنتاج.
| Tab | تستخدمه في |
|---|---|
| Resources | حالة كل خدمة/container، الـ endpoints، الـ env vars المحقونة (debug للـ config) |
| Console logs | stdout لكل resource في مكان واحد |
| Structured logs | فلترة بالـ trace id أو الـ level أو أي property |
| Traces | «ليه الطلب ده بطيء؟» — span بطيء أو N+1 queries ظاهرة |
| Metrics | request rate، durations، runtime (GC، thread pool) |
الـ dashboard كمان ممكن يشتغل standalone (container) مع أي تطبيق بيبعت OTLP، حتى من غير AppHost.
Integration tests بالـ AppHost
public sealed class ChatFlowTests
{
[Fact]
public async Task Ask_returns_cited_answer_end_to_end()
{
var appHost = await DistributedApplicationTestingBuilder.CreateAsync<Projects.Knowledge_AppHost>();
await using var app = await appHost.BuildAsync();
await app.StartAsync();
var http = app.CreateHttpClient("api"); // real API, real Postgres container, mock LLM
await app.ResourceNotifications.WaitForResourceHealthyAsync("api");
var res = await http.PostAsJsonAsync("/api/questions", new { question = "What is the refund window?" });
res.EnsureSuccessStatusCode();
var body = await res.Content.ReadFromJsonAsync<AnswerDto>();
Assert.NotEmpty(body!.Citations);
}
}تقيلة نسبيًا (containers حقيقية)، فخليها لعدد قليل من الـ flows الحرجة — نفس منطق الـ test pyramid. الاختبارات الأسرع لكل خدمة لوحدها بـ WebApplicationFactory و Testcontainers.
من التطوير للـ deployment
نفس الـ AppHost بيوصف topology النظام، فـ Aspire يقدر يولّد منه artifacts للـ deployment: aspire publish بيطلّع manifests/IaC حسب الـ target (Docker Compose، Kubernetes، أو Azure: Bicep لـ Azure Container Apps)، و aspire deploy بيعمل deployment مباشر للـ targets المدعومة. القرارات المهمة:
- Azure Container Apps الأقرب لنموذج Aspire (كل project = container app، Postgres/Redis ← خدمات Azure مُدارة عبر integrations بتعمل provisioning).
- Kubernetes ممكن عبر الـ publisher أو أدوات زي Aspir8 — بس غالبًا فريق الـ platform عنده Helm/GitOps، فـ Aspire بيبقى للـ inner loop بس.
- Containers في الـ dev ≠ الإنتاج: Postgres container محليًا يقابله Azure Database for PostgreSQL في الإنتاج — نفس الـ connection string name، provider مختلف. اعرف ده عشان ما تتفاجئش بفروق الإصدارات والـ extensions (pgvector لازم يتفعل على الخدمة المدارة).
- الأسرار: الـ parameters بتتحول لـ secrets في الـ target (Key Vault/Container Apps secrets)، مش env vars plain.
Aspire مقابل Docker Compose
| Docker Compose | Aspire | |
|---|---|---|
| لغة الوصف | YAML | C# (أو TypeScript) — refactoring، types، شروط |
| تشغيل مشاريع .NET | لازم تبني images | بيشغلها كـ processes مباشرة (debugger، hot reload) |
| Config wiring | يدوي (env vars) | WithReference بيحقنها |
| Observability | تجيب stack بنفسك | dashboard مدمج + ServiceDefaults |
| غير .NET | أي حاجة | containers + Python/JS integrations (أوسع من الأول بكتير من 13) |
| الفريق | معروف للكل | محتاج تعلم، وبيتطور بسرعة (breaking changes بين majors) |
التوصية: لنظام معظمه .NET وفريق .NET، Aspire بيوفر وقت كبير في الـ inner loop والـ onboarding. لو النظام متعدد اللغات بشكل كبير أو فريق الـ ops مستقر على Compose/K8s، Compose لسه اختيار ممتاز. الـ Capstone فيه الاتنين: docker-compose.yml كـ baseline محايد، و AppHost كخيار للتطوير.
إزاي الـ configuration بتوصل للخدمة؟ trace كامل
لما تكتب .WithReference(db)، Aspire بيعمل التالي وقت aspire run: (1) يشغّل الـ Postgres container ويستنى الـ health check، (2) يبني connection string من الـ host/port/password الفعليين، (3) يحقنها في process الـ API كـ environment variable ConnectionStrings__knowledge، (4) الـ API بيقراها بالـ configuration system العادي في .NET (builder.Configuration.GetConnectionString("knowledge")) — مفيش سحر في الكود، هي نفس الـ configuration providers من Developer Workflow.
| في الـ AppHost | بيوصل للخدمة كـ | بتقراه بـ |
|---|---|---|
WithReference(db) | ConnectionStrings__knowledge | GetConnectionString("knowledge") أو الـ integration (AddNpgsqlDbContext("knowledge")) |
WithReference(api) (خدمة HTTP) | services__api__https__0 | service discovery: https+http://api في HttpClient |
WithEnvironment("Llm__Model", "small") | Llm__Model | IOptions<LlmOptions> |
AddParameter("key", secret: true) | قيمة من user-secrets/env | نفس الـ configuration |
الفايدة إن نفس الكود بيشتغل من غير Aspire خالص (في Kubernetes مثلًا) طالما الـ environment variables بنفس الأسماء موجودة — Aspire مش dependency لازم في الإنتاج. وده سؤال مهم في الـ adoption: «لو قررنا نشيل Aspire بعد سنة، هنغير إيه؟» الإجابة: الـ AppHost بس، مش الخدمات.
Aspire والـ AI workloads
- Model endpoints كـ resources: integrations لـ Azure OpenAI/AI Foundry بتعمل provisioning في Azure وبتحقن الـ endpoint، أو connection string لـ OpenAI-compatible endpoint (Ollama/vLLM محلي) — والكود بيستخدم
IChatClientفي الحالتين. - Python services: worker الـ embeddings أو الـ evals بـ Python يتضاف للـ AppHost (Python integration)، ويطلع في نفس الـ dashboard والـ traces مع خدمات .NET.
- Telemetry للـ LLM calls: الـ OTel GenAI attributes (model، tokens) بتظهر في الـ traces في الـ dashboard وانت بتطور، فتشوف تكلفة كل request قبل الإنتاج.
- Eval runs: AppHost profile منفصل بيشغّل الـ stack + الـ eval harness على الـ golden set — نفس الـ topology اللي في CI.
أخطاء شائعة
- اعتبار Aspire «platform إنتاج» بيلغي الحاجة لفهم Docker/K8s/Azure — هو أداة وصف وتشغيل؛ الإنتاج لسه محتاج قرارات تشغيل.
- Hard-coded passwords في الـ AppHost بدل parameters سرية.
- Upgrade لنسخة major جديدة من غير
aspire updateوقراءة الـ breaking changes. - الاعتماد على containers dev بإصدارات مختلفة عن الخدمات المُدارة في الإنتاج من غير اختبار.
- Integration tests بالـ AppHost لكل حاجة ← suite بطيئة جدًا.
اختبر فهمك
الـ API بيفشل عند البداية لأن Postgres لسه بيعمل initialize. الحل في Aspire؟
إيه اللي بيعمله WithReference(db)؟
تمرين محلول
ضيف Ollama محلي كبديل للـ mock LLM بـ parameter يختار بينهم
الحل: في الـ AppHost: var useOllama = builder.Configuration["UseOllama"] == "true"; ثم IResourceBuilder<IResourceWithServiceDiscovery> llm = useOllama ? builder.AddContainer("ollama", "ollama/ollama").WithHttpEndpoint(targetPort: 11434, name: "http").WithVolume("ollama-models", "/root/.ollama") … : builder.AddProject<Projects.MockLlm>("mock-llm"); (أو استخدم integration مجتمعية لـ Ollama لو متاحة لنسختك)، والـ API بياخد WithReference(llm). الكود في الـ API ما بيتغيرش لأنه بيكلم IChatClient بعنوان من الـ service discovery. وشغّل الـ eval suite على الاتنين وقارن الجودة والـ latency — ده بالظبط قسم «موديل حقيقي» في Capstone Build-Along.
أسئلة إنترفيو
(Mid) Aspire بيحل إيه؟
(Senior) تعتمد Aspire لفريق 20 مهندس؟
المراجع والقراءة الإضافية
الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)
التوثيق الرسمي — Official documentation
مصادر تعليمية ومتقدمة — Third-party & advanced reading
خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.