Öğretici: ASP.NET Core ile web API'si oluşturma

  • Makale

Yayımlayanlar Rick Anderson ve Kirk Larkin

Not

Bu, bu makalenin en son sürümü değildir. En son sürüme geçmek için içindekiler tablosunun üst kısmındaki ASP.NET Core sürüm seçiciyi kullanın.

Sürüm seçici

Seçici dar bir tarayıcı penceresinde görünmüyorsa, pencereyi genişletin veya dikey üç noktayı (⋮) >İçindekiler tablosu'nu seçin.

İçindekiler tablosu seçicisi

Bu öğreticide, veritabanı kullanan denetleyici tabanlı bir web API'sinin temelleri öğretildi. ASP.NET Core'de API oluşturmaya yönelik bir diğer yaklaşım da en az API oluşturmaktır. Minimum API'ler ile denetleyici tabanlı API'ler arasında seçim yaparken yardım için bkz. API'lere genel bakış. En az API oluşturma öğreticisi için bkz. Öğretici: ASP.NET Core ile minimum API oluşturma.

Genel Bakış

Bu öğretici aşağıdaki API'yi oluşturur:

API Açıklama İstek gövdesi Yanıt gövdesi
GET /api/todoitems Tüm yapılacaklar öğelerini alma Hiçbiri Yapılacaklar öğeleri dizisi
GET /api/todoitems/{id} Öğeyi kimliğine göre alma Hiçbiri Yapılacaklar öğesi
POST /api/todoitems Yeni öğe ekleme Yapılacaklar öğesi Yapılacaklar öğesi
PUT /api/todoitems/{id} Var olan bir öğeyi güncelleştirme Yapılacaklar öğesi Hiçbiri
DELETE /api/todoitems/{id}     Öğeyi silme Hiçbiri Hiçbiri

Aşağıdaki diyagramda uygulamanın tasarımı gösterilmektedir.

İstemci, soldaki bir kutuyla temsil edilir. Bir istek gönderir ve uygulamadan sağ tarafta çizilmiş bir kutu olan bir yanıt alır. Uygulama kutusunun içinde üç kutu denetleyiciyi, modeli ve veri erişim katmanını temsil ediyor. İstek uygulamanın denetleyicisine gelir ve denetleyici ile veri erişim katmanı arasında okuma/yazma işlemleri gerçekleşir. Model seri hale getirilir ve yanıtta istemciye döndürülür.

Önkoşullar

Web projesi oluşturma

  • Dosyamenüsünden Yeni Proje'yi> seçin.
  • Arama kutusuna Web API'sini girin.
  • ASP.NET Core Web API'sini seçin ve İleri'yi seçin.
  • Yeni projenizi yapılandırın iletişim kutusunda projeyi TodoApi olarak adlandırın ve İleri'yi seçin.
  • Ek bilgiler iletişim kutusunda:
    • Framework'ün.NET 8.0 (Önizleme) olduğunu onaylayın.
    • Denetleyicileri kullan (en az API kullanmak için işaretini kaldır) onay kutusunun işaretli olduğunu onaylayın.
    • OpenAPI desteğini etkinleştir onay kutusunun işaretli olduğunu onaylayın.
    • Oluştur’u seçin.

NuGet paketi ekleme

Bu öğreticide kullanılan veritabanını desteklemek için bir NuGet paketi eklenmelidir.

  • Araçlar menüsünde NuGet Paket Yöneticisi > Çözüm için NuGet Paketlerini Yönet'i seçin.
  • Gözat sekmesini seçin.
  • Ön sürümü dahil et onay kutusunu seçin.
  • Arama kutusuna Microsoft.EntityFrameworkCore.InMemory yazın ve öğesini seçin Microsoft.EntityFrameworkCore.InMemory.
  • Sağ bölmede Proje onay kutusunu ve ardından Yükle'yi seçin.

Not

.NET uygulamalarına paket ekleme hakkında yönergeler için, Paket tüketimi iş akışında (NuGet belgeleri)paketleri yüklemek ve yönetmek altındaki makalelere bakın. NuGet.org'da doğru paket sürümlerini onaylayın.

Projeyi test etme

Proje şablonu, Swagger desteğine sahip bir WeatherForecast API oluşturur.

Hata ayıklayıcı olmadan çalıştırmak için Ctrl+F5 tuşlarına basın.

Visual Studio, bir proje henüz SSL kullanmak üzere yapılandırılmamışsa aşağıdaki iletişim kutusunu görüntüler:

Bu proje SSL kullanacak şekilde yapılandırılmıştır. Tarayıcıda SSL uyarılarından kaçınmak için, IIS Express tarafından oluşturulan otomatik olarak imzalanan sertifikaya güvenmeyi seçebilirsiniz. IIS Express SSL sertifikasına güvenmek istiyor musunuz?

IIS Express SSL sertifikasına güveniyorsanız Evet'i seçin.

Aşağıdaki iletişim kutusu görüntülenir:

Güvenlik uyarısı iletişim kutusu

Geliştirme sertifikasına güvenmeyi kabul ediyorsanız Evet'i seçin.

Firefox tarayıcısına güvenme hakkında bilgi için bkz. Firefox SEC_ERROR_INADEQUATE_KEY_USAGE sertifika hatası.

Visual Studio varsayılan tarayıcıyı başlatır ve konumuna https://localhost:<port>/swagger/index.htmlgider; burada <port> rastgele seçilmiş bir bağlantı noktası numarasıdır.

Swagger sayfası /swagger/index.html görüntülenir. GET>Try it try it out>Execute öğesini seçin. Sayfa şu şekilde görüntülenir:

  • WeatherForecast API'sini test etmek için Curl komutu.
  • WeatherForecast API'sini test etmek için URL.
  • Yanıt kodu, gövde ve üst bilgiler.
  • Medya türlerinin, örnek değerin ve şemanın yer aldığı bir açılan liste kutusu.

Swagger sayfası görünmüyorsa bu GitHub sorununa bakın.

Swagger, web API'leri için yararlı belgeler ve yardım sayfaları oluşturmak için kullanılır. Bu öğreticide uygulamayı test etmek için Swagger kullanılır. Swagger hakkında daha fazla bilgi için bkz. Swagger / OpenAPI ile ASP.NET Core web API'si belgeleri.

İstek URL'sini kopyalayıp tarayıcıya yapıştırın:https://localhost:<port>/weatherforecast

JSON aşağıdaki örneğe benzer şekilde döndürülür:

[
    {
        "date": "2019-07-16T19:04:05.7257911-06:00",
        "temperatureC": 52,
        "temperatureF": 125,
        "summary": "Mild"
    },
    {
        "date": "2019-07-17T19:04:05.7258461-06:00",
        "temperatureC": 36,
        "temperatureF": 96,
        "summary": "Warm"
    },
    {
        "date": "2019-07-18T19:04:05.7258467-06:00",
        "temperatureC": 39,
        "temperatureF": 102,
        "summary": "Cool"
    },
    {
        "date": "2019-07-19T19:04:05.7258471-06:00",
        "temperatureC": 10,
        "temperatureF": 49,
        "summary": "Bracing"
    },
    {
        "date": "2019-07-20T19:04:05.7258474-06:00",
        "temperatureC": -1,
        "temperatureF": 31,
        "summary": "Chilly"
    }
]

Model sınıfı ekleme

Model, uygulamanın yönettiği verileri temsil eden bir sınıf kümesidir. Bu uygulamanın modeli sınıfıdır TodoItem .

  • Çözüm Gezgini'da projeye sağ tıklayın. Yeni Klasör Ekle'yi> seçin. klasörünü Modelsadlandırın.
  • Klasöre sağ tıklayın veSınıfEkle'yi>Models seçin. Sınıfı TodoItem olarak adlandırın ve Ekle'yi seçin.
  • Şablon kodunu aşağıdakilerle değiştirin:
namespace TodoApi.Models;

public class TodoItem
{
    public long Id { get; set; }
    public string? Name { get; set; }
    public bool IsComplete { get; set; }
}

özelliği, Id ilişkisel veritabanında benzersiz anahtar olarak işlev görür.

Model sınıfları projede herhangi bir yere gidebilir, ancak Models klasör kural tarafından kullanılır.

Veritabanı bağlamı ekleme

Veritabanı bağlamı, bir veri modeli için Entity Framework işlevselliğini koordine eden ana sınıftır. Bu sınıf, sınıfından Microsoft.EntityFrameworkCore.DbContext türetilerek oluşturulur.

  • Klasöre sağ tıklayın veSınıfEkle'yi>Models seçin. Sınıfı TodoContext olarak adlandırın ve Ekle'ye tıklayın.

  • Aşağıdaki kodu girin:

    using Microsoft.EntityFrameworkCore;

namespace TodoApi.Models;

public class TodoContext : DbContext
{
    public TodoContext(DbContextOptions<TodoContext> options)
        : base(options)
    {
    }

    public DbSet<TodoItem> TodoItems { get; set; } = null!;
}

Veritabanı bağlamını kaydetme

ASP.NET Core'de, VERITABANı bağlamı gibi hizmetlerin bağımlılık ekleme (DI) kapsayıcısıyla kaydedilmesi gerekir. Kapsayıcı, denetleyicilere hizmeti sağlar.

Aşağıdaki vurgulanmış kodla güncelleştirin Program.cs :

using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddDbContext<TodoContext>(opt =>
    opt.UseInMemoryDatabase("TodoList"));
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Yukarıdaki kod:

  • Yönergeleri ekler using .
  • VERITABANı bağlamını DI kapsayıcısına ekler.
  • Veritabanı bağlamında bellek içi veritabanı kullanılacağını belirtir.

Bir denetleyicinin iskelesi

  • Denetleyiciler klasörüne sağ tıklayın.

  • Yeni İskeleli Öğe Ekle'yi> seçin.

  • Entity Framework kullanarak eylemlerle API Denetleyicisi'ni ve ardından Ekle'yi seçin.

  • Eylemlerle API Denetleyicisi Ekle iletişim kutusunda Entity Framework kullanarak:

    • Model sınıfındaTodoItem (TodoApi.Models) öğesini seçin.
    • Veri bağlamı sınıfındaTodoContext (TodoApi.Models) öğesini seçin.
    • Add (Ekle) seçeneğini belirleyin.

    yapı iskelesi işlemi başarısız olursa, yapı iskelesini ikinci kez denemek için Ekle'yi seçin.

Oluşturulan kod:

  • sınıfını özniteliğiyle [ApiController] işaretler. Bu öznitelik, denetleyicinin web API'sinin isteklerine yanıt verdiğini gösterir. Özniteliğin etkinleştirilen belirli davranışlar hakkında bilgi için bkz. ASP.NET Core ile web API'leri oluşturma.
  • Veritabanı bağlamını (TodoContext) denetleyiciye eklemek için DI kullanır. Veritabanı bağlamı, denetleyicideki CRUD yöntemlerinin her birinde kullanılır.

aşağıdakiler için ASP.NET Core şablonları:

  • Görünümlere sahip denetleyiciler yol şablonuna dahildir [action] .
  • API denetleyicileri yol şablonuna dahil [action] değildir.

[action] Belirteç yol şablonunda olmadığında, eylem adı (yöntem adı) uç noktaya dahil değildir. Diğer bir ifadeyle, eylemin ilişkili yöntem adı eşleşen yolda kullanılmaz.

PostTodoItem oluşturma yöntemini güncelleştirme

içindeki return deyimini PostTodoItemnameof işlecini kullanacak şekilde güncelleştirin:

[HttpPost]
public async Task<ActionResult<TodoItem>> PostTodoItem(TodoItem todoItem)
{
    _context.TodoItems.Add(todoItem);
    await _context.SaveChangesAsync();

    //    return CreatedAtAction("GetTodoItem", new { id = todoItem.Id }, todoItem);
    return CreatedAtAction(nameof(GetTodoItem), new { id = todoItem.Id }, todoItem);
}

Yukarıdaki kod, özniteliği tarafından [HttpPost] gösterildiği gibi bir HTTP POST yöntemdir. yöntemi HTTP isteğinin TodoItem gövdesinden değerini alır.

Daha fazla bilgi için bkz . Http[Fiil] öznitelikleriyle öznitelik yönlendirme.

CreatedAtAction yöntemi:

  • Başarılı olursa bir HTTP 201 durum kodu döndürür. HTTP 201 , sunucuda yeni bir kaynak oluşturan yöntemin HTTP POST standart yanıtıdır.
  • Yanıta bir Konum üst bilgisi ekler. Üst bilgi, Location yeni oluşturulan yapılacaklar öğesinin URI'sini belirtir. Daha fazla bilgi için bkz . 10.2.2 201 Oluşturuldu.
  • GetTodoItem Üst bilginin URI'sini oluşturma eylemine Location başvurur. C# nameof anahtar sözcüğü, çağrıda CreatedAtAction eylem adını sabit kodlamaktan kaçınmak için kullanılır.

Test PostTodoItem

  • Uygulamayı çalıştırmak için Ctrl+F5 tuşlarına basın.

  • Swagger tarayıcı penceresinde POST /api/TodoItems'i ve ardından Deneyin'i seçin.

  • İstek gövdesi giriş penceresinde AÇI'yı güncelleştirinJS. Örneğin,

    {
  "name": "walk dog",
  "isComplete": true
}

  • Yürüt'e tıklayın

    Swagger POST

Konum üst bilgisi URI'sini test etme

Önceki POST'ta, Swagger kullanıcı arabirimi Yanıt üst bilgileri altındaki konum üst bilgisini gösterir. Örneğin, location: https://localhost:7260/api/TodoItems/1. Konum üst bilgisi, oluşturulan kaynağın URI'sini gösterir.

Konum üst bilgisini test etmek için:

  • Swagger tarayıcı penceresinde GET /api/TodoItems/{id} öğesini ve ardından Deneyin'i seçin.

  • Giriş kutusuna id yazın 1 ve Yürüt'e tıklayın.

    Swagger GET

GET yöntemlerini inceleme

İki GET uç noktası uygulanır:

  • GET /api/todoitems
  • GET /api/todoitems/{id}

Önceki bölümde yol örneği gösterildi /api/todoitems/{id} .

Başka bir yapılacaklar öğesi eklemek için POST yönergelerini izleyin ve ardından Swagger kullanarak yolu test /api/todoitems edin.

Bu uygulama bellek içi bir veritabanı kullanır. Uygulama durdurulur ve başlatılırsa, önceki GET isteği herhangi bir veri döndürmez. Hiçbir veri döndürülmezse , POST verileri uygulamaya gönderilir.

Yönlendirme ve URL yolları

özniteliği, [HttpGet] bir isteğe yanıt veren bir HTTP GET yöntemi belirtir. Her yöntemin URL yolu aşağıdaki gibi oluşturulur:

  • Denetleyicinin Route özniteliğindeki şablon dizesiyle başlayın:

    [Route("api/[controller]")]
[ApiController]
public class TodoItemsController : ControllerBase

  • değerini denetleyicinin adıyla değiştirin [controller] ; kurala göre denetleyici sınıf adı eksi "Denetleyici" sonekidir. Bu örnek için denetleyici sınıf adı TodoItemsController olduğundan denetleyici adı "TodoItems" olur. ASP.NET Core yönlendirme büyük/küçük harfe duyarsızdır.

  • Özniteliğin [HttpGet] bir yol şablonu varsa (örneğin, [HttpGet("products")]), bunu yola ekleyin. Bu örnek şablon kullanmaz. Daha fazla bilgi için bkz . Http[Fiil] öznitelikleriyle öznitelik yönlendirme.

Aşağıdaki GetTodoItem yöntemde, "{id}" yapılacaklar öğesinin benzersiz tanımlayıcısı için bir yer tutucu değişkendir. Çağrıldığında GetTodoItem URL'deki değeri "{id}" parametresindeki id yöntemine sağlanır.

[HttpGet("{id}")]
public async Task<ActionResult<TodoItem>> GetTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        return NotFound();
    }

    return todoItem;
}

Dönüş değerleri

ve yöntemlerinin GetTodoItems dönüş türü ActionResult<T> türüdür.GetTodoItem ASP.NET Core nesneyi JS otomatik olarak ON olarak serileştirir ve YANıT iletisinin JSgövdesine ON yazar. İşlenmeyen özel durum olmadığı varsayılarak, bu dönüş türünün yanıt kodu 200 Tamam'dır. İşlenmeyen özel durumlar 5xx hatalarına çevrilir.

