Menu
CoddyTech

CORS

جزء من قسم واجهات API بنمط REST في رحلة ASP.NET Core على Coddy. الدرس 17 من 20.

تستدعي صفحة على https://shop.example.com واجهة API الخاصة بك باستخدام fetch، ويحظر المتصفح الإجابة. تسمح المتصفحات للصفحة بقراءة الإجابات من المصدر الخاص بها فقط (المخطط والمضيف والمنفذ)، ما لم يسمح الخادم للمصادر الأخرى بذلك باستخدام ترويسات CORS. قبل إرسال طلب PUT أو PATCH أو DELETE أو طلب يتضمن متن JSON، يرسل المتصفح أولًا طلب OPTIONS، وهو الطلب الاستباقي، ولا يرسل الطلب الفعلي إلا إذا سمحت الإجابة بذلك.

builder.Services.AddCors(options =>
    options.AddPolicy("shop", policy => policy
        .WithOrigins("https://shop.example.com")
        .WithMethods("GET", "POST")
        .WithHeaders("Content-Type")));
var app = builder.Build();
app.UseCors("shop");

تجيب برمجية CORS الوسيطة عن الطلب الاستباقي بالرمز 204 وبالطرائق والترويسات المسموح بها، وتضيف Access-Control-Allow-Origin إلى كل إجابة موجّهة إلى ذلك المصدر. لا يحصل أي مصدر آخر على ترويسات CORS، لذا يحظره متصفحه. المتصفحات وحدها هي التي تفرض CORS؛ أما curl وشريط الطلبات فيتجاهلانها.

challenge icon

التحدي

متوسط

يريد تطبيق لوحة على موقع آخر، https://board.example.com، استدعاء واجهة API الخاصة بك من المتصفح. اسمح لهذا المصدر فقط.

  1. في Program.cs، أضف قبل builder.Build() سياسة CORS باسم board باستخدام builder.Services.AddCors. تسمح هذه السياسة بالمصدر https://board.example.com والطرق GET وPOST وPUT وPATCH وDELETE، والترويسة Content-Type.
  2. تعرض اللوحة "page 1 of 3" من X-Total-Count. لا يمكن لصفحة من مصدر آخر قراءة سوى بضعة ترويسات استجابة قياسية، ما لم يكشف الخادم عن ترويسات إضافية، لذا أضف .WithExposedHeaders("X-Total-Count") إلى السياسة.
  3. بعد app.UseStatusCodePages();، فعّل السياسة باستخدام app.UseCors("board");

يردّ طلب التمهيد المسبق من اللوحة برمز 204 مع هذه الترويسات:

Access-Control-Allow-Origin: https://board.example.com
Access-Control-Allow-Methods: GET,POST,PUT,PATCH,DELETE
Access-Control-Allow-Headers: Content-Type

جرّب ذلك: اضغط على تشغيل، واختر OPTIONS، والمسار /api/tasks/2، وأضف الترويستين Origin: https://board.example.com وAccess-Control-Request-Method: DELETE. اضغط على إرسال: يجب أن تكون الاستجابة 204، مع جسم فارغ والترويسات المذكورة أعلاه في علامة تبويب الترويسات. أرسل GET /api/tasks مع Origin نفسه: يجب أن تكون الاستجابة 200 مع Access-Control-Allow-Origin وAccess-Control-Expose-Headers. عند استخدام Origin: https://evil.example.com، لن تحتوي الاستجابة على ترويسات CORS.

جرّب بنفسك

using System.ComponentModel.DataAnnotations;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddProblemDetails();
var app = builder.Build();

app.UseExceptionHandler();
app.UseStatusCodePages();

var tasks = new List<TaskItem>
{
    new(1, "Write the project brief", false, 1),
    new(2, "Book the meeting room", true, 3),
    new(3, "Send the invoice", false),
};
var nextId = 4;

bool TitleTaken(string title, int exceptId) =>
    tasks.Any(t => t.Id != exceptId && string.Equals(t.Title, title, StringComparison.OrdinalIgnoreCase));

