Sokkary | Code3arabi

2.6 ‎.NET API - Roles & Authorization (السماح بناءً على الدور) بعد تفعيل تسجيل الدخول باستخدام JWT، يُفضل في بعض الأنظمة إضافة ميزة الأدوار (Roles) لتحديد صلاحيات المستخدمين، بحيث يُسمح فقط لمستخدمين بدور معين بالدخول إلى Endpoint معين. 👥 أمثلة على الأدوار الشائعة Admin : يمكنه إدارة كل شيء. User : يمكنه فقط عرض البيانات. Manager : لديه صلاحيات خاصة بالإشراف. 🔐 إضافة الدور إلى التوكن [HttpPost("login")] public IActionResult Login(UserLoginDto login) { if (login.Username == "admin" && login.Password == "123") { var claims = new[] { new Claim(ClaimTypes.Name, login.Username), new Claim(ClaimTypes.Role, "Admin") }; var key = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("your_super_secret_key_here")); var creds = new SigningCredentials(key, SecurityAlgorithms.HmacSha256); var token = new JwtSecurityToken( expir...

2.5 ‎.NET API - حماية الـAPI باستخدام JWT Authentication JWT أو JSON Web Token هو معيار يُستخدم لتأمين الـAPI من خلال إصدار "توكن" يُرفق مع كل طلب، ويُستخدم للتحقق من هوية المستخدم دون الحاجة لتخزين الجلسة على الخادم. 🔐 1. ما هو التوكن؟ التوكن هو سلسلة نصية تُولد عند تسجيل الدخول، وتُحفظ لدى العميل (Client)، وتُرسل مع كل طلب في الـ Header. Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... 📦 2. تثبيت الحزم المطلوبة dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer ⚙️ 3. إعداد المصادقة في Program.cs builder.Services.AddAuthentication("Bearer") .AddJwtBearer("Bearer", options => { options.TokenValidationParameters = new TokenValidationParameters { ValidateIssuer = false, ValidateAudience = false, ValidateLifetime = true, ValidateIssuerSigningKey = true, IssuerSigningKey = new SymmetricSecurityKey( Encoding.UTF8.G...

2.4 ‎.NET API - توثيق الـAPI باستخدام Swagger Swagger هو أداة لتوثيق واختبار واجهات الـ Web API، وتُعرف الآن باسم OpenAPI . يتم دمجها بسهولة مع ASP.NET Core Web API لتوليد صفحة توثيق تفاعلية لكل الـEndpoints. ⚙️ 1. تثبيت الحزمة (إذا لم تكن موجودة) عادة ما تكون موجودة تلقائيًا عند إنشاء مشروع Web API جديد، لكن يمكنك تثبيتها يدويًا: dotnet add package Swashbuckle.AspNetCore 🧠 2. تفعيل Swagger في Program.cs builder.Services.AddEndpointsApiExplorer(); builder.Services.AddSwaggerGen(); var app = builder.Build(); if (app.Environment.IsDevelopment()) { app.UseSwagger(); app.UseSwaggerUI(); } 🌐 3. الدخول إلى واجهة Swagger بعد تشغيل المشروع، افتح الرابط التالي في المتصفح: http://localhost:5000/swagger ستظهر صفحة تحتوي على كل الـControllers وEndpoints، ويمكنك تجربة أي طلب منها مباشرة. 📝 4. إضافة تعليقات XML لتفاصيل التوثيق من داخل خصائص المشروع، فعّل خيار XML documentation file ثم أضف التعليق فوق كل دالة: /// <summary> /// يُرجع جميع المنتجات. /// ...

2.3 ‎.NET API - فلترة وترتيب البيانات (Filtering, Sorting, Pagination) عند عرض بيانات كثيرة في Web API، من الأفضل توفير مرونة للمستخدم مثل: 🔍 فلترة (Filter) حسب شروط معينة ⬆️⬇️ ترتيب (Sort) حسب اسم أو تاريخ أو سعر 📄 تقسيم الصفحات (Pagination) لتقليل الحمل وتسريع الأداء 🔍 مثال على الفلترة Filtering [HttpGet] public IActionResult GetAll(string? search) { var query = _context.Products.AsQueryable(); if (!string.IsNullOrWhiteSpace(search)) query = query.Where(p => p.Name.Contains(search)); return Ok(query.ToList()); } مثال على الرابط: GET /api/products?search=laptop ⬆️⬇️ مثال على الترتيب Sorting public IActionResult GetAll(string? sort) { var query = _context.Products.AsQueryable(); if (sort == "name") query = query.OrderBy(p => p.Name); else if (sort == "price_desc") query = query.OrderByDescending(p => p.Price); return Ok(query.ToList()); } مثال: GET /api/products?sort=price...

2.2 ‎.NET API - التعامل مع الأخطاء (Exception Handling + Middleware) عند بناء Web API احترافي، من المهم جدًا التعامل مع الأخطاء بطريقة منظمة وآمنة، بحيث لا يظهر للمستخدم تفاصيل داخلية، ويتم تسجيل الأخطاء لتتبعها لاحقًا. 🧨 ما أنواع الأخطاء الشائعة؟ ❌ NullReferenceException ❌ SqlException أو أخطاء قواعد البيانات ❌ UnauthorizedAccessException ❌ ArgumentException عند تمرير قيم غير صحيحة 🔧 طرق التعامل مع الأخطاء لدينا طريقتان رئيسيتان: ✅ استخدام try-catch داخل الـ Controller أو Service ✅ بناء Global Exception Handling Middleware 📍 مثال باستخدام try-catch [HttpGet("{id}")] public IActionResult GetById(int id) { try { var product = _context.Products.Find(id); if (product == null) return NotFound("المنتج غير موجود"); return Ok(product); } catch (Exception ex) { _logger.LogError(ex, "خطأ أثناء استرجاع المنتج"); return StatusCode(500, "حدث خطأ داخلي...

2.1 ‎.NET API - DTOs وAutoMapper: نقل البيانات بين الطبقات DTO هي اختصار لـ Data Transfer Object ، وهي كائنات تُستخدم لنقل البيانات بين الطبقات داخل التطبيق، خاصة من الطبقة الخلفية (Backend) إلى العميل (Client). أما AutoMapper فهي مكتبة في ‎.NET تُستخدم لتحويل البيانات تلقائيًا بين الكائنات (من Entity إلى DTO والعكس). 🧱 لماذا نستخدم DTOs؟ ✅ فصل كود قاعدة البيانات (Entity) عن كود العرض (Client). ✅ حماية الحقول الحساسة من الظهور في واجهة المستخدم. ✅ تحسين الأداء بنقل الحقول المطلوبة فقط. 📦 مثال: كيان المنتج Product // الكيان المرتبط بقاعدة البيانات public class Product { public int Id { get; set; } public string Name { get; set; } public decimal Price { get; set; } public DateTime CreatedAt { get; set; } } نريد أن نعرض فقط الاسم والسعر: // DTO public class ProductDto { public string Name { get; set; } public decimal Price { get; set; } } ⚙️ تثبيت AutoMapper dotnet add package AutoMapper.Extensions.Microsoft.DependencyInjection ...

1.8 ‎.NET API - قراءة الـappsettings.json وربط البيانات ملف appsettings.json هو ملف الإعدادات الرئيسي في مشاريع ASP.NET Core، ويُستخدم لتخزين إعدادات التطبيق مثل بيانات الاتصال، مفاتيح API، إعدادات التكوين الخاصة، وغيرها. 🧾 تنسيق ملف appsettings.json { "ConnectionStrings": { "DefaultConnection": "Server=.;Database=MyDb;Trusted_Connection=True;" }, "MyAppSettings": { "SiteTitle": "Drift CMS", "ItemsPerPage": 10 } } 📦 قراءة الإعدادات في C# يمكنك إنشاء كلاس يمثل القسم الذي تريد قراءته: public class MyAppSettings { public string SiteTitle { get; set; } public int ItemsPerPage { get; set; } } ثم تسجله في Program.cs : builder.Services.Configure<MyAppSettings>( builder.Configuration.GetSection("MyAppSettings")); 🧠 استخدام الإعدادات داخل Controller أو Service using Microsoft.Extensions.Options; [ApiController] [Route("api/[controller]")] publi...

1.7 ‎.NET API - التعامل مع HTTP Methods: GET, POST, PUT, DELETE تُستخدم HTTP Methods في Web API لتحديد نوع العملية المطلوب تنفيذها على البيانات. في ASP.NET Core Web API، يتم ربط كل Method بميزة محددة من خلال Attribute مثل: [HttpGet] أو [HttpPost] . 📥 1. GET - جلب البيانات يستخدم للحصول على البيانات من السيرفر. [HttpGet] public IActionResult GetAll() { return Ok(_context.Products.ToList()); } مثال على الطلب في Postman أو المتصفح: GET http://localhost:5000/api/products 📤 2. POST - إضافة بيانات جديدة يُستخدم لإنشاء سجل جديد في قاعدة البيانات. [HttpPost] public IActionResult Create(Product product) { _context.Products.Add(product); _context.SaveChanges(); return Ok(product); } مثال على بيانات تُرسل في جسم الطلب: { "name": "New Product", "price": 200 } ✏️ 3. PUT - تحديث البيانات يُستخدم لتحديث سجل موجود بالكامل. [HttpPut("{id}")] public IActionResult Update(int id, Product product) { if (id != pro...

1.6 ‎.NET API - CRUD باستخدام Entity Framework Core (مع قاعدة بيانات SQLite أو SQL Server) في هذا الدرس سنتعلم كيفية تنفيذ العمليات الأساسية CRUD (إنشاء، قراءة، تحديث، حذف) باستخدام Entity Framework Core وربطها بـ Web API. 📦 ما هو EF Core؟ Entity Framework Core هو ORM (Object-Relational Mapper) يتيح لك التعامل مع قاعدة البيانات ككائنات C# بدون الحاجة لكتابة SQL يدوي. 🔧 1. إعداد المشروع لاستخدام EF Core أولاً، نثبّت الحزم المطلوبة: dotnet add package Microsoft.EntityFrameworkCore dotnet add package Microsoft.EntityFrameworkCore.SqlServer dotnet add package Microsoft.EntityFrameworkCore.Tools إذا كنت تفضل SQLite: dotnet add package Microsoft.EntityFrameworkCore.Sqlite 📄 2. إنشاء الكيان (Model) public class Product { public int Id { get; set; } public string Name { get; set; } public decimal Price { get; set; } } 🧠 3. إنشاء DbContext using Microsoft.EntityFrameworkCore; public class AppDbContext : DbContext { public AppDbContext(DbContextOpt...

‎.NET API - استخدام Postman لاختبار الـEndpoints Postman هو أداة مجانية قوية تتيح لك إرسال طلبات HTTP بسهولة إلى API الخاص بك واختبار النتائج. مفيد جدًا أثناء تطوير Web API في ‎.NET. 🧩 ما الذي يمكننا اختباره باستخدام Postman؟ ✅ طلبات GET لاسترجاع البيانات ✅ طلبات POST لإرسال بيانات ✅ طلبات PUT لتحديث بيانات ✅ طلبات DELETE لحذف بيانات 🔌 تشغيل Web API أولاً، تأكد أن Web API يعمل على عنوان مثل: https://localhost:5001/api/products في حال كنت تستخدم HTTP فقط (بدون SSL): http://localhost:5000/api/products 🚀 استخدام Postman خطوة بخطوة افتح تطبيق Postman. اختر نوع الطلب من القائمة (مثل: GET, POST). ضع رابط الـ API في خانة الرابط. إن كنت سترسل بيانات (POST أو PUT)، اختر Body ⮕ raw ⮕ JSON، وأدخل البيانات بصيغة JSON. اضغط Send . 📤 مثال على POST طلب إلى /api/products لإضافة منتج جديد: { "name": "Keyboard", "price": 100 } 📥 مثال على GET طلب إلى /api/products لاسترجاع كل المنتجات: GET http://lo...

1.4 ‎.NET API - إعداد الـRouting في Web API Routing (التوجيه) هو الآلية التي من خلالها يعرف Web API إلى أي Controller و Action يجب توجيه الطلب المرسل من العميل. في ASP.NET Core Web API، يمكن إعداد التوجيه باستخدام Attribute Routing ، وهو الأسلوب الأكثر استخدامًا مع الـ Web APIs. 🔧 ما هو Attribute Routing؟ Attribute Routing يعني كتابة التوجيه مباشرة فوق الـController أو الـAction باستخدام خصائص مثل: [Route] و [HttpGet] و [HttpPost] . [ApiController] [Route("api/[controller]")] public class ProductsController : ControllerBase { [HttpGet] public IActionResult GetAll() => Ok(new[] { "Laptop", "Mouse" }); [HttpGet("{id}")] public IActionResult GetById(int id) => Ok($"Product #{id}"); [HttpPost] public IActionResult Add(string name) => Ok($"Added {name}"); } التوجيه في المثال أعلاه يعمل كالتالي: GET /api/products ⟶ GetAll() GET /api/products/5 ⟶ GetById(5) POST /api/pro...

1.3 ‎.NET API - هيكل المشروع: Controllers وModels وProgram.cs في مشاريع ‎ ASP.NET Core Web API ، يتكوّن المشروع من ملفات أساسية تنظم سير العمل بين الطلبات والاستجابات. دعنا نلقي نظرة على أهم هذه الملفات: 📁 1. Controllers Controllers هي المسؤولة عن استقبال الطلبات من المستخدمين والتفاعل معها. أي Controller يرث من ControllerBase ، ويحتوي على Actions (مثل: Get, Post) تعالج الطلب وترجع استجابة (عادة JSON). using Microsoft.AspNetCore.Mvc; [ApiController] [Route("api/[controller]")] public class ProductsController : ControllerBase { [HttpGet] public IActionResult GetAll() { return Ok(new[] { "Laptop", "Mouse", "Keyboard" }); } } ملاحظة: [ApiController] تسهل التحقق من البيانات وتنسيق الردود تلقائيًا. 📁 2. Models Models هي الطبقة التي تمثل الكائنات أو البيانات المستخدمة داخل التطبيق. غالبًا ما تُستخدم لتمثيل كائنات قاعدة البيانات أو البيانات القادمة من الطلب. public class Product { public int Id { get; s...

1.2 ‎.NET API - إنشاء مشروع ASP.NET Core Web API خطوة بخطوة في هذا الدرس، سنتعلم كيفية إنشاء مشروع Web API باستخدام ASP.NET Core من البداية حتى تشغيل أول Endpoint. هنستخدم Visual Studio أو CLI حسب ما تفضل. 🛠️ الخطوة 1: إنشاء المشروع افتح Visual Studio واختر: File ⮕ New ⮕ Project اختر ASP.NET Core Web API سم المشروع (مثلاً: MyApi ) في صفحة الإعدادات، اختر: ✅ .NET 6 أو أعلى ✅ تعطيل HTTPS (اختياريًا للتجربة) ✅ تمكين OpenAPI (Swagger) أو يمكنك استخدام CLI: dotnet new webapi -n MyApi 📁 هيكل المشروع الناتج Program.cs : نقطة البداية وتشغيل التطبيق. Controllers/WeatherForecastController.cs : مثال جاهز لـ API. appsettings.json : إعدادات المشروع (اتصال بقاعدة البيانات، مفاتيح... إلخ). 🚀 الخطوة 2: تشغيل المشروع من Visual Studio، اضغط F5 أو شغّل المشروع من CLI: cd MyApi dotnet run المتصفح سيفتح صفحة Swagger تلقائيًا: https://localhost:5001/swagger 🔍 الخطوة 3: تجربة أول Endpoint اذهب إلى /WeatherForecast م...

.NET API - ما هي Web API ولماذا نستخدمها؟ Web API هي اختصار لـ Web Application Programming Interface ، وهي وسيلة تتيح لتطبيقات مختلفة أن تتواصل وتتبادل البيانات من خلال بروتوكول HTTP. فمثلًا، يمكن لتطبيق ويب أو تطبيق جوال أن يطلب بيانات من سيرفر باستخدام Web API ويرد السيرفر ببيانات بصيغة JSON أو XML. ما الفرق بين Web API وMVC؟ في ASP.NET MVC ، الهدف هو بناء صفحات HTML تعرض للمستخدم، بينما في ASP.NET Web API الهدف هو إرسال واستقبال بيانات (عادةً بصيغة JSON) بدون واجهة مرئية. MVC: يعرض صفحات HTML. API: يرسل ويستقبل بيانات فقط (بدون HTML). أين نستخدم Web API؟ تُستخدم Web API في مواقف كثيرة منها: بناء تطبيق جوال يتواصل مع السيرفر لجلب البيانات. فصل الواجهة الأمامية (مثل React أو Blazor WebAssembly) عن الواجهة الخلفية. الربط بين الأنظمة المختلفة (مثل نظام نقاط البيع مع نظام المخزون). ماذا نحتاج لبناء Web API؟ لبناء Web API باستخدام .NET نحتاج: Visual Studio أو Visual Studio Code ASP.NET Core SDK (يفضل آخر إصدار) قاعدة بيانات (مثل ...