ActionResult dönüş türleri çok çeşitli HTTP durum kodlarını temsil edebilir. Örneğin, GetTodoItem iki farklı durum değeri döndürebilir:

  • İstenen kimlikle eşleşen öğe yoksa, yöntem bir 404 durumNotFound hata kodu döndürür.
  • Aksi takdirde, yöntemi ON yanıt gövdesine sahip JS200 döndürür. Sonuç döndürerek item bir HTTP 200 yanıt döndürür.

PutTodoItem yöntemi

PutTodoItem yöntemini inceleyin:

[HttpPut("{id}")]
public async Task<IActionResult> PutTodoItem(long id, TodoItem todoItem)
{
    if (id != todoItem.Id)
    {
        return BadRequest();
    }

    _context.Entry(todoItem).State = EntityState.Modified;

    try
    {
        await _context.SaveChangesAsync();
    }
    catch (DbUpdateConcurrencyException)
    {
        if (!TodoItemExists(id))
        {
            return NotFound();
        }
        else
        {
            throw;
        }
    }

    return NoContent();
}

PutTodoItem , ile benzerdir PostTodoItem, ancak kullanır HTTP PUT. Yanıt 204 (İçerik Yok) şeklindedir. HTTP belirtimine göre, bir PUT istek istemcinin yalnızca değişiklikleri değil güncelleştirilmiş varlığın tamamını göndermesini gerektirir. Kısmi güncelleştirmeleri desteklemek için HTTP PATCH kullanın.

PutTodoItem yöntemini test etme

Bu örnek, uygulama her başlatıldığında başlatılması gereken bir bellek içi veritabanı kullanır. PUT çağrısı yapmadan önce veritabanında bir öğe olmalıdır. PUT çağrısı yapmadan önce veritabanında bir öğe olduğundan emin olmak için GET çağrısı yapın.

Swagger kullanıcı arabirimini kullanarak KIMLIĞI = 1 olan öğesini güncelleştirmek TodoItem ve adını olarak ayarlamak için "feed fish"PUT düğmesini kullanın. Yanıtın olduğuna HTTP 204 No Contentdikkat edin.

DeleteTodoItem yöntemi

DeleteTodoItem yöntemini inceleyin:

[HttpDelete("{id}")]
public async Task<IActionResult> DeleteTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);
    if (todoItem == null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(todoItem);
    await _context.SaveChangesAsync();

    return NoContent();
}

DeleteTodoItem yöntemini test etme

Kimliği = 1 olan öğesini TodoItem silmek için Swagger kullanıcı arabirimini kullanın. Yanıtın olduğuna HTTP 204 No Contentdikkat edin.

Diğer araçlarla test etme

Web API'lerini test etmek için kullanılabilecek başka birçok araç vardır, örneğin:

Daha fazla bilgi için bkz.

Fazla deftere nakil önleme

Şu anda örnek uygulama tüm TodoItem nesneyi kullanıma sunar. Üretim uygulamaları genellikle modelin bir alt kümesi kullanılarak giriş ve döndürülen verileri sınırlar. Bunun birden çok nedeni vardır ve güvenlik önemli bir nedendir. Modelin alt kümesi genellikle Veri Aktarım Nesnesi (DTO), giriş modeli veya görünüm modeli olarak adlandırılır. DTO bu öğreticide kullanılır.

DTO, şu durumlarda kullanılabilir:

  • Fazla göndermeyi engelle.
  • İstemcilerin görüntülememesi gereken özellikleri gizleyin.
  • Yük boyutunu küçültmek için bazı özellikleri atla.
  • İç içe nesneler içeren nesne grafiklerini düzleştirme. Düzleştirilmiş nesne grafikleri istemciler için daha kullanışlı olabilir.

DTO yaklaşımını göstermek için sınıfı bir gizli dizi alanı içerecek şekilde güncelleştirin TodoItem :

namespace TodoApi.Models
{
    public class TodoItem
    {
        public long Id { get; set; }
        public string? Name { get; set; }
        public bool IsComplete { get; set; }
        public string? Secret { get; set; }
    }
}

Gizli dizi alanının bu uygulamadan gizlenmesi gerekir, ancak bir yönetim uygulaması bunu kullanıma sunma seçeneğini belirleyebilir.

Gizli dizi alanını gönderip alabildiğinizi doğrulayın.

DTO modeli oluşturma:

namespace TodoApi.Models;

public class TodoItemDTO
{
    public long Id { get; set; }
    public string? Name { get; set; }
    public bool IsComplete { get; set; }
}

kullanılacak TodoItemDTOşekilde güncelleştirinTodoItemsController:

using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

namespace TodoApi.Controllers;

[Route("api/[controller]")]
[ApiController]
public class TodoItemsController : ControllerBase
{
    private readonly TodoContext _context;

    public TodoItemsController(TodoContext context)
    {
        _context = context;
    }

    // GET: api/TodoItems
    [HttpGet]
    public async Task<ActionResult<IEnumerable<TodoItemDTO>>> GetTodoItems()
    {
        return await _context.TodoItems
            .Select(x => ItemToDTO(x))
            .ToListAsync();
    }

    // GET: api/TodoItems/5
    // <snippet_GetByID>
    [HttpGet("{id}")]
    public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
    {
        var todoItem = await _context.TodoItems.FindAsync(id);

        if (todoItem == null)
        {
            return NotFound();
        }

        return ItemToDTO(todoItem);
    }
    // </snippet_GetByID>

    // PUT: api/TodoItems/5
    // To protect from overposting attacks, see https://go.microsoft.com/fwlink/?linkid=2123754
    // <snippet_Update>
    [HttpPut("{id}")]
    public async Task<IActionResult> PutTodoItem(long id, TodoItemDTO todoDTO)
    {
        if (id != todoDTO.Id)
        {
            return BadRequest();
        }

        var todoItem = await _context.TodoItems.FindAsync(id);
        if (todoItem == null)
        {
            return NotFound();
        }

        todoItem.Name = todoDTO.Name;
        todoItem.IsComplete = todoDTO.IsComplete;

        try
        {
            await _context.SaveChangesAsync();
        }
        catch (DbUpdateConcurrencyException) when (!TodoItemExists(id))
        {
            return NotFound();
        }

        return NoContent();
    }
    // </snippet_Update>

    // POST: api/TodoItems
    // To protect from overposting attacks, see https://go.microsoft.com/fwlink/?linkid=2123754
    // <snippet_Create>
    [HttpPost]
    public async Task<ActionResult<TodoItemDTO>> PostTodoItem(TodoItemDTO todoDTO)
    {
        var todoItem = new TodoItem
        {
            IsComplete = todoDTO.IsComplete,
            Name = todoDTO.Name
        };

        _context.TodoItems.Add(todoItem);
        await _context.SaveChangesAsync();

        return CreatedAtAction(
            nameof(GetTodoItem),
            new { id = todoItem.Id },
            ItemToDTO(todoItem));
    }
    // </snippet_Create>

    // DELETE: api/TodoItems/5
    [HttpDelete("{id}")]
    public async Task<IActionResult> DeleteTodoItem(long id)
    {
        var todoItem = await _context.TodoItems.FindAsync(id);
        if (todoItem == null)
        {
            return NotFound();
        }

        _context.TodoItems.Remove(todoItem);
        await _context.SaveChangesAsync();

        return NoContent();
    }

    private bool TodoItemExists(long id)
    {
        return _context.TodoItems.Any(e => e.Id == id);
    }

    private static TodoItemDTO ItemToDTO(TodoItem todoItem) =>
       new TodoItemDTO
       {
           Id = todoItem.Id,
           Name = todoItem.Name,
           IsComplete = todoItem.IsComplete
       };
}

Gizli dizi alanını gönderip alamadığınızdan emin olun.

JavaScript ile web API'sini çağırma

Bkz. Öğretici: JavaScript ile ASP.NET Core web API'si çağırma.

Web API video serisi

Bkz . Video: Başlangıç Serisi- Web API'leri.

Güvenilir web uygulaması desenleri

Sıfırdan veya mevcut bir uygulamayı yeniden düzenlemeye yönelik modern, güvenilir, performanslı, test edilebilir, uygun maliyetli ve ölçeklenebilir bir ASP.NET Core uygulaması oluşturma yönergeleri için YouTube videolarını ve makalesini for.NET Güvenilir Web Uygulaması Düzeni'ne bakın.

Web API'sine kimlik doğrulama desteği ekleme

Identity ASP.NET Core, ASP.NET Core web uygulamalarına kullanıcı arabirimi (UI) oturum açma işlevi ekler. Web API'lerinin ve SPA'larının güvenliğini sağlamak için aşağıdakilerden birini kullanın:

Duende Identity Server, ASP.NET Core için bir OpenID Connect ve OAuth 2.0 çerçevesidir. Duende Identity Server aşağıdaki güvenlik özelliklerini etkinleştirir:

  • Hizmet Olarak Kimlik Doğrulaması (AaaS)
  • Birden çok uygulama türü üzerinden çoklu oturum açma/kapatma (SSO)
  • API'ler için erişim denetimi
  • Federasyon Ağ Geçidi

Önemli

Duende Yazılımı, Duende Identity Server'ın üretim kullanımı için lisans ücreti ödemenizi gerektirebilir. Daha fazla bilgi için, bkz. ASP.NET Core 5.0'den 6.0'a geçiş.

Daha fazla bilgi için Duende Identity Server belgelerine (Duende Yazılımı web sitesi) bakın.

Azure’da Yayımlama

Azure'a dağıtma hakkında bilgi için bkz . Hızlı Başlangıç: ASP.NET web uygulaması dağıtma.

Ek kaynaklar

Bu öğretici için örnek kodu görüntüleyin veya indirin. İndirmeyi öğrenin.

Daha fazla bilgi için aşağıdaki kaynaklara bakın:

Bu öğreticide, veritabanı kullanan denetleyici tabanlı bir web API'sini oluşturmanın temelleri öğretildi. ASP.NET Core'de API oluşturmanın bir diğer yaklaşımı da en az API oluşturmaktır. En düşük API'ler ile denetleyici tabanlı API'ler arasında seçim yaparken yardım için bkz. API'lere genel bakış. En düşük API oluşturma öğreticisi için bkz. Öğretici: ASP.NET Core ile minimum API oluşturma.

Genel Bakış

Bu öğretici aşağıdaki API'yi oluşturur:

API Açıklama İstek gövdesi Yanıt gövdesi
GET /api/todoitems Tüm yapılacaklar öğelerini alma Hiçbiri Yapılacaklar öğeleri dizisi
GET /api/todoitems/{id} Kimliğine göre öğe alma Hiçbiri Yapılacaklar öğesi
POST /api/todoitems Yeni öğe ekleme Yapılacaklar öğesi Yapılacaklar öğesi
PUT /api/todoitems/{id} Var olan bir öğeyi güncelleştirme Yapılacaklar öğesi Hiçbiri
DELETE /api/todoitems/{id}     Öğeyi silme Hiçbiri Hiçbiri

Aşağıdaki diyagramda uygulamanın tasarımı gösterilmektedir.

İstemci, soldaki bir kutuyla temsil edilir. Bir istek gönderir ve uygulamadan sağ tarafta çizilmiş bir kutu olan bir yanıt alır. Uygulama kutusunun içinde, denetleyiciyi, modeli ve veri erişim katmanını temsil eden üç kutu vardır. İstek uygulamanın denetleyicisine gelir ve denetleyici ile veri erişim katmanı arasında okuma/yazma işlemleri gerçekleşir. Model serileştirilir ve yanıtta istemciye döndürülür.

Önkoşullar

Web projesi oluşturma

  • Dosyamenüsünden Yeni Proje'yi> seçin.
  • Arama kutusuna Web API'sini girin.
  • ASP.NET Core Web API'sini seçin ve İleri'yi seçin.
  • Yeni projenizi yapılandırın iletişim kutusunda projeyi TodoApi olarak adlandırın ve İleri'yi seçin.
  • Ek bilgiler iletişim kutusunda:
    • Framework'ün.NET 7.0 (veya üzeri) olduğunu onaylayın.
    • Denetleyicileri kullan (en az API kullanmak için işaretini kaldırın) onay kutusunun işaretli olduğunu onaylayın.
    • Oluştur’u seçin.

Not

.NET uygulamalarına paket ekleme hakkında yönergeler için, Paket tüketimi iş akışında (NuGet belgeleri)paketleri yüklemek ve yönetmek altındaki makalelere bakın. NuGet.org'da doğru paket sürümlerini onaylayın.

Projeyi test etme

Proje şablonu, Swagger desteğine sahip bir WeatherForecast API oluşturur.

Hata ayıklayıcı olmadan çalıştırmak için Ctrl+F5 tuşlarına basın.

Visual Studio, bir proje henüz SSL kullanmak üzere yapılandırılmamışsa aşağıdaki iletişim kutusunu görüntüler:

Bu proje SSL kullanacak şekilde yapılandırılmıştır. Tarayıcıda SSL uyarılarından kaçınmak için, IIS Express tarafından oluşturulan otomatik olarak imzalanan sertifikaya güvenmeyi seçebilirsiniz. IIS Express SSL sertifikasına güvenmek istiyor musunuz?

IIS Express SSL sertifikasına güveniyorsanız Evet'i seçin.

Aşağıdaki iletişim kutusu görüntülenir:

Güvenlik uyarısı iletişim kutusu

Geliştirme sertifikasına güvenmeyi kabul ediyorsanız Evet'i seçin.

Firefox tarayıcısına güvenme hakkında bilgi için bkz. Firefox SEC_ERROR_INADEQUATE_KEY_USAGE sertifika hatası.

Visual Studio varsayılan tarayıcıyı başlatır ve konumuna https://localhost:<port>/swagger/index.htmlgider; burada <port> rastgele seçilmiş bir bağlantı noktası numarasıdır.

Swagger sayfası /swagger/index.html görüntülenir. GET>Try it out>Execute öğesini seçin. Sayfa şu şekilde görüntülenir:

  • WeatherForecast API'sini test etmek için Curl komutu.
  • WeatherForecast API'sini test etmek için URL.
  • Yanıt kodu, gövde ve üst bilgiler.
  • Medya türlerinin ve örnek değerin ve şemanın yer aldığı bir açılan liste kutusu.

Swagger sayfası görünmüyorsa bu GitHub sorununa bakın.

Swagger, web API'leri için yararlı belgeler ve yardım sayfaları oluşturmak için kullanılır. Bu öğreticide web API'si oluşturmaya odaklanmaktadır. Swagger hakkında daha fazla bilgi için bkz. Swagger / OpenAPI ile ASP.NET Core web API'si belgeleri.

İstek URL'sini kopyalayıp tarayıcıya yapıştırın:https://localhost:<port>/weatherforecast

JSON aşağıdaki örneğe benzer şekilde döndürülür:

[
    {
        "date": "2019-07-16T19:04:05.7257911-06:00",
        "temperatureC": 52,
        "temperatureF": 125,
        "summary": "Mild"
    },
    {
        "date": "2019-07-17T19:04:05.7258461-06:00",
        "temperatureC": 36,
        "temperatureF": 96,
        "summary": "Warm"
    },
    {
        "date": "2019-07-18T19:04:05.7258467-06:00",
        "temperatureC": 39,
        "temperatureF": 102,
        "summary": "Cool"
    },
    {
        "date": "2019-07-19T19:04:05.7258471-06:00",
        "temperatureC": 10,
        "temperatureF": 49,
        "summary": "Bracing"
    },
    {
        "date": "2019-07-20T19:04:05.7258474-06:00",
        "temperatureC": -1,
        "temperatureF": 31,
        "summary": "Chilly"
    }
]

Model sınıfı ekleme

Model, uygulamanın yönettiği verileri temsil eden bir sınıf kümesidir. Bu uygulamanın modeli sınıfıdır TodoItem .

  • Çözüm Gezgini'da projeye sağ tıklayın. Yeni Klasör Ekle'yi> seçin. Klasörü Modelsolarak adlandırın.
  • Klasöre sağ tıklayın veSınıfEkle'yi>Models seçin. Sınıfı TodoItem olarak adlandırın ve Ekle'yi seçin.
  • Şablon kodunu aşağıdakilerle değiştirin:
namespace TodoApi.Models;

public class TodoItem
{
    public long Id { get; set; }
    public string? Name { get; set; }
    public bool IsComplete { get; set; }
}

