هنطلع من الدرس بإيه؟
بعد الدرس ده هتعرف تجهّز جهازك لمشروع .NET + Angular + Python، تختار IDE مناسب، تشغّل أدوات التطوير، تقرأ stack trace، تستخدم breakpoint و logging، وتدور في documentation بدل النسخ الأعمى من AI.
- تتحقق من الأدوات بأوامر version.
- تختبر API من Postman وتفحص request من DevTools.
- تحوّل bug غامض لخطوات إعادة إنتاج صغيرة.
- تكتب سؤال تقني فيه expected و actual result.
المتطلبات: جهاز عليه Terminal واتصال إنترنت وقت التثبيت. مش مطلوب خبرة سابقة بالأدوات.
ابدأ بمثال شغال
افتح Terminal في فولدر فاضي ونفّذ الأوامر دي. المثال بيختبر إن .NET SDK متثبت ويقدر ينشئ ويشغّل تطبيق.
dotnet --info
dotnet new console -n HelloWorkflow
cd HelloWorkflow
dotnet runالمتوقع يظهر Hello, World!. لو dotnet مش معروف، راجع تثبيت SDK و PATH، وبعد التثبيت افتح Terminal جديد. حالة التحقق: لم يُنفَّذ داخل بيئة بناء الموسوعة؛ المثال للتشغيل على جهاز المتعلم.
اختار بيئة التطوير الصح
فيه منتجين مختلفين: Microsoft Visual Studio (الأيقونة البنفسجي) IDE متكامل على Windows، مناسب لحلول .NET الكبيرة و debugging وإدارة المشاريع والاختبارات من واجهة واحدة. Visual Studio Code (الأيقونة الزرقاء) محرر خفيف متعدد الأنظمة؛ بتضيف Extensions حسب اللغة، ومناسب لـ Angular و Python و Docker وشغل الويب. تقدر تعمل .NET بـ VS Code برضه، لكن هتعتمد أكتر على CLI والإضافات.
لو شغلك الأساسي ASP.NET Core على Windows وعايز تجربة متكاملة، ابدأ بـ Microsoft Visual Studio. لو بتتنقل بين C# و TypeScript و Python أو على Linux/macOS، VS Code مرن. مش لازم تثبت الاتنين لمجرد تشابه الاسم.
| الأداة | دورها | التحقق |
|---|---|---|
| .NET SDK | يبني ويشغّل مشاريع .NET | dotnet --info |
| Git | Version control | git --version |
| Node.js و npm | تشغيل tooling الخاص بـ Angular | node --version و npm --version |
| Python | سكربتات و ML tooling | python --version |
| Docker Desktop | تشغيل containers محليًا | docker version |
نزّل الأدوات من مواقعها الرسمية. الإصدارات بتتغير؛ راجع متطلبات المشروع قبل اختيار version، واستخدم global.json أو version manager لما الفريق يحتاج توحيد البيئة.
كل أداة بتحل مشكلة إيه؟
Postman: بيبعت HTTP requests من غير frontend. جرّب GET و POST وراقب status code و headers و JSON body. كده بتفصل مشكلة API عن مشكلة الواجهة.
Browser DevTools: افتح Network وشوف URL و method و payload و response ووقت التنفيذ. Console للأخطاء اللي بتحصل في JavaScript. قارن response بالبيانات اللي الواجهة رسمتها.
Docker Desktop: بيشغّل containers محليًا. افهم image مقابل container، وبعدها شغّل SQL Server أو Redis في مشروع تدريبي. Docker مش بديل عن SDK؛ هو وسيلة لتغليف وتشغيل خدمات معزولة.
Python venv: بيعمل بيئة مستقلة لكل مشروع. Node.js: بيشغّل npm وأدوات بناء Angular؛ مش هو Angular نفسه.
python -m venv .venv
# Windows PowerShell:
.venv\Scripts\Activate.ps1
# macOS/Linux:
source .venv/bin/activate
python -m pip install --upgrade pip
# Inside a new Node project folder:
npm init -yلو PowerShell منع تفعيل venv بسبب Execution Policy، ما تغيّرش إعدادات الجهاز عشوائيًا؛ استخدم طريقة التفعيل الموثقة أو شغّل Python من .venv/Scripts/python.exe مباشرة. احفظ package-lock.json في Git لتثبيت npm قابل للتكرار.
Debugging: دور على السبب مش العرض
تخيّل endpoint بيرجع 500. بدل تغيير كذا سطر بالحظ، ثبّت المشكلة: ابعت نفس request، سجّل input آمن، وحدد هل الخطأ قبل دخول action ولا جواه ولا وقت الوصول للداتابيز.
Stack trace سلسلة الاستدعاءات اللي وصلت للخطأ. ابدأ بأول frame من كودك. Breakpoint نقطة توقف تشوف عندها قيم المتغيرات. Logging سجل أحداث مفيد في بيئة مش فاتح فيها debugger.
- أعد إنتاج الخطأ بأقل request ممكن.
- اقرأ exception type و message والـ inner exception.
- حط breakpoint عند boundary: endpoint ثم service ثم repository.
- راقب القيم وشروط if ونتيجة query.
- قلّص المشكلة: عطّل جزء واحد أو استبدل dependency بـ fake.
- اكتب regression test يمنع رجوع العطل.
using Microsoft.Extensions.Logging;
public sealed class OrderService(ILogger<OrderService> logger)
{
public void Process(int orderId)
{
logger.LogInformation("Processing order {OrderId}", orderId);
try
{
// Business operation goes here.
}
catch (InvalidOperationException ex)
{
logger.LogError(ex, "Order {OrderId} could not be processed", orderId);
throw;
}
}
}استخدم structured logging placeholders بدل string interpolation. ما تسجلش password أو access token أو بيانات شخصية كاملة. ولما تعيد رمي exception استخدم throw; مش throw ex; عشان تحافظ على stack trace الأصلي.
إزاي تقرأ Documentation وتحل مشكلة لوحدك؟
حدد السؤال: عايز تعمل إيه؟ على أي framework/runtime version؟ وإيه اللي حصل بدل المتوقع؟ دور في documentation الرسمية على المفهوم أو API، اختار صفحة version المناسبة، وجرب مثال صغير. لو فيه breaking changes اقرأ migration guide.
رتّب المصادر: documentation الرسمية، release notes، GitHub issue أو discussion من repository الأصلي، وبعدها المقالات. إجابة Stack Overflow ممكن تساعدك، لكنها مش ضمان إنها مناسبة لإصدارك.
اعتبر AI مساعد مش مصدر حقيقة. اطلب منه يشرح assumptions ويحدد الملفات المتأثرة ويكتب tests. راجع الـ API في docs، شغّل build و tests، وافحص security implications. ما تبعتش secrets أو customer data أو source code خاص لخدمة مش مصرح بيها.
Goal:
Environment and exact versions:
Minimal steps to reproduce:
Expected result:
Actual result:
Full error / stack trace (secrets removed):
What I already tried:
Smallest relevant code:لو مش قادر تشرح ليه الكود المقترح بيشتغل، لسه ما خلصتش. اطلب شرح flow و failure cases، وبعدها اختبر بنفسك.
Git workflow يومي: من branch لـ PR مدموج
الـ Git مش «save button». هو سجل قرارات الفريق. أي Junior بيتقاس من أول أسبوع بشكل الـ commits والـ PRs بتاعته قبل جودة الكود نفسه.
git switch main && git pull --ff-only # start from the latest main, never from a stale branch
git switch -c feature/123-invoice-pdf # one branch = one ticket = one reviewable change
# ... edit, then look at what you are about to commit
git status && git diff
git add -p # stage hunk by hunk: no debug prints, no unrelated files
git commit -m "feat(invoices): render invoice as PDF via QuestPDF"
git fetch origin && git rebase origin/main # keep the branch current; resolve conflicts locally
dotnet build && dotnet test # run what CI runs BEFORE pushing
git push -u origin feature/123-invoice-pdf # then open the PR with a description + screenshots| أمر | إمتى | خطر |
|---|---|---|
git rebase | تحديث branch خاص بيك على main | ما تعملوش على branch حد تاني شغال عليه (بيعيد كتابة التاريخ) |
git merge | دمج branches مشتركة | merge commits كتير بتصعّب القراءة |
git stash | تغيير سياق مؤقت | stash منسي = شغل ضايع؛ سمّيه git stash push -m |
git reset --hard | تخلص من تغييرات محلية | مفيش رجوع للـ uncommitted؛ git reflog بينقذ الـ committed بس |
git push --force-with-lease | بعد rebase لـ branch بتاعك | أأمن من --force: بيرفض لو حد ضاف commits |
git bisect | «كان شغال من أسبوع» | binary search على الـ commits لحد ما تلاقي اللي كسر |
Commit message كويس بيقول «ليه» مش «إيه» بس. Conventional Commits (feat:, fix:, refactor:) بتسهّل الـ changelog والـ semantic versioning. PR كويس: أقل من ~400 سطر، وصف المشكلة، إزاي اختبرت، screenshots للـ UI، وأي migration أو config جديد.
الـ dotnet CLI والـ solution structure
الـ IDE بيخبي حاجات، والـ CI ما عندوش IDE. لو مش قادر تبني وتختبر وتشغّل من الـ terminal، مش هتعرف تصلح pipeline مكسور.
dotnet new sln -n Shop
dotnet new webapi -n Shop.Api -o src/Shop.Api
dotnet new classlib -n Shop.Domain -o src/Shop.Domain
dotnet new xunit -n Shop.Tests -o tests/Shop.Tests
dotnet sln add src/**/*.csproj tests/**/*.csproj
dotnet add src/Shop.Api reference src/Shop.Domain
dotnet add tests/Shop.Tests reference src/Shop.Api
dotnet new gitignore && dotnet new editorconfig # consistent ignores and code style for the whole team
dotnet build -warnaserror # warnings are bugs-in-waiting; fail early
dotnet test --collect:"XPlat Code Coverage"
dotnet watch --project src/Shop.Api # hot reload during development
dotnet list package --vulnerable --include-transitive # known CVEs in your dependency tree
dotnet format --verify-no-changes # the same check CI runsDirectory.Build.props في جذر الـ repo بيوحّد الإعدادات لكل المشاريع (Nullable، TreatWarningsAsErrors، LangVersion)، وDirectory.Packages.props (Central Package Management) بيخلي نسخ الـ NuGet في مكان واحد بدل ما كل project يقرر لوحده. الربط: نفس الأوامر دي هي اللي هتلاقيها حرفيًا في CI/CD.
<Project>
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
<AnalysisLevel>latest-recommended</AnalysisLevel>
</PropertyGroup>
</Project>Debugging متقدم: breakpoints ذكية، logs، و diagnostics tools
| الأداة | بتحل إيه | مثال |
|---|---|---|
| Conditional breakpoint | bug بيحصل في iteration رقم 9,000 بس | Condition: order.Id == 4521 |
| Tracepoint / logpoint | تطبع قيمة من غير ما توقف البرنامج (مهم مع timing bugs) | Action: {order.Total} continue execution |
| Exception settings | exception بيتبلع في catch عام | Break when thrown لـ InvalidOperationException |
| Immediate / Watch | تجرب expression في نفس الـ state | orders.Where(o => o.Total < 0).Count() |
| Structured logs | bug في production مش قادر تعمله reproduce | Serilog + correlation id في Observability |
| dotnet-counters | CPU/GC/thread pool live | dotnet-counters monitor -n Shop.Api |
| dotnet-trace / dotnet-dump | بطء أو memory leak | trace بيتفتح في PerfView/VS، dump بيتحلل بـ dotnet-dump analyze |
منهج علمي مش تخمين: (1) اعمل reproduce بأصغر input، (2) اكتب فرضية واحدة، (3) جرب تجربة تنفيها أو تثبتها، (4) لما تلاقي السبب اكتب test بيفشل قبل الإصلاح وينجح بعده. الخطوة 4 هي اللي بتفرّق مهندس عن حد «صلّح الـ bug»: الـ test بيمنع رجوعه.
تغيير 3 حاجات مرة واحدة ومش عارف أنهي صلّح؛ الثقة في الـ log message من غير ما تشوف الـ stack trace كامل؛ debugging في Release build والقيم «optimized away»؛ تجاهل الـ inner exception (السبب الحقيقي غالبًا هناك، خصوصًا مع EF Core: DbUpdateException ← SqlException).
AI assistants في الشغل اليومي: استخدام مسؤول
أدوات زي Copilot و Claude Code و Cursor بقت جزء من الـ toolchain. القيمة الحقيقية: scaffolding، شرح كود غريب، كتابة tests، و refactor متكرر. القواعد: انت المسؤول عن كل سطر بيتعمله merge؛ اقرأ الـ diff كأنه PR من زميل جديد؛ ما تحطش secrets أو بيانات عملاء في prompts لأدوات غير معتمدة من الشركة؛ وخلي الـ tests والـ CI هي الحكم مش ثقة الأداة. الـ Junior اللي بيستخدمها صح بيتعلم أسرع؛ اللي بيعمل copy-paste من غير فهم بيتكشف في أول code review أو أول incident.
Knowledge check
عملت rebase لـ branch بتاعك على main وعايز تعمل push. الأمر الأأمن؟
تطبيق شغال من أسبوع وبقى بيفشل في test معين، وفيه 60 commit من وقتها. أسرع طريقة منهجية؟
Configuration محليًا: launchSettings و user-secrets و environments
المشكلة: connection string فيه password اتعمله commit مرة واحدة = اتسرّب للأبد (حتى لو مسحته، التاريخ فيه). الحل مش «خلي بالك»، الحل workflow ما يسمحش بالغلط.
| المصدر | بيتقري إمتى | يتحط فيه إيه |
|---|---|---|
appsettings.json | دايمًا | defaults غير سرية (log levels، feature flags الافتراضية) |
appsettings.Development.json | لما ASPNETCORE_ENVIRONMENT=Development | إعدادات التطوير غير السرية (localhost URLs) |
| User Secrets | Development بس، خارج الـ repo (في profile المستخدم) | API keys و passwords على جهازك |
| Environment variables | كل البيئات، بتغلب الملفات | CI و containers (ConnectionStrings__Default؛ __ = :) |
| Key Vault / Secret Manager | Production | الأسرار الحقيقية عبر Managed Identity (Azure) |
dotnet user-secrets init --project src/Shop.Api # adds a UserSecretsId to the csproj
dotnet user-secrets set "ConnectionStrings:Default" "Server=localhost;Database=Shop;User Id=sa;Password=..." --project src/Shop.Api
dotnet user-secrets set "OpenAI:ApiKey" "sk-..." --project src/Shop.Api
dotnet user-secrets list --project src/Shop.Api
# Pre-commit safety net: scan staged changes for secrets (e.g. gitleaks) so a mistake never reaches the remote
gitleaks protect --stagedالترتيب بيفرق: كل provider بيتقري بعد اللي قبله وبيغلبه، فـ environment variable بيكسب الـ json. ده بيخليك تشغّل نفس الـ image في كل البيئات وتغيّر بس الـ env. لو حصل سر اتسرب: اعمل rotate للسر فورًا (الأولوية) وبعدين نضّف التاريخ — الترتيب العكسي غلط.
NuGet والـ dependencies: SemVer و lock files والتحديث الآمن
كل package بتضيفه = كود حد تاني بيشتغل بصلاحيات تطبيقك. SemVer (MAJOR.MINOR.PATCH): MAJOR = breaking، MINOR = ميزة متوافقة، PATCH = إصلاح. ده وعد من صاحب الـ package مش ضمان.
- ثبّت النسخ: استخدم نسخ محددة في Central Package Management، وفعّل
RestorePackagesWithLockFileعشان CI يبني بنفس الـ transitive dependencies اللي اختبرتها (dotnet restore --locked-mode). - حدّث بانتظام وبكميات صغيرة: Dependabot/Renovate بيفتحوا PR لكل تحديث، والـ CI بيحكم. تحديث 40 package مرة واحدة بعد سنة = أسبوع debugging.
- قيّم قبل ما تضيف: صيانة نشطة؟ license مناسب (MIT/Apache مقابل GPL في منتج تجاري)؟ عدد الـ dependencies اللي بيجرّها؟ هل الـ BCL فيها البديل أصلًا (
System.Text.Jsonبدل مكتبة JSON إضافية)؟ - أمان:
dotnet list package --vulnerable --include-transitiveفي CI، ومصدر packages موثوق (package source mapping لو فيه feed داخلي — يمنع dependency confusion).
<Project>
<PropertyGroup>
<ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
<RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
</PropertyGroup>
<ItemGroup>
<PackageVersion Include="Microsoft.EntityFrameworkCore.SqlServer" Version="10.0.0" />
<PackageVersion Include="Serilog.AspNetCore" Version="9.0.0" />
</ItemGroup>
</Project>
<!-- csproj files then reference packages WITHOUT a Version attribute -->النسخ في المثال توضيحية؛ استخدم أحدث stable وقت التنفيذ.
قراءة stack trace و exception زي المحترفين
Microsoft.EntityFrameworkCore.DbUpdateException: An error occurred while saving the entity changes.
---> Microsoft.Data.SqlClient.SqlException (0x80131904): Cannot insert duplicate key row in object
'dbo.Customers' with unique index 'IX_Customers_Email'. The duplicate key value is (a@b.com).
at Microsoft.Data.SqlClient.SqlConnection.OnError(...)
...
at Shop.Application.Customers.RegisterCustomerHandler.Handle(RegisterCustomer cmd, CancellationToken ct)
in /src/Shop.Application/Customers/RegisterCustomerHandler.cs:line 42
at Shop.Api.Endpoints.CustomerEndpoints.<>c.<<Map>b__0_0>d.MoveNext() in .../CustomerEndpoints.cs:line 18- النوع والرسالة الخارجية:
DbUpdateException= الفشل حصل فيSaveChanges. - الـ inner exception (
--->): السبب الحقيقي: unique index على Email. - أول frame من كودك:
RegisterCustomerHandler.cs:42— مكان القرار. - الإصلاح الصح: مش try/catch يبلع الخطأ؛ تحقق مسبق + الاعتماد على الـ unique index كضمان أخير (race condition)، وترجمة الخطأ لـ 409 Conflict بـ Problem Details (DTOs & Errors).
Testing loop سريع: filters و watch و coverage
dotnet test --filter "FullyQualifiedName~Invoices" # one feature
dotnet test --filter "Category!=Integration" # skip slow tests locally ([Trait("Category","Integration")])
dotnet watch test --project tests/Shop.Tests # re-run on save (TDD loop)
dotnet test --logger "trx" --results-directory ./TestResults # machine-readable results for CIالهدف: feedback في ثواني وانت بتكتب، والـ suite الكاملة في CI. لو الـ unit tests بتاخد دقايق، غالبًا فيه I/O متخبي فيها (database أو HTTP) — افصله لـ integration tests (Unit Testing).
أخطاء شائعة في الـ workflow
- شغل أسبوع على branch من غير push ← الجهاز باظ أو conflict ضخم. Push يوميًا (حتى draft PR).
- «شغال على جهازي»: نسخة SDK مختلفة. ثبّتها بـ
global.json. - commit لـ
bin/وobj/أو ملفات IDE: استخدمdotnet new gitignoreمن أول يوم. - تجاهل الـ warnings لحد ما تبقى 300 ومحدش يشوف الجديد.
- سؤال في الـ chat من غير سياق: «مش شغال». اكتب: المتوقع، الحاصل، الخطوات، الـ error كامل، وإيه اللي جربته.
{ "sdk": { "version": "10.0.100", "rollForward": "latestFeature" } }تمارين وحلول ومشروع صغير
المستوى الأول — تأسيس:
- اطبع إصدارات الأدوات الخمسة. الحل: شغّل
dotnet --infoوgit --versionوnode --versionوnpm --versionوpython --versionوسجّل الناتج الحقيقي. - أنشئ Console app وشغّله. الحل: نفّذ أوامر أول الدرس، وتأكد إن Terminal داخل فولدر المشروع قبل
dotnet run. - أنشئ venv وثبّت package. الحل: فعّل البيئة ثم
python -m pip install requestsوبعدهاpython -m pip freeze.
المستوى الثاني — تطبيق:
- API بيرجع 400؛ هل السبب validation ولا route؟ الحل: افحص URL والـ method والـ response body في Postman، ثم جرّب payload صحيح وآخر ناقص خاصية مطلوبة وقارن النتيجة.
- Angular بيعرض قائمة فاضية رغم إن API بيرجع بيانات. الحل: افتح Network وتأكد من response، ثم Console، ثم افحص mapping والـ subscription أو async flow وربط template.
- Exception بيظهر في production فقط. الحل: اجمع correlation ID ووقت الحدوث ونسخة التطبيق و stack trace بعد تنقيح الأسرار، وقارن configuration والـ dependencies في staging.
المستوى الثالث — استقلالية:
- اكتب bug report قابل لإعادة الإنتاج. الحل: استخدم القالب السابق وأضف request صغير و expected/actual واحذف الأسرار.
- AI اقترح method مش موجودة في إصدارك. الحل: افتح docs للإصدار المثبت، راجع package version، واستبدل الاقتراح بـ API مدعوم واكتب test.
- اعمل regression test. الحل: اكتب test يفشل قبل الإصلاح ويمر بعده، ثم شغّل suite كاملة.
المشروع المصغّر: جهّز Starter Workspace فيه Console app، API request collection، Python venv، README للتثبيت، وملف BUG-REPORT.md لمشكلة أعدت إنتاجها وأصلحتها. معيار القبول: شخص تاني يقدر يجهّز البيئة ويشغّل المشروع من README من غير شرح شفهي.
أسئلة إنترفيو
إيه الفرق بين Microsoft Visual Studio و Visual Studio Code؟
إمتى تستخدم Postman وإمتى DevTools؟
إيه الفرق بين stack trace و logs؟
ليه نستخدم Python venv؟
إزاي تتحقق من اقتراح AI؟
المراجع والقراءة الإضافية
الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)
التوثيق الرسمي — Official documentation
خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.