app.MapGet("/api/tasks", (bool? done, string? search, int? priority, string? sort, HttpResponse response, int page = 1, int pageSize = 10) =>
{
    var errors = new Dictionary<string, string[]>();
    if (sort is not null && sort != "id" && sort != "title" && sort != "priority")
        errors["sort"] = ["Sort by id, title or priority."];
    if (priority is < 1 or > 3)
        errors["priority"] = ["Priority is 1 to 3."];
    if (page < 1)
        errors["page"] = ["Page starts at 1."];
    if (pageSize < 1 || pageSize > 50)
        errors["pageSize"] = ["Page size is 1 to 50."];
    if (errors.Count > 0) return Results.ValidationProblem(errors);

    IEnumerable<TaskItem> result = tasks;
    if (done is not null) result = result.Where(t => t.Done == done);
    if (!string.IsNullOrWhiteSpace(search))
        result = result.Where(t => t.Title.Contains(search, StringComparison.OrdinalIgnoreCase));
    if (priority is not null) result = result.Where(t => t.Priority == priority);
    if (sort == "title") result = result.OrderBy(t => t.Title);
    if (sort == "priority") result = result.OrderBy(t => t.Priority);

    var matching = result.ToList();
    response.Headers["X-Total-Count"] = matching.Count.ToString();
    return Results.Ok(matching.Skip((page - 1) * pageSize).Take(pageSize));
});

app.MapGet("/api/tasks/{id:int}", (int id) =>
{
    var task = tasks.Find(t => t.Id == id);
    return task is null ? Results.NotFound() : Results.Ok(task);
});

app.MapPost("/api/tasks", (TaskInput input) =>
{
    var errors = Validation.Errors(input);
    if (errors is not null) return Results.ValidationProblem(errors);
    if (TitleTaken(input.Title, 0))
        return Results.Problem(title: "A task with this title already exists.", statusCode: 409);
    var task = new TaskItem(nextId++, input.Title, input.Done, input.Priority);
    tasks.Add(task);
    return Results.Created($"/api/tasks/{task.Id}", task);
});

app.MapPut("/api/tasks/{id:int}", (int id, TaskInput input) =>
{
    var errors = Validation.Errors(input);
    if (errors is not null) return Results.ValidationProblem(errors);
    var index = tasks.FindIndex(t => t.Id == id);
    if (index == -1) return Results.NotFound();
    if (TitleTaken(input.Title, id))
        return Results.Problem(title: "A task with this title already exists.", statusCode: 409);
    tasks[index] = new TaskItem(id, input.Title, input.Done, input.Priority);
    return Results.Ok(tasks[index]);
});

app.MapPatch("/api/tasks/{id:int}", (int id, TaskPatch patch) =>
{
    var errors = Validation.Errors(patch);
    if (errors is not null) return Results.ValidationProblem(errors);
    var index = tasks.FindIndex(t => t.Id == id);
    if (index == -1) return Results.NotFound();
    if (patch.Title is not null && TitleTaken(patch.Title, id))
        return Results.Problem(title: "A task with this title already exists.", statusCode: 409);
    var task = tasks[index];
    tasks[index] = task with
    {
        Title = patch.Title ?? task.Title,
        Done = patch.Done ?? task.Done,
        Priority = patch.Priority ?? task.Priority,
    };
    return Results.Ok(tasks[index]);
});

app.MapDelete("/api/tasks/{id:int}", (int id) =>
{
    var removed = tasks.RemoveAll(t => t.Id == id);
    return removed == 0 ? Results.NotFound() : Results.NoContent();
});

app.MapDelete("/api/tasks", (bool? done) =>
{
    if (done != true)
    {
        return Results.ValidationProblem(new Dictionary<string, string[]>
        {
            ["done"] = ["Add ?done=true to delete the done tasks."],
        });
    }
    tasks.RemoveAll(t => t.Done);
    return Results.NoContent();
});

app.Run();

record TaskItem(int Id, string Title, bool Done, int Priority = 2);
record TaskInput(
    [property: Required(ErrorMessage = "Title is required."), StringLength(80)] string Title,
    bool Done,
    [property: Range(1, 3)] int Priority = 2);
record TaskPatch(string? Title, bool? Done, [property: Range(1, 3)] int? Priority);
quiz iconاختبر نفسك

يتضمن هذا الدرس اختبارًا قصيرًا. ابدأ الدرس للإجابة عليه وتتبّع تقدمك.

جميع دروس واجهات API بنمط REST