özelliği, Id ilişkisel veritabanında benzersiz anahtar olarak işlev görür.

Model sınıfları projede herhangi bir yere gidebilir, ancak Models klasör kural tarafından kullanılır.

Veritabanı bağlamı ekleme

Veritabanı bağlamı, bir veri modeli için Entity Framework işlevselliğini koordine eden ana sınıftır. Bu sınıf, sınıfından Microsoft.EntityFrameworkCore.DbContext türetilerek oluşturulur.

NuGet paketlerini ekleme

  • Araçlar menüsünde NuGet Paket Yöneticisi > Çözüm için NuGet Paketlerini Yönet'i seçin.
  • Gözat sekmesini seçin ve arama kutusuna girinMicrosoft.EntityFrameworkCore.InMemory.
  • Sol bölmede öğesini seçin Microsoft.EntityFrameworkCore.InMemory .
  • Sağ bölmede Proje onay kutusunu ve ardından Yükle'yi seçin.

TodoContext veritabanı bağlamını ekleme

  • Klasöre sağ tıklayın veSınıfEkle'yi>Models seçin. Sınıfı TodoContext olarak adlandırın ve Ekle'ye tıklayın.

  • Aşağıdaki kodu girin:

    using Microsoft.EntityFrameworkCore;

namespace TodoApi.Models;

public class TodoContext : DbContext
{
    public TodoContext(DbContextOptions<TodoContext> options)
        : base(options)
    {
    }

    public DbSet<TodoItem> TodoItems { get; set; } = null!;
}

Veritabanı bağlamını kaydetme

ASP.NET Core'de, VERITABANı bağlamı gibi hizmetlerin bağımlılık ekleme (DI) kapsayıcısıyla kaydedilmesi gerekir. Kapsayıcı, denetleyicilere hizmeti sağlar.

Aşağıdaki vurgulanmış kodla güncelleştirin Program.cs :

using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddDbContext<TodoContext>(opt =>
    opt.UseInMemoryDatabase("TodoList"));
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Yukarıdaki kod:

  • Yönergeleri ekler using .
  • VERITABANı bağlamını DI kapsayıcısına ekler.
  • Veritabanı bağlamın bellek içi veritabanı kullanacağını belirtir.

Denetleyicinin iskelesi

  • Denetleyiciler klasörüne sağ tıklayın.

  • Yeni İskeleli Öğe Ekle'yi> seçin.

  • Entity Framework kullanarak eylemleri olan API Denetleyicisi'ni ve ardından Ekle'yi seçin.

  • Entity Framework kullanarak EYLEMLERle API Denetleyicisi Ekle iletişim kutusunda:

    • Model sınıfındaTodoItem (TodoApi.Models) öğesini seçin.
    • Veri bağlamı sınıfındaTodoContext (TodoApi.Models) öğesini seçin.
    • Add (Ekle) seçeneğini belirleyin.

    yapı iskelesi işlemi başarısız olursa, yapı iskelesi oluşturmayı ikinci kez denemek için Ekle'yi seçin.

Oluşturulan kod:

  • Sınıfı özniteliğiyle [ApiController] işaretler. Bu öznitelik, denetleyicinin web API isteklerine yanıt verdiğini gösterir. Özniteliğin etkinleştirilen belirli davranışlar hakkında bilgi için bkz. ASP.NET Core ile web API'leri oluşturma.
  • Veritabanı bağlamını (TodoContext) denetleyiciye eklemek için DI kullanır. Veritabanı bağlamı, denetleyicideki CRUD yöntemlerinin her birinde kullanılır.

Aşağıdakiler için ASP.NET Core şablonları:

  • Görünümlere sahip denetleyiciler yol şablonuna dahildir [action] .
  • API denetleyicileri yol şablonuna dahil [action] değildir.

[action] Belirteç yol şablonunda olmadığında, eylem adı (yöntem adı) uç noktaya dahil değildir. Başka bir ifadeyle, eylemin ilişkili yöntem adı eşleşen yolda kullanılmaz.

PostTodoItem oluşturma yöntemini güncelleştirme

içindeki return deyimini PostTodoItemnameof işlecini kullanacak şekilde güncelleştirin:

[HttpPost]
public async Task<ActionResult<TodoItem>> PostTodoItem(TodoItem todoItem)
{
    _context.TodoItems.Add(todoItem);
    await _context.SaveChangesAsync();

    //    return CreatedAtAction("GetTodoItem", new { id = todoItem.Id }, todoItem);
    return CreatedAtAction(nameof(GetTodoItem), new { id = todoItem.Id }, todoItem);
}

Yukarıdaki kod, özniteliğinde [HttpPost] belirtildiği gibi bir HTTP POST yöntemdir. yöntemi, DEĞERINI HTTP isteğinin gövdesinden alır TodoItem .

Daha fazla bilgi için bkz . Http[Fiil] öznitelikleriyle öznitelik yönlendirme.

CreatedAtAction yöntemi:

  • Başarılı olursa bir HTTP 201 durum kodu döndürür. HTTP 201 , sunucuda yeni bir kaynak oluşturan yöntemin HTTP POST standart yanıtıdır.
  • Yanıta bir Konum üst bilgisi ekler. Üst bilgi, Location yeni oluşturulan yapılacaklar öğesinin URI'sini belirtir. Daha fazla bilgi için bkz. 10.2.2 201 Oluşturuldu.
  • GetTodoItem Üst bilginin URI'sini Location oluşturma eylemine başvurur. C# nameof anahtar sözcüğü, çağrıda CreatedAtAction eylem adını sabit kodlamaktan kaçınmak için kullanılır.

Test PostTodoItem

  • Uygulamayı çalıştırmak için Ctrl+F5 tuşlarına basın.

  • Swagger tarayıcı penceresinde POST /api/TodoItems öğesini ve ardından Deneyin'i seçin.

  • İstek gövdesi giriş penceresinde AÇI'yı güncelleştirinJS. Örneğin,

    {
  "name": "walk dog",
  "isComplete": true
}

  • Yürüt'e tıklayın

    Swagger POST

Konum üst bilgisi URI'sini test edin

Önceki POST'ta, Swagger kullanıcı arabirimi Yanıt üst bilgileri altındaki konum üst bilgisini gösterir. Örneğin, location: https://localhost:7260/api/TodoItems/1. Konum üst bilgisi, oluşturulan kaynağın URI'sini gösterir.

Konum üst bilgisini test etmek için:

  • Swagger tarayıcı penceresinde GET /api/TodoItems/{id} öğesini ve ardından Deneyin'i seçin.

  • Giriş kutusuna id girin 1 ve Yürüt'e tıklayın.

    Swagger GET

GET yöntemlerini inceleme

İki GET uç noktası uygulanır:

  • GET /api/todoitems
  • GET /api/todoitems/{id}

Önceki bölümde yolun bir örneği gösterildi /api/todoitems/{id} .

Başka bir yapılacaklar öğesi eklemek için POST yönergelerini izleyin ve ardından Swagger kullanarak yolu test /api/todoitems edin.

Bu uygulama bellek içi bir veritabanı kullanır. Uygulama durdurulup başlatılırsa, önceki GET isteği herhangi bir veri döndürmez. Hiçbir veri döndürülmezse , uygulamaya POST verileri gönderin.

Yönlendirme ve URL yolları

[HttpGet] özniteliği, bir isteğe yanıt veren bir HTTP GET yöntemi belirtir. Her yöntemin URL yolu aşağıdaki gibi oluşturulur:

  • Denetleyicinin Route özniteliğindeki şablon dizesiyle başlayın:

    [Route("api/[controller]")]
[ApiController]
public class TodoItemsController : ControllerBase

  • değerini denetleyicinin adıyla değiştirin [controller] ; kural gereği denetleyici sınıf adı eksi "Denetleyici" sonekidir. Bu örnek için denetleyici sınıf adı TodoItemsController olduğundan denetleyici adı "TodoItems" olur. ASP.NET Core yönlendirme büyük/küçük harfe duyarsızdır.

  • Özniteliğin [HttpGet] bir yol şablonu varsa (örneğin, [HttpGet("products")]), bunu yola ekleyin. Bu örnek şablon kullanmaz. Daha fazla bilgi için bkz . Http[Fiil] öznitelikleriyle öznitelik yönlendirme.

Aşağıdaki GetTodoItem yöntemde, "{id}" yapılacaklar öğesinin benzersiz tanımlayıcısı için bir yer tutucu değişkendir. çağrıldığında GetTodoItem URL'deki değeri "{id}" parametresindeki id yöntemine sağlanır.

[HttpGet("{id}")]
public async Task<ActionResult<TodoItem>> GetTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        return NotFound();
    }

    return todoItem;
}

Dönüş değerleri

ve yöntemlerinin GetTodoItems dönüş türü ActionResult<T> türüdür.GetTodoItem ASP.NET Core, nesneyi JS otomatik olarak ON olarak seri hale getirerek JSyanıt iletisinin gövdesine ON yazar. İşlenmeyen özel durum olmadığı varsayılarak, bu dönüş türünün yanıt kodu 200 Tamam'dır. İşlenmeyen özel durumlar 5xx hatalarına dönüştürülür.

ActionResult dönüş türleri çok çeşitli HTTP durum kodlarını temsil edebilir. Örneğin, GetTodoItem iki farklı durum değeri döndürebilir:

  • İstenen kimlikle eşleşen öğe yoksa, yöntem bir 404 durumNotFound hata kodu döndürür.
  • Aksi takdirde, yöntem ON yanıt gövdesine sahip JS200 değerini döndürür. Sonuçları item yanıt olarak HTTP 200 döndürme.

PutTodoItem yöntemi

PutTodoItem yöntemini inceleyin:

[HttpPut("{id}")]
public async Task<IActionResult> PutTodoItem(long id, TodoItem todoItem)
{
    if (id != todoItem.Id)
    {
        return BadRequest();
    }

    _context.Entry(todoItem).State = EntityState.Modified;

    try
    {
        await _context.SaveChangesAsync();
    }
    catch (DbUpdateConcurrencyException)
    {
        if (!TodoItemExists(id))
        {
            return NotFound();
        }
        else
        {
            throw;
        }
    }

    return NoContent();
}

PutTodoItem , ile benzerdir PostTodoItem, ancak kullanır HTTP PUT. Yanıt 204 (İçerik Yok) şeklindedir. HTTP belirtimine göre, bir PUT istek istemcinin yalnızca değişiklikleri değil güncelleştirilmiş varlığın tamamını göndermesini gerektirir. Kısmi güncelleştirmeleri desteklemek için HTTP PATCH kullanın.

PutTodoItem yöntemini test edin

Bu örnek, uygulama her başlatıldığında başlatılması gereken bir bellek içi veritabanı kullanır. PUT çağrısı yapmadan önce veritabanında bir öğe olmalıdır. PUT çağrısı yapmadan önce veritabanında bir öğe olduğundan emin olmak için GET çağrısı yapın.

Swagger kullanıcı arabirimini kullanarak PUT düğmesini kullanarak Kimliği = 1 olan öğesini güncelleştirin TodoItem ve adını olarak "feed fish"ayarlayın. Yanıtın olduğuna HTTP 204 No Contentdikkat edin.

DeleteTodoItem yöntemi

DeleteTodoItem yöntemini inceleyin:

[HttpDelete("{id}")]
public async Task<IActionResult> DeleteTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);
    if (todoItem == null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(todoItem);
    await _context.SaveChangesAsync();

    return NoContent();
}

DeleteTodoItem yöntemini test edin

Kimliği = 1 olan öğesini TodoItem silmek için Swagger kullanıcı arabirimini kullanın. Yanıtın olduğuna HTTP 204 No Contentdikkat edin.

http-repl, Postman veya curl ile test edin

http-repl, Postman ve curl genellikle API'leri test etmek için kullanılır. Swagger gönderdiği komutu kullanır curl ve gösterir curl .

Bu araçlarla ilgili yönergeler için aşağıdaki bağlantılara bakın:

hakkında http-repldaha fazla bilgi için bkz . HttpRepl ile web API'lerini test edin.

Fazla göndermeyi engelle

Şu anda örnek uygulama tüm TodoItem nesneyi kullanıma sunar. Üretim uygulamaları genellikle modelin bir alt kümesi kullanılarak giriş ve döndürülen verileri sınırlandırır. Bunun arkasında birden çok neden vardır ve güvenlik önemli bir nedendir. Modelin alt kümesi genellikle Veri Aktarım Nesnesi (DTO), giriş modeli veya görünüm modeli olarak adlandırılır. DTO bu öğreticide kullanılır.

DTO, şu durumlarda kullanılabilir:

  • Fazla göndermeyi engelle.
  • İstemcilerin görüntülememesi gereken özellikleri gizleyin.
  • Yük boyutunu azaltmak için bazı özellikleri atla.
  • İç içe nesneler içeren nesne grafiklerini düzleştirme. Düzleştirilmiş nesne grafikleri istemciler için daha kullanışlı olabilir.

DTO yaklaşımını göstermek için sınıfını bir gizli dizi alanı içerecek şekilde güncelleştirin TodoItem :

namespace TodoApi.Models
{
    public class TodoItem
    {
        public long Id { get; set; }
        public string? Name { get; set; }
        public bool IsComplete { get; set; }
        public string? Secret { get; set; }
    }
}

Gizli dizi alanının bu uygulamadan gizlenmesi gerekir, ancak bir yönetim uygulaması bunu kullanıma sunma seçeneğini belirleyebilir.

Gizli dizi alanını gönderip alabildiğinizi doğrulayın.

DTO modeli oluşturma:

namespace TodoApi.Models;

public class TodoItemDTO
{
    public long Id { get; set; }
    public string? Name { get; set; }
    public bool IsComplete { get; set; }
}

uygulamasını kullanacak TodoItemDTOşekilde güncelleştirinTodoItemsController:

using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

namespace TodoApi.Controllers;

[Route("api/[controller]")]
[ApiController]
public class TodoItemsController : ControllerBase
{
    private readonly TodoContext _context;

    public TodoItemsController(TodoContext context)
    {
        _context = context;
    }

    // GET: api/TodoItems
    [HttpGet]
    public async Task<ActionResult<IEnumerable<TodoItemDTO>>> GetTodoItems()
    {
        return await _context.TodoItems
            .Select(x => ItemToDTO(x))
            .ToListAsync();
    }

    // GET: api/TodoItems/5
    // <snippet_GetByID>
    [HttpGet("{id}")]
    public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
    {
        var todoItem = await _context.TodoItems.FindAsync(id);

        if (todoItem == null)
        {
            return NotFound();
        }

        return ItemToDTO(todoItem);
    }
    // </snippet_GetByID>

    // PUT: api/TodoItems/5
    // To protect from overposting attacks, see https://go.microsoft.com/fwlink/?linkid=2123754
    // <snippet_Update>
    [HttpPut("{id}")]
    public async Task<IActionResult> PutTodoItem(long id, TodoItemDTO todoDTO)
    {
        if (id != todoDTO.Id)
        {
            return BadRequest();
        }

        var todoItem = await _context.TodoItems.FindAsync(id);
        if (todoItem == null)
        {
            return NotFound();
        }

        todoItem.Name = todoDTO.Name;
        todoItem.IsComplete = todoDTO.IsComplete;

        try
        {
            await _context.SaveChangesAsync();
        }
        catch (DbUpdateConcurrencyException) when (!TodoItemExists(id))
        {
            return NotFound();
        }

        return NoContent();
    }
    // </snippet_Update>

    // POST: api/TodoItems
    // To protect from overposting attacks, see https://go.microsoft.com/fwlink/?linkid=2123754
    // <snippet_Create>
    [HttpPost]
    public async Task<ActionResult<TodoItemDTO>> PostTodoItem(TodoItemDTO todoDTO)
    {
        var todoItem = new TodoItem
        {
            IsComplete = todoDTO.IsComplete,
            Name = todoDTO.Name
        };

        _context.TodoItems.Add(todoItem);
        await _context.SaveChangesAsync();

        return CreatedAtAction(
            nameof(GetTodoItem),
            new { id = todoItem.Id },
            ItemToDTO(todoItem));
    }
    // </snippet_Create>

    // DELETE: api/TodoItems/5
    [HttpDelete("{id}")]
    public async Task<IActionResult> DeleteTodoItem(long id)
    {
        var todoItem = await _context.TodoItems.FindAsync(id);
        if (todoItem == null)
        {
            return NotFound();
        }

        _context.TodoItems.Remove(todoItem);
        await _context.SaveChangesAsync();

        return NoContent();
    }

    private bool TodoItemExists(long id)
    {
        return _context.TodoItems.Any(e => e.Id == id);
    }

    private static TodoItemDTO ItemToDTO(TodoItem todoItem) =>
       new TodoItemDTO
       {
           Id = todoItem.Id,
           Name = todoItem.Name,
           IsComplete = todoItem.IsComplete
       };
}

Gizli dizi alanını gönderip alamadığınızdan emin olun.

JavaScript ile web API'sini çağırma

Bkz. Öğretici: JavaScript ile ASP.NET Core web API'lerini çağırma.

Web API video serisi

Bkz . Video: Başlangıç Serisi: Web API'leri.

Güvenilir web uygulaması desenleri

İster sıfırdan ister mevcut bir uygulamayı yeniden düzenleme olsun, modern, güvenilir, performanslı, test edilebilir, uygun maliyetli ve ölçeklenebilir bir ASP.NET Core uygulaması oluşturma yönergeleri için YouTube videolarını ve makalesini for.NET Güvenilir Web Uygulaması Düzeni'ne bakın.

Web API'sine kimlik doğrulaması desteği ekleme

Identity ASP.NET Core, ASP.NET Core web uygulamalarına kullanıcı arabirimi (UI) oturum açma işlevselliği ekler. Web API'lerinin ve SPA'larının güvenliğini sağlamak için aşağıdakilerden birini kullanın:

Duende Identity Server, ASP.NET Core için bir OpenID Connect ve OAuth 2.0 çerçevesidir. Duende Identity Server aşağıdaki güvenlik özelliklerini etkinleştirir:

  • Hizmet Olarak Kimlik Doğrulaması (AaaS)
  • Birden çok uygulama türü üzerinde çoklu oturum açma/kapatma (SSO)
  • API'ler için erişim denetimi
  • Federasyon Ağ Geçidi

Önemli

Duende Yazılımı, Duende Identity Server'ın üretim kullanımı için lisans ücreti ödemenizi gerektirebilir. Daha fazla bilgi için, bkz. ASP.NET Core 5.0'den 6.0'a geçiş.

Daha fazla bilgi için Duende Identity Server belgelerine (Duende Yazılımı web sitesi) bakın.

Azure’da Yayımlama

Azure'a dağıtma hakkında bilgi için bkz . Hızlı Başlangıç: ASP.NET web uygulaması dağıtma.

Ek kaynaklar

Bu öğretici için örnek kodu görüntüleyin veya indirin. İndirmeyi öğrenin.

Daha fazla bilgi için aşağıdaki kaynaklara bakın:

Bu öğreticide, veritabanı kullanan denetleyici tabanlı bir web API'sinin temelleri öğretildi. ASP.NET Core'de API oluşturmaya yönelik bir diğer yaklaşım da en az API oluşturmaktır. Minimum API'ler ile denetleyici tabanlı API'ler arasında seçim yaparken yardım için bkz. API'lere genel bakış. En az API oluşturma öğreticisi için bkz. Öğretici: ASP.NET Core ile minimum API oluşturma.

Bu öğreticide şunların nasıl yapıldığını öğreneceksiniz:

  • Web API'si projesi oluşturma.
  • Model sınıfı ve veritabanı bağlamı ekleyin.
  • CRUD yöntemleriyle bir denetleyicinin iskelesi oluşturun.
  • Yönlendirmeyi, URL yollarını ve dönüş değerlerini yapılandırın.
  • http-repl ile web API'sini çağırın.

Sonunda, bir veritabanında depolanan "yapılacaklar" öğelerini yönetebilen bir web API'niz vardır.

Genel Bakış

Bu öğretici aşağıdaki API'yi oluşturur:

API Açıklama İstek gövdesi Yanıt gövdesi
GET /api/todoitems Tüm yapılacaklar öğelerini alma Hiçbiri Yapılacaklar öğeleri dizisi
GET /api/todoitems/{id} Öğeyi kimliğine göre alma Hiçbiri Yapılacaklar öğesi
POST /api/todoitems Yeni öğe ekleme Yapılacaklar öğesi Yapılacaklar öğesi
PUT /api/todoitems/{id} Var olan bir öğeyi güncelleştirme Yapılacaklar öğesi Hiçbiri
DELETE /api/todoitems/{id}     Öğeyi silme Hiçbiri Hiçbiri

Aşağıdaki diyagramda uygulamanın tasarımı gösterilmektedir.

İstemci, soldaki bir kutuyla temsil edilir. Bir istek gönderir ve uygulamadan sağ tarafta çizilmiş bir kutu olan bir yanıt alır. Uygulama kutusunun içinde, denetleyiciyi, modeli ve veri erişim katmanını temsil eden üç kutu vardır. İstek uygulamanın denetleyicisine gelir ve denetleyici ile veri erişim katmanı arasında okuma/yazma işlemleri gerçekleşir. Model serileştirilir ve yanıtta istemciye döndürülür.

Önkoşullar

Web projesi oluşturma

  • Dosyamenüsünden Yeni Proje'yi> seçin.
  • Arama kutusuna Web API'sini girin.
  • ASP.NET Core Web API'sini seçin ve İleri'yi seçin.
  • Yeni projenizi yapılandırın iletişim kutusunda projeyi TodoApi olarak adlandırın ve İleri'yi seçin.
  • Ek bilgiler iletişim kutusunda:
    • Framework'ün.NET 6.0 (Uzun süreli destek) olduğunu onaylayın.
    • Denetleyicileri kullan (en az API kullanmak için işaretini kaldırın) onay kutusunun işaretli olduğunu onaylayın.
    • Oluştur’u seçin.

Not

.NET uygulamalarına paket ekleme hakkında yönergeler için, Paket tüketimi iş akışında (NuGet belgeleri)paketleri yüklemek ve yönetmek altındaki makalelere bakın. NuGet.org'da doğru paket sürümlerini onaylayın.

Projeyi test etme

Proje şablonu, Swagger desteğine sahip bir WeatherForecast API oluşturur.

Hata ayıklayıcı olmadan çalıştırmak için Ctrl+F5 tuşlarına basın.

Proje henüz SSL kullanacak şekilde yapılandırılmadığında Visual Studio aşağıdaki iletişim kutusunu görüntüler:

Bu proje SSL kullanacak şekilde yapılandırıldı. Tarayıcıda SSL uyarılarından kaçınmak için, IIS Express tarafından oluşturulan otomatik olarak imzalanan sertifikaya güvenmeyi seçebilirsiniz. IIS Express SSL sertifikasına güvenmek istiyor musunuz?

IIS Express SSL sertifikasına güveniyorsanız Evet'i seçin.

Aşağıdaki iletişim kutusu görüntülenir:

Güvenlik uyarısı iletişim kutusu

Geliştirme sertifikasına güvenmeyi kabul ediyorsanız Evet'i seçin.

Firefox tarayıcısına güvenme hakkında bilgi için bkz. Firefox SEC_ERROR_INADEQUATE_KEY_USAGE sertifika hatası.

Visual Studio varsayılan tarayıcıyı başlatır ve rastgele seçilen bağlantı noktası numarası olan <port> konumuna https://localhost:<port>/swagger/index.htmlgider.

Swagger sayfası /swagger/index.html görüntülenir. GET>Try it try it out>Execute öğesini seçin. Sayfa şu şekilde görüntülenir:

  • WeatherForecast API'sini test etmek için Curl komutu.
  • WeatherForecast API'sini test etmek için URL.
  • Yanıt kodu, gövde ve üst bilgiler.
  • Medya türlerinin, örnek değerin ve şemanın yer aldığı bir açılan liste kutusu.

Swagger sayfası görünmüyorsa bu GitHub sorununa bakın.

Swagger, web API'leri için yararlı belgeler ve yardım sayfaları oluşturmak için kullanılır. Bu öğreticide web API'si oluşturmaya odaklanmaktadır. Swagger hakkında daha fazla bilgi için bkz. Swagger / OpenAPI ile ASP.NET Core web API'si belgeleri.

İstek URL'sini kopyalayıp tarayıcıya yapıştırın:https://localhost:<port>/weatherforecast

JSON aşağıdaki örneğe benzer şekilde döndürülür:

[
    {
        "date": "2019-07-16T19:04:05.7257911-06:00",
        "temperatureC": 52,
        "temperatureF": 125,
        "summary": "Mild"
    },
    {
        "date": "2019-07-17T19:04:05.7258461-06:00",
        "temperatureC": 36,
        "temperatureF": 96,
        "summary": "Warm"
    },
    {
        "date": "2019-07-18T19:04:05.7258467-06:00",
        "temperatureC": 39,
        "temperatureF": 102,
        "summary": "Cool"
    },
    {
        "date": "2019-07-19T19:04:05.7258471-06:00",
        "temperatureC": 10,
        "temperatureF": 49,
        "summary": "Bracing"
    },
    {
        "date": "2019-07-20T19:04:05.7258474-06:00",
        "temperatureC": -1,
        "temperatureF": 31,
        "summary": "Chilly"
    }
]

launchUrl güncelleştirme

Properties\launchSettings.json içinde, 'den '"swagger"a "api/todoitems"güncelleştirinlaunchUrl:

"launchUrl": "api/todoitems",

Swagger kaldırılacağından, yukarıdaki işaretleme, başlatılan URL'yi aşağıdaki bölümlerde eklenen denetleyicinin GET yöntemine değiştirir.

Model sınıfı ekleme

Model, uygulamanın yönettiği verileri temsil eden bir sınıf kümesidir. Bu uygulamanın modeli tek TodoItem bir sınıftır.

  • Çözüm Gezgini'da projeye sağ tıklayın. Yeni Klasör Ekle'yi> seçin. klasörünü Modelsadlandırın.

  • Klasöre sağ tıklayın veSınıfEkle'yi>Models seçin. Sınıfı TodoItem olarak adlandırın ve Ekle'yi seçin.

  • Şablon kodunu aşağıdakilerle değiştirin:

namespace TodoApi.Models
{
    public class TodoItem
    {
        public long Id { get; set; }
        public string? Name { get; set; }
        public bool IsComplete { get; set; }
    }
}

özelliği, Id ilişkisel veritabanında benzersiz anahtar olarak işlev görür.

Model sınıfları projede herhangi bir yere gidebilir, ancak Models klasör kural tarafından kullanılır.

Veritabanı bağlamı ekleme

Veritabanı bağlamı, bir veri modeli için Entity Framework işlevselliğini koordine eden ana sınıftır. Bu sınıf, sınıfından Microsoft.EntityFrameworkCore.DbContext türetilerek oluşturulur.

NuGet paketlerini ekleme

  • Araçlarmenüsünden NuGet Paket Yöneticisi > Çözüm için NuGet Paketlerini Yönet'i seçin.
  • Gözat sekmesini seçin ve arama kutusuna girinMicrosoft.EntityFrameworkCore.InMemory.
  • Sol bölmede öğesini seçin Microsoft.EntityFrameworkCore.InMemory .
  • Sağ bölmede Proje onay kutusunu ve ardından Yükle'yi seçin.

TodoContext veritabanı bağlamını ekleme

  • Klasöre sağ tıklayın veSınıfEkle'yi>Models seçin. Sınıfı TodoContext olarak adlandırın ve Ekle'ye tıklayın.

  • Aşağıdaki kodu girin:

    using Microsoft.EntityFrameworkCore;
using System.Diagnostics.CodeAnalysis;

namespace TodoApi.Models
{
    public class TodoContext : DbContext
    {
        public TodoContext(DbContextOptions<TodoContext> options)
            : base(options)
        {
        }

        public DbSet<TodoItem> TodoItems { get; set; } = null!;
    }
}

Veritabanı bağlamını kaydetme

ASP.NET Core'de, VERITABANı bağlamı gibi hizmetlerin bağımlılık ekleme (DI) kapsayıcısıyla kaydedilmesi gerekir. Kapsayıcı, denetleyicilere hizmeti sağlar.

Aşağıdaki kodla güncelleştirin Program.cs :

using Microsoft.EntityFrameworkCore;
using TodoApi.Models;


var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

builder.Services.AddControllers();
builder.Services.AddDbContext<TodoContext>(opt =>
    opt.UseInMemoryDatabase("TodoList"));
//builder.Services.AddSwaggerGen(c =>
//{
//    c.SwaggerDoc("v1", new() { Title = "TodoApi", Version = "v1" });
//});

var app = builder.Build();

// Configure the HTTP request pipeline.
if (builder.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
    //app.UseSwagger();
    //app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "TodoApi v1"));
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Yukarıdaki kod:

  • Swagger çağrılarını kaldırır.
  • Kullanılmayan using yönergeleri kaldırır.
  • VERITABANı bağlamını DI kapsayıcısına ekler.
  • Veritabanı bağlamında bellek içi veritabanı kullanılacağını belirtir.

Bir denetleyicinin iskelesi

  • Denetleyiciler klasörüne sağ tıklayın.

  • Yeni İskeleli Öğe Ekle'yi> seçin.

  • Entity Framework kullanarak eylemlerle API Denetleyicisi'ni ve ardından Ekle'yi seçin.

  • Eylemlerle API Denetleyicisi Ekle iletişim kutusunda Entity Framework kullanarak:

    • Model sınıfındaTodoItem (TodoApi.Models) öğesini seçin.
    • Veri bağlamı sınıfındaTodoContext (TodoApi.Models) öğesini seçin.
    • Add (Ekle) seçeneğini belirleyin.

    yapı iskelesi işlemi başarısız olursa, yapı iskelesini ikinci kez denemek için Ekle'yi seçin.

Oluşturulan kod:

  • sınıfını özniteliğiyle [ApiController] işaretler. Bu öznitelik, denetleyicinin web API'sinin isteklerine yanıt verdiğini gösterir. Özniteliğin etkinleştirilen belirli davranışlar hakkında bilgi için bkz. ASP.NET Core ile web API'leri oluşturma.
  • Veritabanı bağlamını (TodoContext) denetleyiciye eklemek için DI kullanır. Veritabanı bağlamı, denetleyicideki CRUD yöntemlerinin her birinde kullanılır.

aşağıdakiler için ASP.NET Core şablonları:

  • Görünümlere sahip denetleyiciler yol şablonuna dahildir [action] .
  • API denetleyicileri yol şablonuna dahil [action] değildir.

[action] Belirteç yol şablonunda olmadığında, eylem adı yolun dışında tutulur. Diğer bir ifadeyle, eylemin ilişkili yöntem adı eşleşen yolda kullanılmaz.

PostTodoItem oluşturma yöntemini güncelleştirme

içindeki return deyimini PostTodoItemnameof işlecini kullanacak şekilde güncelleştirin:

[HttpPost]
public async Task<ActionResult<TodoItem>> PostTodoItem(TodoItem todoItem)
{
    _context.TodoItems.Add(todoItem);
    await _context.SaveChangesAsync();

    //return CreatedAtAction("GetTodoItem", new { id = todoItem.Id }, todoItem);
    return CreatedAtAction(nameof(GetTodoItem), new { id = todoItem.Id }, todoItem);
}

Yukarıdaki kod, özniteliği tarafından [HttpPost] gösterildiği gibi bir HTTP POST yöntemidir. yöntemi, YAPıLACAKlar öğesinin değerini HTTP isteğinin gövdesinden alır.

Daha fazla bilgi için bkz . Http[Fiil] öznitelikleriyle öznitelik yönlendirme.

CreatedAtAction yöntemi:

  • Başarılı olursa bir HTTP 201 durum kodu döndürür. HTTP 201, sunucuda yeni bir kaynak oluşturan bir HTTP POST yöntemi için standart yanıttır.
  • Yanıta bir Konum üst bilgisi ekler. Üst bilgi, Location yeni oluşturulan yapılacaklar öğesinin URI'sini belirtir. Daha fazla bilgi için bkz . 10.2.2 201 Oluşturuldu.
  • GetTodoItem Üst bilginin URI'sini oluşturma eylemine Location başvurur. C# nameof anahtar sözcüğü, çağrıda CreatedAtAction eylem adını sabit kodlamaktan kaçınmak için kullanılır.

http-repl yükleme

Bu öğreticide web API'sini test etmek için http-repl kullanılır.

  • Komut isteminde aşağıdaki komutu çalıştırın:

    dotnet tool install -g Microsoft.dotnet-httprepl

  • .NET 6.0 SDK'nız veya çalışma zamanı yüklü değilse.NET 6.0 çalışma zamanını yükleyin.

Test PostTodoItem

  • Uygulamayı çalıştırmak için Ctrl+F5 tuşlarına basın.

  • Yeni bir terminal penceresi açın ve aşağıdaki komutları çalıştırın. Uygulamanız farklı bir bağlantı noktası numarası kullanıyorsa httprepl komutundaki 5001 değerini bağlantı noktası numaranızla değiştirin.

    httprepl https://localhost:5001/api/todoitems
post -h Content-Type=application/json -c "{"name":"walk dog","isComplete":true}"

    Aşağıda komutun çıktısının bir örneğini inceleyebilirsiniz:

    HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Date: Tue, 07 Sep 2021 20:39:47 GMT
Location: https://localhost:5001/api/TodoItems/1
Server: Kestrel
Transfer-Encoding: chunked

{
  "id": 1,
  "name": "walk dog",
  "isComplete": true
}

Konum üst bilgisi URI'sini test etme

Konum üst bilgisini test etmek için kopyalayıp bir httprepl get komutuna yapıştırın.

Aşağıdaki örnekte hala bir httprepl oturumunda olduğunuz varsayılır. Önceki httprepl oturumunu sona erdirdiyseniz aşağıdaki komutlarda öğesini ile httprepl değiştirinconnect:

connect https://localhost:5001/api/todoitems/1
get

Aşağıda komutun çıktısının bir örneğini inceleyebilirsiniz:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Tue, 07 Sep 2021 20:48:10 GMT
Server: Kestrel
Transfer-Encoding: chunked

{
  "id": 1,
  "name": "walk dog",
  "isComplete": true
}

GET yöntemlerini inceleme

İki GET uç noktası uygulanır:

  • GET /api/todoitems
  • GET /api/todoitems/{id}

Yolun bir örneğini /api/todoitems/{id} gördünüz. Yolu test edin /api/todoitems :

connect https://localhost:5001/api/todoitems
get

Aşağıda komutun çıktısının bir örneğini inceleyebilirsiniz:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Tue, 07 Sep 2021 20:59:21 GMT
Server: Kestrel
Transfer-Encoding: chunked

[
  {
    "id": 1,
    "name": "walk dog",
    "isComplete": true
  }
]

Bu kez, JSon döndürülen bir öğe dizisidir.

Bu uygulama bellek içi bir veritabanı kullanır. Uygulama durdurulur ve başlatılırsa, önceki GET isteği herhangi bir veri döndürmez. Hiçbir veri döndürülmezse , POST verileri uygulamaya gönderilir.

Yönlendirme ve URL yolları

özniteliği, [HttpGet] HTTP GET isteğine yanıt veren bir yöntemi belirtir. Her yöntemin URL yolu aşağıdaki gibi oluşturulur:

  • Denetleyicinin Route özniteliğindeki şablon dizesiyle başlayın:

    [Route("api/[controller]")]
[ApiController]
public class TodoItemsController : ControllerBase

  • değerini denetleyicinin adıyla değiştirin [controller] ; kurala göre denetleyici sınıf adı eksi "Denetleyici" sonekidir. Bu örnek için denetleyici sınıf adı TodoItemsController olduğundan denetleyici adı "TodoItems" olur. ASP.NET Core yönlendirme büyük/küçük harfe duyarsızdır.

  • Özniteliğin [HttpGet] bir yol şablonu varsa (örneğin, [HttpGet("products")]), bunu yola ekleyin. Bu örnek şablon kullanmaz. Daha fazla bilgi için bkz . Http[Fiil] öznitelikleriyle öznitelik yönlendirme.

Aşağıdaki GetTodoItem yöntemde, "{id}" yapılacaklar öğesinin benzersiz tanımlayıcısı için bir yer tutucu değişkendir. Çağrıldığında GetTodoItem URL'deki değeri "{id}" parametresindeki id yöntemine sağlanır.

[HttpGet("{id}")]
public async Task<ActionResult<TodoItem>> GetTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        return NotFound();
    }

    return todoItem;
}

Dönüş değerleri

ve yöntemlerinin GetTodoItems dönüş türü ActionResult<T> türüdür.GetTodoItem ASP.NET Core nesneyi JS otomatik olarak ON olarak serileştirir ve YANıT iletisinin JSgövdesine ON yazar. İşlenmeyen özel durum olmadığı varsayılarak, bu dönüş türünün yanıt kodu 200 Tamam'dır. İşlenmeyen özel durumlar 5xx hatalarına çevrilir.

ActionResult dönüş türleri çok çeşitli HTTP durum kodlarını temsil edebilir. Örneğin, GetTodoItem iki farklı durum değeri döndürebilir:

  • İstenen kimlikle eşleşen öğe yoksa, yöntem bir 404 durumNotFound hata kodu döndürür.
  • Aksi takdirde, yöntemi ON yanıt gövdesine sahip JS200 döndürür. Sonuçları HTTP 200 yanıtıyla döndürme item .

PutTodoItem yöntemi

PutTodoItem yöntemini inceleyin:

[HttpPut("{id}")]
public async Task<IActionResult> PutTodoItem(long id, TodoItem todoItem)
{
    if (id != todoItem.Id)
    {
        return BadRequest();
    }

    _context.Entry(todoItem).State = EntityState.Modified;

    try
    {
        await _context.SaveChangesAsync();
    }
    catch (DbUpdateConcurrencyException)
    {
        if (!TodoItemExists(id))
        {
            return NotFound();
        }
        else
        {
            throw;
        }
    }

    return NoContent();
}

PutTodoItem , HTTP PUT'yi PostTodoItemkullanması dışında benzerdir. Yanıt 204 (İçerik Yok) şeklindedir. HTTP belirtimine göre, PUT isteği istemcinin yalnızca değişiklikleri değil güncelleştirilmiş varlığın tamamını göndermesini gerektirir. Kısmi güncelleştirmeleri desteklemek için HTTP PATCH kullanın.

Aşağıdaki bölümde arama PutTodoItem hatası alırsanız, veritabanında bir öğe olduğundan emin olmak için çağrısı GET yapın.

PutTodoItem yöntemini test etme

Bu örnek, uygulama her başlatıldığında başlatılması gereken bir bellek içi veritabanı kullanır. PUT çağrısı yapmadan önce veritabanında bir öğe olmalıdır. PUT çağrısı yapmadan önce veritabanında bir öğe olduğundan emin olmak için GET çağrısı yapın.

Kimliği = 1 olan yapılacaklar öğesini güncelleştirin ve adını olarak "feed fish"ayarlayın:

connect https://localhost:5001/api/todoitems/1
put -h Content-Type=application/json -c "{"id":1,"name":"feed fish","isComplete":true}"

Aşağıda komutun çıktısının bir örneğini inceleyebilirsiniz:

HTTP/1.1 204 No Content
Date: Tue, 07 Sep 2021 21:20:47 GMT
Server: Kestrel

DeleteTodoItem yöntemi

DeleteTodoItem yöntemini inceleyin:

[HttpDelete("{id}")]
public async Task<IActionResult> DeleteTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);
    if (todoItem == null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(todoItem);
    await _context.SaveChangesAsync();

    return NoContent();
}

DeleteTodoItem yöntemini test etme

Kimliği = 1 olan yapılacaklar öğesini silin:

connect https://localhost:5001/api/todoitems/1
delete

Aşağıda komutun çıktısının bir örneğini inceleyebilirsiniz:

HTTP/1.1 204 No Content
Date: Tue, 07 Sep 2021 21:43:00 GMT
Server: Kestrel

Fazla deftere nakil önleme

Şu anda örnek uygulama tüm TodoItem nesneyi kullanıma sunar. Üretim uygulamaları genellikle modelin bir alt kümesi kullanılarak giriş ve döndürülen verileri sınırlar. Bunun birden çok nedeni vardır ve güvenlik önemli bir nedendir. Modelin alt kümesi genellikle Veri Aktarım Nesnesi (DTO), giriş modeli veya görünüm modeli olarak adlandırılır. DTO bu öğreticide kullanılır.

DTO, şu durumlarda kullanılabilir:

  • Fazla göndermeyi engelle.
  • İstemcilerin görüntülememesi gereken özellikleri gizleyin.
  • Yük boyutunu küçültmek için bazı özellikleri atla.
  • İç içe nesneler içeren nesne grafiklerini düzleştirme. Düzleştirilmiş nesne grafikleri istemciler için daha kullanışlı olabilir.

DTO yaklaşımını göstermek için sınıfı bir gizli dizi alanı içerecek şekilde güncelleştirin TodoItem :

namespace TodoApi.Models
{
    public class TodoItem
    {
        public long Id { get; set; }
        public string? Name { get; set; }
        public bool IsComplete { get; set; }
        public string? Secret { get; set; }
    }
}

Gizli dizi alanının bu uygulamadan gizlenmesi gerekir, ancak bir yönetim uygulaması bunu kullanıma sunma seçeneğini belirleyebilir.

Gizli dizi alanını gönderip alabildiğinizi doğrulayın.

DTO modeli oluşturma:

namespace TodoApi.Models
{
    public class TodoItemDTO
    {
        public long Id { get; set; }
        public string? Name { get; set; }
        public bool IsComplete { get; set; }
    }
}

kullanılacak TodoItemDTOşekilde güncelleştirinTodoItemsController:

using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

namespace TodoApi.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class TodoItemsController : ControllerBase
    {
        private readonly TodoContext _context;

        public TodoItemsController(TodoContext context)
        {
            _context = context;
        }

        // GET: api/TodoItems
        [HttpGet]
        public async Task<ActionResult<IEnumerable<TodoItemDTO>>> GetTodoItems()
        {
            return await _context.TodoItems
                .Select(x => ItemToDTO(x))
                .ToListAsync();
        }

        // GET: api/TodoItems/5
        [HttpGet("{id}")]
        public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
        {
            var todoItem = await _context.TodoItems.FindAsync(id);

            if (todoItem == null)
            {
                return NotFound();
            }

            return ItemToDTO(todoItem);
        }
        // PUT: api/TodoItems/5
        // To protect from overposting attacks, see https://go.microsoft.com/fwlink/?linkid=2123754
        [HttpPut("{id}")]
        public async Task<IActionResult> UpdateTodoItem(long id, TodoItemDTO todoItemDTO)
        {
            if (id != todoItemDTO.Id)
            {
                return BadRequest();
            }

            var todoItem = await _context.TodoItems.FindAsync(id);
            if (todoItem == null)
            {
                return NotFound();
            }

            todoItem.Name = todoItemDTO.Name;
            todoItem.IsComplete = todoItemDTO.IsComplete;

            try
            {
                await _context.SaveChangesAsync();
            }
            catch (DbUpdateConcurrencyException) when (!TodoItemExists(id))
            {
                return NotFound();
            }

            return NoContent();
        }
        // POST: api/TodoItems
        // To protect from overposting attacks, see https://go.microsoft.com/fwlink/?linkid=2123754
        [HttpPost]
        public async Task<ActionResult<TodoItemDTO>> CreateTodoItem(TodoItemDTO todoItemDTO)
        {
            var todoItem = new TodoItem
            {
                IsComplete = todoItemDTO.IsComplete,
                Name = todoItemDTO.Name
            };

            _context.TodoItems.Add(todoItem);
            await _context.SaveChangesAsync();

            return CreatedAtAction(
                nameof(GetTodoItem),
                new { id = todoItem.Id },
                ItemToDTO(todoItem));
        }

        // DELETE: api/TodoItems/5
        [HttpDelete("{id}")]
        public async Task<IActionResult> DeleteTodoItem(long id)
        {
            var todoItem = await _context.TodoItems.FindAsync(id);

            if (todoItem == null)
            {
                return NotFound();
            }

            _context.TodoItems.Remove(todoItem);
            await _context.SaveChangesAsync();

            return NoContent();
        }

        private bool TodoItemExists(long id)
        {
            return _context.TodoItems.Any(e => e.Id == id);
        }

        private static TodoItemDTO ItemToDTO(TodoItem todoItem) =>
            new TodoItemDTO
            {
                Id = todoItem.Id,
                Name = todoItem.Name,
                IsComplete = todoItem.IsComplete
            };
    }
}

Gizli dizi alanını gönderip alamadığınızdan emin olun.

JavaScript ile web API'sini çağırma

Bkz. Öğretici: JavaScript ile ASP.NET Core web API'si çağırma.

Web API video serisi

Bkz . Video: Başlangıç Serisi- Web API'leri.

Web API'sine kimlik doğrulama desteği ekleme

Identity ASP.NET Core, ASP.NET Core web uygulamalarına kullanıcı arabirimi (UI) oturum açma işlevi ekler. Web API'lerinin ve SPA'larının güvenliğini sağlamak için aşağıdakilerden birini kullanın:

Duende Identity Server, ASP.NET Core için bir OpenID Connect ve OAuth 2.0 çerçevesidir. Duende Identity Server aşağıdaki güvenlik özelliklerini etkinleştirir:

  • Hizmet Olarak Kimlik Doğrulaması (AaaS)
  • Birden çok uygulama türü üzerinden çoklu oturum açma/kapatma (SSO)
  • API'ler için erişim denetimi
  • Federasyon Ağ Geçidi

Önemli

Duende Yazılımı, Duende Identity Server'ın üretim kullanımı için lisans ücreti ödemenizi gerektirebilir. Daha fazla bilgi için, bkz. ASP.NET Core 5.0'den 6.0'a geçiş.

Daha fazla bilgi için Duende Identity Server belgelerine (Duende Yazılımı web sitesi) bakın.

Azure’da Yayımlama

Azure'a dağıtma hakkında bilgi için bkz . Hızlı Başlangıç: ASP.NET web uygulaması dağıtma.

Ek kaynaklar

Bu öğretici için örnek kodu görüntüleyin veya indirin. İndirmeyi öğrenin.

Daha fazla bilgi için aşağıdaki kaynaklara bakın:

Bu öğreticide, veritabanı kullanan denetleyici tabanlı bir web API'sini oluşturmanın temelleri öğretildi. ASP.NET Core'de API oluşturmanın bir diğer yaklaşımı da en az API oluşturmaktır. En düşük API'ler ile denetleyici tabanlı API'ler arasında seçim yaparken yardım için bkz. API'lere genel bakış. En düşük API oluşturma öğreticisi için bkz. Öğretici: ASP.NET Core ile minimum API oluşturma.

Bu öğreticide şunların nasıl yapıldığını öğreneceksiniz:

  • Web API'si projesi oluşturun.
  • Model sınıfı ve veritabanı bağlamı ekleyin.
  • CRUD yöntemleriyle bir denetleyici iskelesi oluşturun.
  • Yönlendirmeyi, URL yollarını ve dönüş değerlerini yapılandırın.
  • Postman ile web API'sini çağırın.

Sonunda, bir veritabanında depolanan "yapılacaklar" öğelerini yönetebilen bir web API'niz vardır.

Genel Bakış

Bu öğretici aşağıdaki API'yi oluşturur:

API Açıklama İstek gövdesi Yanıt gövdesi
GET /api/todoitems Tüm yapılacaklar öğelerini alma Hiçbiri Yapılacaklar öğeleri dizisi
GET /api/todoitems/{id} Kimliğine göre öğe alma Hiçbiri Yapılacaklar öğesi
POST /api/todoitems Yeni öğe ekleme Yapılacaklar öğesi Yapılacaklar öğesi
PUT /api/todoitems/{id} Var olan bir öğeyi güncelleştirme Yapılacaklar öğesi Hiçbiri
DELETE /api/todoitems/{id}     Öğeyi silme Hiçbiri Hiçbiri

Aşağıdaki diyagramda uygulamanın tasarımı gösterilmektedir.

İstemci, soldaki bir kutuyla temsil edilir. Bir istek gönderir ve uygulamadan sağ tarafta çizilmiş bir kutu olan bir yanıt alır. Uygulama kutusunun içinde, denetleyiciyi, modeli ve veri erişim katmanını temsil eden üç kutu vardır. İstek uygulamanın denetleyicisine gelir ve denetleyici ile veri erişim katmanı arasında okuma/yazma işlemleri gerçekleşir. Model serileştirilir ve yanıtta istemciye döndürülür.

Önkoşullar

Web projesi oluşturma

  • Dosyamenüsünden Yeni Proje'yi> seçin.
  • ASP.NET Core Web API'sini seçin ve İleri'ye tıklayın.
  • Projeyi TodoApi olarak adlandırın ve Oluştur'a tıklayın.
  • Yeni ASP.NET Core Web Uygulaması oluştur iletişim kutusunda .NET Core ve ASP.NET Core 5.0'ın seçili olduğunu onaylayın. API şablonunu seçin ve Oluştur'a tıklayın.

VS yeni proje iletişim kutusu

Not

.NET uygulamalarına paket ekleme hakkında yönergeler için, Paket tüketimi iş akışında (NuGet belgeleri)paketleri yüklemek ve yönetmek altındaki makalelere bakın. NuGet.org'da doğru paket sürümlerini onaylayın.

Projeyi test etme

Proje şablonu, Swagger desteğine sahip bir WeatherForecast API oluşturur.

Hata ayıklayıcı olmadan çalıştırmak için Ctrl+F5 tuşlarına basın.

Proje henüz SSL kullanacak şekilde yapılandırılmadığında Visual Studio aşağıdaki iletişim kutusunu görüntüler:

Bu proje SSL kullanacak şekilde yapılandırıldı. Tarayıcıda SSL uyarılarından kaçınmak için, IIS Express tarafından oluşturulan otomatik olarak imzalanan sertifikaya güvenmeyi seçebilirsiniz. IIS Express SSL sertifikasına güvenmek istiyor musunuz?

IIS Express SSL sertifikasına güveniyorsanız Evet'i seçin.

Aşağıdaki iletişim kutusu görüntülenir:

Güvenlik uyarısı iletişim kutusu

Geliştirme sertifikasına güvenmeyi kabul ediyorsanız Evet'i seçin.

Firefox tarayıcısına güvenme hakkında bilgi için bkz. Firefox SEC_ERROR_INADEQUATE_KEY_USAGE sertifika hatası.

Visual Studio başlatılır:

  • IIS Express web sunucusu.
  • Varsayılan tarayıcı ve konumuna https://localhost:<port>/swagger/index.htmlgider; burada <port> rastgele seçilen bir bağlantı noktası numarasıdır.

Swagger sayfası /swagger/index.html görüntülenir. GET>Try it try it out>Execute öğesini seçin. Sayfa şu şekilde görüntülenir:

  • WeatherForecast API'sini test etmek için Curl komutu.
  • WeatherForecast API'sini test etmek için URL.
  • Yanıt kodu, gövde ve üst bilgiler.
  • Medya türlerinin, örnek değerin ve şemanın yer aldığı bir açılan liste kutusu.

Swagger sayfası görünmüyorsa bu GitHub sorununa bakın.

Swagger, web API'leri için yararlı belgeler ve yardım sayfaları oluşturmak için kullanılır. Bu öğreticide web API'si oluşturmaya odaklanmaktadır. Swagger hakkında daha fazla bilgi için bkz. Swagger / OpenAPI ile ASP.NET Core web API'si belgeleri.

İstek URL'sini kopyalayıp tarayıcıya yapıştırın:https://localhost:<port>/weatherforecast

JSON aşağıdakine benzer şekilde döndürülür:

[
    {
        "date": "2019-07-16T19:04:05.7257911-06:00",
        "temperatureC": 52,
        "temperatureF": 125,
        "summary": "Mild"
    },
    {
        "date": "2019-07-17T19:04:05.7258461-06:00",
        "temperatureC": 36,
        "temperatureF": 96,
        "summary": "Warm"
    },
    {
        "date": "2019-07-18T19:04:05.7258467-06:00",
        "temperatureC": 39,
        "temperatureF": 102,
        "summary": "Cool"
    },
    {
        "date": "2019-07-19T19:04:05.7258471-06:00",
        "temperatureC": 10,
        "temperatureF": 49,
        "summary": "Bracing"
    },
    {
        "date": "2019-07-20T19:04:05.7258474-06:00",
        "temperatureC": -1,
        "temperatureF": 31,
        "summary": "Chilly"
    }
]

launchUrl güncelleştirme

Properties\launchSettings.json içinde, 'den '"swagger"a "api/todoitems"güncelleştirinlaunchUrl:

"launchUrl": "api/todoitems",

Swagger kaldırılacağından, yukarıdaki işaretleme, başlatılan URL'yi aşağıdaki bölümlerde eklenen denetleyicinin GET yöntemine değiştirir.

Model sınıfı ekleme

Model, uygulamanın yönettiği verileri temsil eden bir sınıf kümesidir. Bu uygulamanın modeli tek TodoItem bir sınıftır.

  • Çözüm Gezgini'da projeye sağ tıklayın. Yeni Klasör Ekle'yi> seçin. klasörünü Modelsadlandırın.

  • Klasöre sağ tıklayın veSınıfEkle'yi>Models seçin. Sınıfı TodoItem olarak adlandırın ve Ekle'yi seçin.

  • Şablon kodunu aşağıdakilerle değiştirin:

namespace TodoApi.Models
{
    public class TodoItem
    {
        public long Id { get; set; }
        public string Name { get; set; }
        public bool IsComplete { get; set; }
    }
}

özelliği, Id ilişkisel veritabanında benzersiz anahtar olarak işlev görür.

Model sınıfları projede herhangi bir yere gidebilir, ancak Models klasör kural tarafından kullanılır.

Veritabanı bağlamı ekleme

Veritabanı bağlamı, bir veri modeli için Entity Framework işlevselliğini koordine eden ana sınıftır. Bu sınıf, sınıfından Microsoft.EntityFrameworkCore.DbContext türetilerek oluşturulur.

NuGet paketlerini ekleme

  • Araçlarmenüsünden NuGet Paket Yöneticisi > Çözüm için NuGet Paketlerini Yönet'i seçin.
  • Gözat sekmesini seçin ve arama kutusuna girinMicrosoft.EntityFrameworkCore.InMemory.
  • Sol bölmede öğesini seçin Microsoft.EntityFrameworkCore.InMemory .
  • Sağ bölmede Proje onay kutusunu ve ardından Yükle'yi seçin.

NuGet Paket Yöneticisi

TodoContext veritabanı bağlamını ekleme

  • Klasöre sağ tıklayın veSınıfEkle'yi>Models seçin. Sınıfı TodoContext olarak adlandırın ve Ekle'ye tıklayın.

  • Aşağıdaki kodu girin:

    using Microsoft.EntityFrameworkCore;

namespace TodoApi.Models
{
    public class TodoContext : DbContext
    {
        public TodoContext(DbContextOptions<TodoContext> options)
            : base(options)
        {
        }

        public DbSet<TodoItem> TodoItems { get; set; }
    }
}

Veritabanı bağlamını kaydetme

ASP.NET Core'de, VERITABANı bağlamı gibi hizmetlerin bağımlılık ekleme (DI) kapsayıcısıyla kaydedilmesi gerekir. Kapsayıcı, denetleyicilere hizmeti sağlar.

Aşağıdaki kodla güncelleştirin Startup.cs :

// Unused usings removed
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

namespace TodoApi
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();

            services.AddDbContext<TodoContext>(opt =>
                                               opt.UseInMemoryDatabase("TodoList"));
            //services.AddSwaggerGen(c =>
            //{
            //    c.SwaggerDoc("v1", new OpenApiInfo { Title = "TodoApi", Version = "v1" });
            //});
        }

        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
                //app.UseSwagger();
                //app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "TodoApi v1"));
            }

            app.UseHttpsRedirection();
            app.UseRouting();

            app.UseAuthorization();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });
        }
    }
}

Yukarıdaki kod:

  • Swagger çağrılarını kaldırır.
  • Kullanılmayan using bildirimleri kaldırır.
  • VERITABANı bağlamını DI kapsayıcısına ekler.
  • Veritabanı bağlamında bellek içi veritabanı kullanılacağını belirtir.

Bir denetleyicinin iskelesi

  • Denetleyiciler klasörüne sağ tıklayın.

  • Yeni İskeleli Öğe Ekle'yi> seçin.

  • Entity Framework kullanarak eylemlerle API Denetleyicisi'ni ve ardından Ekle'yi seçin.

  • Entity Framework kullanarak EYLEMLERle API Denetleyicisi Ekle iletişim kutusunda:

    • Model sınıfındaTodoItem (TodoApi.Models) öğesini seçin.
    • Veri bağlamı sınıfındaTodoContext (TodoApi.Models) öğesini seçin.
    • Add (Ekle) seçeneğini belirleyin.

Oluşturulan kod:

  • Sınıfı özniteliğiyle [ApiController] işaretler. Bu öznitelik, denetleyicinin web API isteklerine yanıt verdiğini gösterir. Özniteliğin etkinleştirilen belirli davranışlar hakkında bilgi için bkz. ASP.NET Core ile web API'leri oluşturma.
  • Veritabanı bağlamını (TodoContext) denetleyiciye eklemek için DI kullanır. Veritabanı bağlamı, denetleyicideki CRUD yöntemlerinin her birinde kullanılır.

Aşağıdakiler için ASP.NET Core şablonları:

  • Görünümlere sahip denetleyiciler yol şablonuna dahildir [action] .
  • API denetleyicileri yol şablonuna dahil [action] değildir.

[action] Belirteç yol şablonunda olmadığında, eylem adı yolun dışında tutulur. Başka bir ifadeyle, eylemin ilişkili yöntem adı eşleşen yolda kullanılmaz.

PostTodoItem oluşturma yöntemini güncelleştirme

içindeki return deyimini PostTodoItemnameof işlecini kullanacak şekilde güncelleştirin:

// POST: api/TodoItems
[HttpPost]
public async Task<ActionResult<TodoItem>> PostTodoItem(TodoItem todoItem)
{
    _context.TodoItems.Add(todoItem);
    await _context.SaveChangesAsync();

    //return CreatedAtAction("GetTodoItem", new { id = todoItem.Id }, todoItem);
    return CreatedAtAction(nameof(GetTodoItem), new { id = todoItem.Id }, todoItem);
}

Yukarıdaki kod, özniteliğinde gösterildiği gibi bir HTTP POST yöntemidir [HttpPost] . yöntemi, YAPıLACAKlar öğesinin değerini HTTP isteğinin gövdesinden alır.

Daha fazla bilgi için bkz . Http[Fiil] öznitelikleriyle öznitelik yönlendirme.

CreatedAtAction yöntemi:

  • Başarılı olursa bir HTTP 201 durum kodu döndürür. HTTP 201, sunucuda yeni bir kaynak oluşturan bir HTTP POST yönteminin standart yanıtıdır.
  • Yanıta bir Konum üst bilgisi ekler. Üst bilgi, Location yeni oluşturulan yapılacaklar öğesinin URI'sini belirtir. Daha fazla bilgi için bkz . 201 Oluşturuldu.
  • GetTodoItem Üst bilginin URI'sini Location oluşturma eylemine başvurur. C# nameof anahtar sözcüğü, çağrıda CreatedAtAction eylem adını sabit kodlamaktan kaçınmak için kullanılır.

Postman'i yükleme

Bu öğreticide web API'sini test etmek için Postman kullanılır.

  • Postman'i yükleme
  • Web uygulamasını başlatın.
  • Postman'i başlatın.
  • SSL sertifika doğrulamayı devre dışı bırak:
    • Windows için Postman: Dosya>Ayarları 'nı (Genel sekmesi) seçin, SSL sertifika doğrulamasını devre dışı bırakın.
    • macOS için Postman: Postman>Ayarları 'nı (Genel sekmesi) seçin, SSL sertifika doğrulamasını devre dışı bırakın.

      Uyarı

      Denetleyiciyi test ettikten sonra SSL sertifikası doğrulamasını yeniden etkinleştirin.

PostMan ile PostTodoItem'i test edin

  • Yeni bir istek oluşturun.

  • HTTP yöntemini olarak POSTayarlayın.

  • URI'yi olarak https://localhost:<port>/api/todoitemsayarlayın. Örneğin, https://localhost:5001/api/todoitems.

  • Gövde sekmesini seçin.

  • Ham radyo düğmesini seçin.

  • Türü JSON (application/json) olarak ayarlayın.

  • İstek gövdesine yapılacaklar öğesi için ON girin JS:

    {
  "name":"walk dog",
  "isComplete":true
}

  • Gönder’i seçin.

    Oluşturma isteği olan postman

Konum üst bilgisi URI'sini test edin

Konum üst bilgisi URI'sini tarayıcıda test edebilirsiniz. Konum üst bilgisi URI'sini kopyalayıp tarayıcıya yapıştırın.

Postman'de test etmek için:

  • Yanıt bölmesinde Üst Bilgiler sekmesini seçin.

  • Konum üst bilgi değerini kopyalayın:

    Postman konsolunun Üst Bilgiler sekmesi

  • HTTP yöntemini olarak GETayarlayın.

  • URI'yi olarak https://localhost:<port>/api/todoitems/1ayarlayın. Örneğin, https://localhost:5001/api/todoitems/1.

  • Gönder’i seçin.

GET yöntemlerini inceleme

İki GET uç noktası uygulanır:

  • GET /api/todoitems
  • GET /api/todoitems/{id}

İki uç noktayı bir tarayıcıdan veya Postman'den çağırarak uygulamayı test edin. Örnek:

  • https://localhost:5001/api/todoitems
  • https://localhost:5001/api/todoitems/1

çağrısı GetTodoItemstarafından aşağıdakine benzer bir yanıt oluşturulur:

[
  {
    "id": 1,
    "name": "Item1",
    "isComplete": false
  }
]

Postman ile Get'i test edin

  • Yeni bir istek oluşturun.
  • HTTP yöntemini GET olarak ayarlayın.
  • İstek URI'sini olarak https://localhost:<port>/api/todoitemsayarlayın. Örneğin, https://localhost:5001/api/todoitems.
  • Postman'de İki bölme görünümünü ayarlayın.
  • Gönder’i seçin.

Bu uygulama bellek içi bir veritabanı kullanır. Uygulama durdurulup başlatılırsa, önceki GET isteği herhangi bir veri döndürmez. Hiçbir veri döndürülmezse , uygulamaya POST verileri gönderin.

Yönlendirme ve URL yolları

özniteliği, [HttpGet] HTTP GET isteğine yanıt veren bir yöntemi belirtir. Her yöntemin URL yolu aşağıdaki gibi oluşturulur:

  • Denetleyicinin Route özniteliğindeki şablon dizesiyle başlayın:

    [Route("api/[controller]")]
[ApiController]
public class TodoItemsController : ControllerBase
{
    private readonly TodoContext _context;

    public TodoItemsController(TodoContext context)
    {
        _context = context;
    }

  • değerini denetleyicinin adıyla değiştirin [controller] ; kural gereği denetleyici sınıf adı eksi "Denetleyici" sonekidir. Bu örnek için denetleyici sınıf adı TodoItemsController olduğundan denetleyici adı "TodoItems" olur. ASP.NET Core yönlendirme büyük/küçük harfe duyarsızdır.

  • Özniteliğin [HttpGet] bir yol şablonu varsa (örneğin, [HttpGet("products")]), bunu yola ekleyin. Bu örnek şablon kullanmaz. Daha fazla bilgi için bkz . Http[Fiil] öznitelikleriyle öznitelik yönlendirme.

Aşağıdaki GetTodoItem yöntemde, "{id}" yapılacaklar öğesinin benzersiz tanımlayıcısı için bir yer tutucu değişkendir. çağrıldığında GetTodoItem URL'deki değeri "{id}" parametresindeki id yöntemine sağlanır.

// GET: api/TodoItems/5
[HttpGet("{id}")]
public async Task<ActionResult<TodoItem>> GetTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        return NotFound();
    }

    return todoItem;
}

Dönüş değerleri

ve yöntemlerinin GetTodoItems dönüş türü ActionResult<T> türüdür.GetTodoItem ASP.NET Core, nesneyi JS otomatik olarak ON olarak seri hale getirerek JSyanıt iletisinin gövdesine ON yazar. İşlenmeyen özel durum olmadığı varsayılarak, bu dönüş türünün yanıt kodu 200 Tamam'dır. İşlenmeyen özel durumlar 5xx hatalarına dönüştürülür.

ActionResult dönüş türleri çok çeşitli HTTP durum kodlarını temsil edebilir. Örneğin, GetTodoItem iki farklı durum değeri döndürebilir:

  • İstenen kimlikle eşleşen öğe yoksa, yöntem bir 404 durumNotFound hata kodu döndürür.
  • Aksi takdirde, yöntemi ON yanıt gövdesine sahip JS200 döndürür. Sonuçları HTTP 200 yanıtıyla döndürme item .

PutTodoItem yöntemi

PutTodoItem yöntemini inceleyin:

// PUT: api/TodoItems/5
[HttpPut("{id}")]
public async Task<IActionResult> PutTodoItem(long id, TodoItem todoItem)
{
    if (id != todoItem.Id)
    {
        return BadRequest();
    }

    _context.Entry(todoItem).State = EntityState.Modified;

    try
    {
        await _context.SaveChangesAsync();
    }
    catch (DbUpdateConcurrencyException)
    {
        if (!TodoItemExists(id))
        {
            return NotFound();
        }
        else
        {
            throw;
        }
    }

    return NoContent();
}

PutTodoItem , HTTP PUT'yi PostTodoItemkullanması dışında benzerdir. Yanıt 204 (İçerik Yok) şeklindedir. HTTP belirtimine göre, PUT isteği istemcinin yalnızca değişiklikleri değil güncelleştirilmiş varlığın tamamını göndermesini gerektirir. Kısmi güncelleştirmeleri desteklemek için HTTP PATCH kullanın.

çağrısı PutTodoItemsırasında bir hata alırsanız, veritabanında bir öğe olduğundan emin olmak için öğesini arayın GET .

PutTodoItem yöntemini test etme

Bu örnek, uygulama her başlatıldığında başlatılması gereken bir bellek içi veritabanı kullanır. PUT çağrısı yapmadan önce veritabanında bir öğe olmalıdır. PUT çağrısı yapmadan önce veritabanında bir öğe olduğundan emin olmak için GET çağrısı yapın.

Kimliği = 1 olan yapılacaklar öğesini güncelleştirin ve adını olarak "feed fish"ayarlayın:

  {
    "Id":1,
    "name":"feed fish",
    "isComplete":true
  }

Aşağıdaki görüntüde Postman güncelleştirmesi gösterilmektedir:

204 (İçerik Yok) yanıtı gösteren Postman konsolu

DeleteTodoItem yöntemi

DeleteTodoItem yöntemini inceleyin:

// DELETE: api/TodoItems/5
[HttpDelete("{id}")]
public async Task<IActionResult> DeleteTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);
    if (todoItem == null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(todoItem);
    await _context.SaveChangesAsync();

    return NoContent();
}

DeleteTodoItem yöntemini test etme

Yapılacaklar öğesini silmek için Postman kullanın:

  • yöntemini olarak DELETEayarlayın.
  • Silinecek nesnenin URI'sini ayarlayın (örneğin https://localhost:5001/api/todoitems/1).
  • Gönder’i seçin.

Fazla deftere nakil önleme

Şu anda örnek uygulama tüm TodoItem nesneyi kullanıma sunar. Üretim uygulamaları genellikle modelin bir alt kümesi kullanılarak giriş ve döndürülen verileri sınırlar. Bunun birçok nedeni vardır ve güvenlik önemli bir nedendir. Modelin alt kümesi genellikle Veri Aktarım Nesnesi (DTO), giriş modeli veya görünüm modeli olarak adlandırılır. Bu makalede DTO kullanılmıştır.

DTO, şu durumlarda kullanılabilir:

  • Fazla göndermeyi engelle.
  • İstemcilerin görüntülememesi gereken özellikleri gizleyin.
  • Yük boyutunu küçültmek için bazı özellikleri atla.
  • İç içe nesneler içeren nesne grafiklerini düzleştirme. Düzleştirilmiş nesne grafikleri istemciler için daha kullanışlı olabilir.

DTO yaklaşımını göstermek için sınıfı bir gizli dizi alanı içerecek şekilde güncelleştirin TodoItem :

namespace TodoApi.Models
{
    public class TodoItem
    {
        public long Id { get; set; }
        public string Name { get; set; }
        public bool IsComplete { get; set; }
        public string Secret { get; set; }
    }
}

Gizli dizi alanının bu uygulamadan gizlenmesi gerekir, ancak bir yönetim uygulaması bunu kullanıma sunma seçeneğini belirleyebilir.

Gizli dizi alanını gönderip alabildiğinizi doğrulayın.

DTO modeli oluşturma:

public class TodoItemDTO
{
    public long Id { get; set; }
    public string Name { get; set; }
    public bool IsComplete { get; set; }
}

kullanılacak TodoItemDTOşekilde güncelleştirinTodoItemsController:

// GET: api/TodoItems
[HttpGet]
public async Task<ActionResult<IEnumerable<TodoItemDTO>>> GetTodoItems()
{
    return await _context.TodoItems
        .Select(x => ItemToDTO(x))
        .ToListAsync();
}

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

[HttpPut("{id}")]
public async Task<IActionResult> UpdateTodoItem(long id, TodoItemDTO todoItemDTO)
{
    if (id != todoItemDTO.Id)
    {
        return BadRequest();
    }

    var todoItem = await _context.TodoItems.FindAsync(id);
    if (todoItem == null)
    {
        return NotFound();
    }

    todoItem.Name = todoItemDTO.Name;
    todoItem.IsComplete = todoItemDTO.IsComplete;

    try
    {
        await _context.SaveChangesAsync();
    }
    catch (DbUpdateConcurrencyException) when (!TodoItemExists(id))
    {
        return NotFound();
    }

    return NoContent();
}

[HttpPost]
public async Task<ActionResult<TodoItemDTO>> CreateTodoItem(TodoItemDTO todoItemDTO)
{
    var todoItem = new TodoItem
    {
        IsComplete = todoItemDTO.IsComplete,
        Name = todoItemDTO.Name
    };

    _context.TodoItems.Add(todoItem);
    await _context.SaveChangesAsync();

    return CreatedAtAction(
        nameof(GetTodoItem),
        new { id = todoItem.Id },
        ItemToDTO(todoItem));
}

[HttpDelete("{id}")]
public async Task<IActionResult> DeleteTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(todoItem);
    await _context.SaveChangesAsync();

    return NoContent();
}

private bool TodoItemExists(long id) =>
     _context.TodoItems.Any(e => e.Id == id);

private static TodoItemDTO ItemToDTO(TodoItem todoItem) =>
    new TodoItemDTO
    {
        Id = todoItem.Id,
        Name = todoItem.Name,
        IsComplete = todoItem.IsComplete
    };

Gizli dizi alanını gönderip alamadığınızdan emin olun.

JavaScript ile web API'sini çağırma

Bkz. Öğretici: JavaScript ile ASP.NET Core web API'si çağırma.

Web API'sine kimlik doğrulama desteği ekleme

Identity ASP.NET Core, ASP.NET Core web uygulamalarına kullanıcı arabirimi (UI) oturum açma işlevi ekler. Web API'lerinin ve SPA'larının güvenliğini sağlamak için aşağıdakilerden birini kullanın:

Duende Identity Server, ASP.NET Core için bir OpenID Connect ve OAuth 2.0 çerçevesidir. Duende Identity Server aşağıdaki güvenlik özelliklerini etkinleştirir:

  • Hizmet Olarak Kimlik Doğrulaması (AaaS)
  • Birden çok uygulama türü üzerinden çoklu oturum açma/kapatma (SSO)
  • API'ler için erişim denetimi
  • Federasyon Ağ Geçidi

Önemli

Duende Yazılımı, Duende Identity Server'ın üretim kullanımı için lisans ücreti ödemenizi gerektirebilir. Daha fazla bilgi için, bkz. ASP.NET Core 5.0'den 6.0'a geçiş.

Daha fazla bilgi için Duende Identity Server belgelerine (Duende Yazılımı web sitesi) bakın.

Azure’da Yayımlama

Azure'a dağıtma hakkında bilgi için bkz . Hızlı Başlangıç: ASP.NET web uygulaması dağıtma.

Ek kaynaklar

Bu öğretici için örnek kodu görüntüleyin veya indirin. İndirmeyi öğrenin.

Daha fazla bilgi için aşağıdaki kaynaklara bakın:

Bu öğreticide, veritabanı kullanan denetleyici tabanlı bir web API'sini oluşturmanın temelleri öğretildi. ASP.NET Core'de API oluşturmanın bir diğer yaklaşımı da en az API oluşturmaktır. En düşük API'ler ile denetleyici tabanlı API'ler arasında seçim yaparken yardım için bkz. API'lere genel bakış. En düşük API oluşturma öğreticisi için bkz. Öğretici: ASP.NET Core ile minimum API oluşturma.

Bu öğreticide şunların nasıl yapıldığını öğreneceksiniz:

  • Web API'si projesi oluşturun.
  • Model sınıfı ve veritabanı bağlamı ekleyin.
  • CRUD yöntemleriyle bir denetleyici iskelesi oluşturun.
  • Yönlendirmeyi, URL yollarını ve dönüş değerlerini yapılandırın.
  • Postman ile web API'sini çağırın.

Sonunda, bir veritabanında depolanan "yapılacaklar" öğelerini yönetebilen bir web API'niz vardır.

Genel Bakış

Bu öğretici aşağıdaki API'yi oluşturur:

API Açıklama İstek gövdesi Yanıt gövdesi
GET /api/todoitems Tüm yapılacaklar öğelerini alma Hiçbiri Yapılacaklar öğeleri dizisi
GET /api/todoitems/{id} Kimliğine göre öğe alma Hiçbiri Yapılacaklar öğesi
POST /api/todoitems Yeni öğe ekleme Yapılacaklar öğesi Yapılacaklar öğesi
PUT /api/todoitems/{id} Var olan bir öğeyi güncelleştirme Yapılacaklar öğesi Hiçbiri
DELETE /api/todoitems/{id}     Öğeyi silme Hiçbiri Hiçbiri

Aşağıdaki diyagramda uygulamanın tasarımı gösterilmektedir.

İstemci, soldaki bir kutuyla temsil edilir. Bir istek gönderir ve uygulamadan sağ tarafta çizilmiş bir kutu olan bir yanıt alır. Uygulama kutusunun içinde üç kutu denetleyiciyi, modeli ve veri erişim katmanını temsil ediyor. İstek uygulamanın denetleyicisine gelir ve denetleyici ile veri erişim katmanı arasında okuma/yazma işlemleri gerçekleşir. Model seri hale getirilir ve yanıtta istemciye döndürülür.

Önkoşullar

Web projesi oluşturma

  • Dosyamenüsünden Yeni Proje'yi> seçin.
  • ASP.NET Core Web Uygulaması şablonunu seçin ve İleri'ye tıklayın.
  • Projeyi TodoApi olarak adlandırın ve Oluştur'a tıklayın.
  • Yeni ASP.NET Core Web Uygulaması oluştur iletişim kutusunda.NET Core ve ASP.NET Core 3.1'in seçili olduğunu onaylayın. API şablonunu seçin ve Oluştur'a tıklayın.

VS yeni proje iletişim kutusu

Not

.NET uygulamalarına paket ekleme hakkında yönergeler için, Paket tüketimi iş akışında (NuGet belgeleri)paketleri yüklemek ve yönetmek altındaki makalelere bakın. NuGet.org'da doğru paket sürümlerini onaylayın.

API’yi test etme

Proje şablonu bir WeatherForecast API oluşturur. Get Uygulamayı test etmek için tarayıcıdan yöntemini çağırın.

Uygulamayı çalıştırmak için Ctrl+F5 tuşlarına basın. Visual Studio bir tarayıcı başlatır ve konumuna https://localhost:<port>/weatherforecastgider; burada <port> rastgele seçilmiş bir bağlantı noktası numarasıdır.

IIS Express sertifikasına güvenmeniz gerekip gerekmediğini soran bir iletişim kutusu alırsanız Evet'i seçin. Ardından görüntülenen Güvenlik Uyarısı iletişim kutusunda Evet'i seçin.

JSON aşağıdakine benzer şekilde döndürülür:

[
    {
        "date": "2019-07-16T19:04:05.7257911-06:00",
        "temperatureC": 52,
        "temperatureF": 125,
        "summary": "Mild"
    },
    {
        "date": "2019-07-17T19:04:05.7258461-06:00",
        "temperatureC": 36,
        "temperatureF": 96,
        "summary": "Warm"
    },
    {
        "date": "2019-07-18T19:04:05.7258467-06:00",
        "temperatureC": 39,
        "temperatureF": 102,
        "summary": "Cool"
    },
    {
        "date": "2019-07-19T19:04:05.7258471-06:00",
        "temperatureC": 10,
        "temperatureF": 49,
        "summary": "Bracing"
    },
    {
        "date": "2019-07-20T19:04:05.7258474-06:00",
        "temperatureC": -1,
        "temperatureF": 31,
        "summary": "Chilly"
    }
]

Model sınıfı ekleme

Model, uygulamanın yönettiği verileri temsil eden bir sınıf kümesidir. Bu uygulamanın modeli tek TodoItem bir sınıftır.

  • Çözüm Gezgini'da projeye sağ tıklayın. Yeni Klasör Ekle'yi> seçin. Klasörü Modelsolarak adlandırın.

  • Klasöre sağ tıklayın veSınıfEkle'yi>Models seçin. Sınıfı TodoItem olarak adlandırın ve Ekle'yi seçin.

  • Şablon kodunu aşağıdaki kodla değiştirin:

public class TodoItem
{
    public long Id { get; set; }
    public string Name { get; set; }
    public bool IsComplete { get; set; }
}

özelliği, Id ilişkisel veritabanında benzersiz anahtar olarak işlev görür.

Model sınıfları projede herhangi bir yere gidebilir, ancak Models klasör kural tarafından kullanılır.

Veritabanı bağlamı ekleme

Veritabanı bağlamı, bir veri modeli için Entity Framework işlevselliğini koordine eden ana sınıftır. Bu sınıf, sınıfından Microsoft.EntityFrameworkCore.DbContext türetilerek oluşturulur.

NuGet paketlerini ekleme

  • Araçlarmenüsünden NuGet Paket Yöneticisi > Çözüm için NuGet Paketlerini Yönet'i seçin.
  • Gözat sekmesini seçin ve arama kutusuna Microsoft.EntityFrameworkCore.InMemory yazın.
  • Sol bölmede Microsoft.EntityFrameworkCore.InMemory'yi seçin.
  • Sağ bölmede Proje onay kutusunu ve ardından Yükle'yi seçin.

NuGet Paket Yöneticisi

TodoContext veritabanı bağlamını ekleme

  • Klasöre sağ tıklayın veSınıfEkle'yi>Models seçin. Sınıfı TodoContext olarak adlandırın ve Ekle'ye tıklayın.

  • Aşağıdaki kodu girin:

    using Microsoft.EntityFrameworkCore;

namespace TodoApi.Models
{
    public class TodoContext : DbContext
    {
        public TodoContext(DbContextOptions<TodoContext> options)
            : base(options)
        {
        }

        public DbSet<TodoItem> TodoItems { get; set; }
    }
}

Veritabanı bağlamını kaydetme

ASP.NET Core'de, VERITABANı bağlamı gibi hizmetlerin bağımlılık ekleme (DI) kapsayıcısıyla kaydedilmesi gerekir. Kapsayıcı, denetleyicilere hizmeti sağlar.

Aşağıdaki vurgulanmış kodla güncelleştirin Startup.cs :

// Unused usings removed
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

namespace TodoApi
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddDbContext<TodoContext>(opt =>
               opt.UseInMemoryDatabase("TodoList"));
            services.AddControllers();
        }

        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }

            app.UseHttpsRedirection();

            app.UseRouting();

            app.UseAuthorization();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });
        }
    }
}

Yukarıdaki kod:

  • Kullanılmayan using bildirimleri kaldırır.
  • VERITABANı bağlamını DI kapsayıcısına ekler.
  • Veritabanı bağlamında bellek içi veritabanı kullanılacağını belirtir.

Bir denetleyicinin iskelesi

  • Denetleyiciler klasörüne sağ tıklayın.

  • Yeni İskeleli Öğe Ekle'yi> seçin.

  • Entity Framework kullanarak eylemlerle API Denetleyicisi'ni ve ardından Ekle'yi seçin.

  • Eylemlerle API Denetleyicisi Ekle iletişim kutusunda Entity Framework kullanarak:

    • Model sınıfındaTodoItem (TodoApi.Models) öğesini seçin.
    • Veri bağlamı sınıfındaTodoContext (TodoApi.Models) öğesini seçin.
    • Add (Ekle) seçeneğini belirleyin.

Oluşturulan kod:

  • sınıfını özniteliğiyle [ApiController] işaretler. Bu öznitelik, denetleyicinin web API'sinin isteklerine yanıt verdiğini gösterir. Özniteliğin etkinleştirilen belirli davranışlar hakkında bilgi için bkz. ASP.NET Core ile web API'leri oluşturma.
  • Veritabanı bağlamını (TodoContext) denetleyiciye eklemek için DI kullanır. Veritabanı bağlamı, denetleyicideki CRUD yöntemlerinin her birinde kullanılır.

aşağıdakiler için ASP.NET Core şablonları:

  • Görünümlere sahip denetleyiciler yol şablonuna dahildir [action] .
  • API denetleyicileri yol şablonuna dahil [action] değildir.

[action] Belirteç yol şablonunda olmadığında, eylem adı yolun dışında tutulur. Diğer bir ifadeyle, eylemin ilişkili yöntem adı eşleşen yolda kullanılmaz.

PostTodoItem oluşturma yöntemini inceleme

içindeki return deyimini PostTodoItemnameof işlecini kullanacak şekilde değiştirin:

// POST: api/TodoItems
[HttpPost]
public async Task<ActionResult<TodoItem>> PostTodoItem(TodoItem todoItem)
{
    _context.TodoItems.Add(todoItem);
    await _context.SaveChangesAsync();

    //return CreatedAtAction("GetTodoItem", new { id = todoItem.Id }, todoItem);
    return CreatedAtAction(nameof(GetTodoItem), new { id = todoItem.Id }, todoItem);
}

Yukarıdaki kod, özniteliği tarafından [HttpPost] gösterildiği gibi bir HTTP POST yöntemidir. yöntemi, YAPıLACAKlar öğesinin değerini HTTP isteğinin gövdesinden alır.

Daha fazla bilgi için bkz . Http[Fiil] öznitelikleriyle öznitelik yönlendirme.

CreatedAtAction yöntemi:

  • Başarılı olursa bir HTTP 201 durum kodu döndürür. HTTP 201, sunucuda yeni bir kaynak oluşturan bir HTTP POST yöntemi için standart yanıttır.
  • Yanıta bir Konum üst bilgisi ekler. Üst bilgi, Location yeni oluşturulan yapılacaklar öğesinin URI'sini belirtir. Daha fazla bilgi için bkz . 201 Oluşturuldu.
  • GetTodoItem Üst bilginin URI'sini oluşturma eylemine Location başvurur. C# nameof anahtar sözcüğü, çağrıda CreatedAtAction eylem adını sabit kodlamaktan kaçınmak için kullanılır.

Postman'i yükleme

Bu öğreticide web API'sini test etmek için Postman kullanılır.

  • Postman'i yükleme
  • Web uygulamasını başlatın.
  • Postman'i başlatın.
  • SSL sertifika doğrulamayı devre dışı bırak:
    • Windows için Postman: Windows Dosya>Ayarları için Postman (Genel sekmesi), SSL sertifika doğrulamasını devre dışı bırakın.
    • macOS için Postman: Windows PostmanAyarları için Postman> (Genel sekmesi), SSL sertifika doğrulamasını devre dışı bırakın.

      Uyarı

      Denetleyiciyi test ettikten sonra SSL sertifika doğrulamasını yeniden etkinleştirin.

PostTodoItem'i Postman ile test etme

  • Yeni bir istek oluşturun.

  • HTTP yöntemini olarak POSTayarlayın.

  • URI'yi olarak https://localhost:<port>/api/todoitemsayarlayın. Örneğin, https://localhost:5001/api/todoitems.

  • Gövde sekmesini seçin.

  • Ham radyo düğmesini seçin.

  • Türü ON (application/json) olarakJS ayarlayın.

  • İstek gövdesine yapılacaklar öğesi için ON girin JS:

    {
  "name":"walk dog",
  "isComplete":true
}

  • Gönder’i seçin.

    Oluşturma isteği olan postman

Postman ile konum üst bilgisi URI'sini test etme

  • Yanıt bölmesinde Üst Bilgiler sekmesini seçin.

  • Konum üst bilgisi değerini kopyalayın:

    Postman konsolunun Üst Bilgiler sekmesi

  • HTTP yöntemini olarak GETayarlayın.

  • URI'yi olarak https://localhost:<port>/api/todoitems/1ayarlayın. Örneğin, https://localhost:5001/api/todoitems/1.

  • Gönder’i seçin.

GET yöntemlerini inceleme

Bu yöntemler iki GET uç noktası uygular:

  • GET /api/todoitems
  • GET /api/todoitems/{id}

Bir tarayıcıdan veya Postman'den iki uç noktayı çağırarak uygulamayı test edin. Örnek:

  • https://localhost:5001/api/todoitems
  • https://localhost:5001/api/todoitems/1

çağrısı GetTodoItemstarafından aşağıdakine benzer bir yanıt oluşturulur:

[
  {
    "id": 1,
    "name": "Item1",
    "isComplete": false
  }
]

Postman ile Get'i test etme

  • Yeni bir istek oluşturun.
  • HTTP yöntemini GET olarak ayarlayın.
  • İstek URI'sini olarak https://localhost:<port>/api/todoitemsayarlayın. Örneğin, https://localhost:5001/api/todoitems.
  • Postman'de İki bölme görünümü ayarlayın.
  • Gönder’i seçin.

Bu uygulama bellek içi bir veritabanı kullanır. Uygulama durdurulur ve başlatılırsa, önceki GET isteği herhangi bir veri döndürmez. Hiçbir veri döndürülmezse , POST verileri uygulamaya gönderilir.

Yönlendirme ve URL yolları

özniteliği, [HttpGet] HTTP GET isteğine yanıt veren bir yöntemi belirtir. Her yöntemin URL yolu aşağıdaki gibi oluşturulur:

  • Denetleyicinin Route özniteliğindeki şablon dizesiyle başlayın:

    [Route("api/[controller]")]
[ApiController]
public class TodoItemsController : ControllerBase
{
    private readonly TodoContext _context;

    public TodoItemsController(TodoContext context)
    {
        _context = context;
    }

  • değerini denetleyicinin adıyla değiştirin [controller] ; kurala göre denetleyici sınıf adı eksi "Denetleyici" sonekidir. Bu örnek için denetleyici sınıf adı TodoItemsController olduğundan denetleyici adı "TodoItems" olur. ASP.NET Core yönlendirme büyük/küçük harfe duyarsızdır.

  • Özniteliğin [HttpGet] bir yol şablonu varsa (örneğin, [HttpGet("products")]), bunu yola ekleyin. Bu örnek şablon kullanmaz. Daha fazla bilgi için bkz . Http[Fiil] öznitelikleriyle öznitelik yönlendirme.

Aşağıdaki GetTodoItem yöntemde, "{id}" yapılacaklar öğesinin benzersiz tanımlayıcısı için bir yer tutucu değişkendir. Çağrıldığında GetTodoItem URL'deki değeri "{id}" parametresindeki id yöntemine sağlanır.

// GET: api/TodoItems/5
[HttpGet("{id}")]
public async Task<ActionResult<TodoItem>> GetTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        return NotFound();
    }

    return todoItem;
}

Dönüş değerleri

ve yöntemlerinin GetTodoItems dönüş türü ActionResult<T> türüdür.GetTodoItem ASP.NET Core nesneyi JS otomatik olarak ON olarak serileştirir ve YANıT iletisinin JSgövdesine ON yazar. İşlenmeyen özel durumların olmadığı varsayılarak, bu dönüş türünün yanıt kodu 200'dür. İşlenmeyen özel durumlar 5xx hatalarına çevrilir.

ActionResult dönüş türleri çok çeşitli HTTP durum kodlarını temsil edebilir. Örneğin, GetTodoItem iki farklı durum değeri döndürebilir:

  • İstenen kimlikle eşleşen öğe yoksa, yöntem bir 404 NotFound hata kodu döndürür.
  • Aksi takdirde, yöntemi ON yanıt gövdesine sahip JS200 döndürür. Sonuçları HTTP 200 yanıtıyla döndürme item .

PutTodoItem yöntemi

PutTodoItem yöntemini inceleyin:

// PUT: api/TodoItems/5
[HttpPut("{id}")]
public async Task<IActionResult> PutTodoItem(long id, TodoItem todoItem)
{
    if (id != todoItem.Id)
    {
        return BadRequest();
    }

    _context.Entry(todoItem).State = EntityState.Modified;

    try
    {
        await _context.SaveChangesAsync();
    }
    catch (DbUpdateConcurrencyException)
    {
        if (!TodoItemExists(id))
        {
            return NotFound();
        }
        else
        {
            throw;
        }
    }

    return NoContent();
}

PutTodoItem , HTTP PUT'yi PostTodoItemkullanması dışında benzerdir. Yanıt 204 (İçerik Yok) şeklindedir. HTTP belirtimine göre, PUT isteği istemcinin yalnızca değişiklikleri değil güncelleştirilmiş varlığın tamamını göndermesini gerektirir. Kısmi güncelleştirmeleri desteklemek için HTTP PATCH kullanın.

çağrısı PutTodoItemsırasında bir hata alırsanız, veritabanında bir öğe olduğundan emin olmak için öğesini arayın GET .

PutTodoItem yöntemini test etme

Bu örnek, uygulama her başlatıldığında başlatılması gereken bir bellek içi veritabanı kullanır. PUT çağrısı yapmadan önce veritabanında bir öğe olmalıdır. PUT çağrısı yapmadan önce veritabanında bir öğe olduğundan emin olmak için GET çağrısı yapın.

Kimliği = 1 olan yapılacaklar öğesini güncelleştirin ve adını "balık besleme" olarak ayarlayın:

  {
    "id":1,
    "name":"feed fish",
    "isComplete":true
  }

Aşağıdaki görüntüde Postman güncelleştirmesi gösterilmektedir:

204 (İçerik Yok) yanıtı gösteren Postman konsolu

DeleteTodoItem yöntemi

DeleteTodoItem yöntemini inceleyin:

// DELETE: api/TodoItems/5
[HttpDelete("{id}")]
public async Task<ActionResult<TodoItem>> DeleteTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);
    if (todoItem == null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(todoItem);
    await _context.SaveChangesAsync();

    return todoItem;
}

DeleteTodoItem yöntemini test etme

Yapılacaklar öğesini silmek için Postman kullanın:

  • yöntemini olarak DELETEayarlayın.
  • Silinecek nesnenin URI'sini ayarlayın (örneğin https://localhost:5001/api/todoitems/1).
  • Gönder’i seçin.

Fazla deftere nakil önleme

Şu anda örnek uygulama tüm TodoItem nesneyi kullanıma sunar. Üretim uygulamaları genellikle modelin bir alt kümesi kullanılarak giriş ve döndürülen verileri sınırlar. Bunun birçok nedeni vardır ve güvenlik önemli bir nedendir. Modelin alt kümesi genellikle Veri Aktarım Nesnesi (DTO), giriş modeli veya görünüm modeli olarak adlandırılır. Bu makalede DTO kullanılmıştır.

DTO, şu durumlarda kullanılabilir:

  • Fazla göndermeyi engelle.
  • İstemcilerin görüntülememesi gereken özellikleri gizleyin.
  • Yük boyutunu küçültmek için bazı özellikleri atla.
  • İç içe nesneler içeren nesne grafiklerini düzleştirme. Düzleştirilmiş nesne grafikleri istemciler için daha kullanışlı olabilir.

DTO yaklaşımını göstermek için sınıfı bir gizli dizi alanı içerecek şekilde güncelleştirin TodoItem :

public class TodoItem
{
    public long Id { get; set; }
    public string Name { get; set; }
    public bool IsComplete { get; set; }
    public string Secret { get; set; }
}

Gizli dizi alanının bu uygulamadan gizlenmesi gerekir, ancak bir yönetim uygulaması bunu kullanıma sunma seçeneğini belirleyebilir.

Gizli dizi alanını gönderip alabildiğinizi doğrulayın.

DTO modeli oluşturma:

public class TodoItemDTO
{
    public long Id { get; set; }
    public string Name { get; set; }
    public bool IsComplete { get; set; }
}

kullanılacak TodoItemDTOşekilde güncelleştirinTodoItemsController:

    [HttpGet]
    public async Task<ActionResult<IEnumerable<TodoItemDTO>>> GetTodoItems()
    {
        return await _context.TodoItems
            .Select(x => ItemToDTO(x))
            .ToListAsync();
    }

    [HttpGet("{id}")]
    public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
    {
        var todoItem = await _context.TodoItems.FindAsync(id);

        if (todoItem == null)
        {
            return NotFound();
        }

        return ItemToDTO(todoItem);
    }

    [HttpPut("{id}")]
    public async Task<IActionResult> UpdateTodoItem(long id, TodoItemDTO todoItemDTO)
    {
        if (id != todoItemDTO.Id)
        {
            return BadRequest();
        }

        var todoItem = await _context.TodoItems.FindAsync(id);
        if (todoItem == null)
        {
            return NotFound();
        }

        todoItem.Name = todoItemDTO.Name;
        todoItem.IsComplete = todoItemDTO.IsComplete;

        try
        {
            await _context.SaveChangesAsync();
        }
        catch (DbUpdateConcurrencyException) when (!TodoItemExists(id))
        {
            return NotFound();
        }

        return NoContent();
    }

    [HttpPost]
    public async Task<ActionResult<TodoItemDTO>> CreateTodoItem(TodoItemDTO todoItemDTO)
    {
        var todoItem = new TodoItem
        {
            IsComplete = todoItemDTO.IsComplete,
            Name = todoItemDTO.Name
        };

        _context.TodoItems.Add(todoItem);
        await _context.SaveChangesAsync();

        return CreatedAtAction(
            nameof(GetTodoItem),
            new { id = todoItem.Id },
            ItemToDTO(todoItem));
    }

    [HttpDelete("{id}")]
    public async Task<IActionResult> DeleteTodoItem(long id)
    {
        var todoItem = await _context.TodoItems.FindAsync(id);

        if (todoItem == null)
        {
            return NotFound();
        }

        _context.TodoItems.Remove(todoItem);
        await _context.SaveChangesAsync();

        return NoContent();
    }

    private bool TodoItemExists(long id) =>
         _context.TodoItems.Any(e => e.Id == id);

    private static TodoItemDTO ItemToDTO(TodoItem todoItem) =>
        new TodoItemDTO
        {
            Id = todoItem.Id,
            Name = todoItem.Name,
            IsComplete = todoItem.IsComplete
        };       
}

Gizli dizi alanını gönderip alamadığınızdan emin olun.

JavaScript ile web API'sini çağırma

Bkz. Öğretici: JavaScript ile ASP.NET Core web API'si çağırma.

Web API'sine kimlik doğrulama desteği ekleme

Identity ASP.NET Core, ASP.NET Core web uygulamalarına kullanıcı arabirimi (UI) oturum açma işlevi ekler. Web API'lerinin ve SPA'larının güvenliğini sağlamak için aşağıdakilerden birini kullanın:

Duende Identity Server, ASP.NET Core için bir OpenID Connect ve OAuth 2.0 çerçevesidir. Duende Identity Server aşağıdaki güvenlik özelliklerini etkinleştirir:

  • Hizmet Olarak Kimlik Doğrulaması (AaaS)
  • Birden çok uygulama türü üzerinden çoklu oturum açma/kapatma (SSO)
  • API'ler için erişim denetimi
  • Federasyon Ağ Geçidi

Önemli

Duende Yazılımı, Duende Identity Server'ın üretim kullanımı için lisans ücreti ödemenizi gerektirebilir. Daha fazla bilgi için, bkz. ASP.NET Core 5.0'den 6.0'a geçiş.

Daha fazla bilgi için Duende Identity Server belgelerine (Duende Yazılımı web sitesi) bakın.

Azure’da Yayımlama

Azure'a dağıtma hakkında bilgi için bkz . Hızlı Başlangıç: ASP.NET web uygulaması dağıtma.

Ek kaynaklar

Bu öğretici için örnek kodu görüntüleyin veya indirin. İndirmeyi öğrenin.

Daha fazla bilgi için aşağıdaki kaynaklara bakın: