ASP.NET Web API 'SI kullanarak OData v4 uç noktası oluşturmaCreate an OData v4 Endpoint Using ASP.NET Web API

Açık Veri Protokolü (OData) Web için bir veri erişim protokolüdür.The Open Data Protocol (OData) is a data access protocol for the web. OData, CRUD işlemleri (oluşturma, okuma, güncelleştirme ve silme) aracılığıyla veri kümelerini sorgulamak ve işlemek için Tekdüzen bir yol sağlar.OData provides a uniform way to query and manipulate data sets through CRUD operations (create, read, update, and delete).

ASP.NET Web API 'SI hem v3 hem de v4 protokolünü destekler.ASP.NET Web API supports both v3 and v4 of the protocol. V3 uç noktasıyla yan yana çalışan bir v4 uç noktasına bile sahip olabilirsiniz.You can even have a v4 endpoint that runs side-by-side with a v3 endpoint.

Bu öğreticide, CRUD işlemlerini destekleyen bir OData v4 uç noktası oluşturma işlemi gösterilmektedir.This tutorial shows how to create an OData v4 endpoint that supports CRUD operations.

Öğreticide kullanılan yazılım sürümleriSoftware versions used in the tutorial

  • Web API 5,2Web API 5.2
  • OData v4OData v4
  • Visual Studio 2017 (Visual Studio 2017 burayaindirin)Visual Studio 2017 (download Visual Studio 2017 here)
  • Entity Framework 6Entity Framework 6
  • .NET 4.7.2.NET 4.7.2

Öğretici sürümleriTutorial versions

OData sürüm 3 için bkz. OData v3 uç noktası oluşturma.For the OData Version 3, see Creating an OData v3 Endpoint.

Visual Studio projesi oluşturmaCreate the Visual Studio Project

Visual Studio 'da, Dosya menüsünden Yeni > Proje' yi seçin.In Visual Studio, from the File menu, select New > Project.

Yüklü > C# Visual > Web' i genişletin ve ASP.NET Web uygulaması (.NET Framework) şablonunu seçin.Expand Installed > Visual C# > Web, and select the ASP.NET Web Application (.NET Framework) template. Projeyi "ProductService"olarak adlandırın.Name the project "ProductService".

Tamam’ı seçin.Select OK.

Boş şablonu seçin.Select the Empty template. İçin klasör ve çekirdek başvuruları Eklealtında Web API 'si' ni seçin.Under Add folders and core references for:, select Web API. Tamam’ı seçin.Select OK.

OData paketlerini yüklerInstall the OData packages

Araçlar menüsünde NuGet Paket Yöneticisi > Paket Yöneticisi konsolu' nu seçin.From the Tools menu, select NuGet Package Manager > Package Manager Console. Paket Yöneticisi konsol penceresinde, şunu yazın:In the Package Manager Console window, type:

Install-Package Microsoft.AspNet.Odata

Bu komut en son OData NuGet paketlerini yükleme.This command installs the latest OData NuGet packages.

Bir model sınıfı eklemeAdd a model class

Model , uygulamanızdaki bir veri varlığını temsil eden bir nesnedir.A model is an object that represents a data entity in your application.

Çözüm Gezgini modeller klasörüne sağ tıklayın.In Solution Explorer, right-click the Models folder. Bağlam menüsünden > sınıfı Ekle ' yi seçin.From the context menu, select Add > Class.

Note

Kurala göre, model sınıfları modeller klasörüne yerleştirilir, ancak bu kuralı kendi projelerinizde izlemeniz gerekmez.By convention, model classes are placed in the Models folder, but you don't have to follow this convention in your own projects.

Productsınıfı adlandırın.Name the class Product. Product.cs dosyasında, demirbaş kodu aşağıdaki kodla değiştirin:In the Product.cs file, replace the boilerplate code with the following:

namespace ProductService.Models
{
    public class Product
    {
        public int Id { get; set; }
        public string Name { get; set; }
        public decimal Price { get; set; }
        public string Category { get; set; }
    }
}

Id özelliği varlık anahtarıdır.The Id property is the entity key. İstemciler, varlıkları anahtara göre sorgulayabilir.Clients can query entities by key. Örneğin, KIMLIĞI 5 olan ürünü almak için URI /Products(5).For example, to get the product with ID of 5, the URI is /Products(5). Id özelliği, arka uç veritabanında da birincil anahtar olacaktır.The Id property will also be the primary key in the back-end database.

Entity Framework etkinleştirEnable Entity Framework

Bu öğreticide, arka uç veritabanını oluşturmak için Entity Framework (EF) Code First kullanacağız.For this tutorial, we'll use Entity Framework (EF) Code First to create the back-end database.

Note

Web API OData, EF gerektirmez.Web API OData does not require EF. Veritabanı varlıklarını modellerle çevirebilirler herhangi bir veri erişim katmanını kullanın.Use any data-access layer that can translate database entities into models.

İlk olarak, EF için NuGet paketini yüklemeniz gerekir.First, install the NuGet package for EF. Araçlar menüsünde NuGet Paket Yöneticisi > Paket Yöneticisi konsolu' nu seçin.From the Tools menu, select NuGet Package Manager > Package Manager Console. Paket Yöneticisi konsol penceresinde, şunu yazın:In the Package Manager Console window, type:

Install-Package EntityFramework

Web. config dosyasını açın ve aşağıdaki bölümü, configSections öğesinden sonra yapılandırma öğesinin içine ekleyin.Open the Web.config file, and add the following section inside the configuration element, after the configSections element.

<configuration>
  <configSections>
    <!-- ... -->
  </configSections>

  <!-- Add this: -->
  <connectionStrings>
    <add name="ProductsContext" connectionString="Data Source=(localdb)\mssqllocaldb; 
        Initial Catalog=ProductsContext; Integrated Security=True; MultipleActiveResultSets=True; 
        AttachDbFilename=|DataDirectory|ProductsContext.mdf"
      providerName="System.Data.SqlClient" />
  </connectionStrings>

Bu ayar, LocalDB veritabanı için bir bağlantı dizesi ekler.This setting adds a connection string for a LocalDB database. Bu veritabanı, uygulamayı yerel olarak çalıştırdığınızda kullanılacaktır.This database will be used when you run the app locally.

Ardından modeller klasörüne ProductsContext adlı bir sınıf ekleyin:Next, add a class named ProductsContext to the Models folder:

using System.Data.Entity;
namespace ProductService.Models
{
    public class ProductsContext : DbContext
    {
        public ProductsContext() 
                : base("name=ProductsContext")
        {
        }
        public DbSet<Product> Products { get; set; }
    }
}

Oluşturucuda, "name=ProductsContext" bağlantı dizesinin adını verir.In the constructor, "name=ProductsContext" gives the name of the connection string.

OData uç noktasını yapılandırmaConfigure the OData endpoint

Start/WebApiConfig. cs_dosya uygulamasını açın.Open the file App_Start/WebApiConfig.cs. Aşağıdaki using deyimlerini ekleyin:Add the following using statements:

using ProductService.Models;
using Microsoft.AspNet.OData.Builder;
using Microsoft.AspNet.OData.Extensions;

Ardından register yöntemine aşağıdaki kodu ekleyin:Then add the following code to the Register method:

public static class WebApiConfig
{
    public static void Register(HttpConfiguration config)
    {
        // New code:
        ODataModelBuilder builder = new ODataConventionModelBuilder();
        builder.EntitySet<Product>("Products");
        config.MapODataServiceRoute(
            routeName: "ODataRoute",
            routePrefix: null,
            model: builder.GetEdmModel());
    }
}

Bu kod iki şeyi yapar:This code does two things:

  • Bir Varlık Veri Modeli (EDM) oluşturur.Creates an Entity Data Model (EDM).
  • Bir yol ekler.Adds a route.

EDM, verilerin soyut bir modelidir.An EDM is an abstract model of the data. EDM, hizmet meta verileri belgesi oluşturmak için kullanılır.The EDM is used to create the service metadata document. ODataConventionModelBuilder sınıfı varsayılan adlandırma kurallarını kullanarak bir EDM oluşturur.The ODataConventionModelBuilder class creates an EDM by using default naming conventions. Bu yaklaşım için en az kod gereklidir.This approach requires the least code. EDM üzerinde daha fazla denetim istiyorsanız, özellik, anahtar ve gezinti özelliklerini açıkça ekleyerek EDM oluşturmak için ODataModelBuilder sınıfını kullanabilirsiniz.If you want more control over the EDM, you can use the ODataModelBuilder class to create the EDM by adding properties, keys, and navigation properties explicitly.

Bir yol , Web API 'sine http isteklerini uç noktaya nasıl yönlendirildiğini söyler.A route tells Web API how to route HTTP requests to the endpoint. OData v4 yolu oluşturmak için, MapODataServiceRoute genişletme yöntemini çağırın.To create an OData v4 route, call the MapODataServiceRoute extension method.

Uygulamanızda birden çok OData uç noktası varsa, her biri için ayrı bir yol oluşturun.If your application has multiple OData endpoints, create a separate route for each. Her rotaya benzersiz bir yol adı ve ön ek verin.Give each route a unique route name and prefix.

OData denetleyicisi eklemeAdd the OData controller

Denetleyici , http isteklerini işleyen bir sınıftır.A controller is a class that handles HTTP requests. OData hizmetinizde her bir varlık kümesi için ayrı bir denetleyici oluşturursunuz.You create a separate controller for each entity set in your OData service. Bu öğreticide, Product varlığı için bir denetleyici oluşturacaksınız.In this tutorial, you will create one controller, for the Product entity.

Çözüm Gezgini, denetleyiciler klasörüne sağ tıklayın ve > sınıfı Ekle ' yi seçin.In Solution Explorer, right-click the Controllers folder and select Add > Class. ProductsControllersınıfı adlandırın.Name the class ProductsController.

Note

OData v3 için Bu öğreticinin sürümü, denetleyiciyi Ekle yapı iskelesi kullanır.The version of this tutorial for OData v3 uses the Add Controller scaffolding. Şu anda OData v4 için bir yapı iskelesi yoktur.Currently, there is no scaffolding for OData v4.

ProductsController.cs içindeki ortak kodu aşağıdaki kodla değiştirin.Replace the boilerplate code in ProductsController.cs with the following.

using ProductService.Models;
using System.Data.Entity;
using System.Data.Entity.Infrastructure;
using System.Linq;
using System.Net;
using System.Threading.Tasks;
using System.Web.Http;
using System.Web.OData;
namespace ProductService.Controllers
{
    public class ProductsController : ODataController
    {
        ProductsContext db = new ProductsContext();
        private bool ProductExists(int key)
        {
            return db.Products.Any(p => p.Id == key);
        } 
        protected override void Dispose(bool disposing)
        {
            db.Dispose();
            base.Dispose(disposing);
        }
    }
}

Denetleyici, EF kullanarak veritabanına erişmek için ProductsContext sınıfını kullanır.The controller uses the ProductsContext class to access the database using EF. Denetleyicinin Productscontext'i atmak için Dispose metodunu geçersiz kıldığını unutmayın.Notice that the controller overrides the Dispose method to dispose of the ProductsContext.

Bu, denetleyicinin başlangıç noktasıdır.This is the starting point for the controller. Ardından, tüm CRUD işlemleri için yöntemler ekleyeceğiz.Next, we'll add methods for all of the CRUD operations.

Varlık kümesini sorgulamaQuery the entity set

ProductsControlleriçin aşağıdaki yöntemleri ekleyin.Add the following methods to ProductsController.

[EnableQuery]
public IQueryable<Product> Get()
{
    return db.Products;
}
[EnableQuery]
public SingleResult<Product> Get([FromODataUri] int key)
{
    IQueryable<Product> result = db.Products.Where(p => p.Id == key);
    return SingleResult.Create(result);
}

Get yönteminin parametresiz sürümü tüm ürünler koleksiyonunu döndürür.The parameterless version of the Get method returns the entire Products collection. Anahtar parametresine sahip Get yöntemi bir ürünü anahtarıyla arar (Bu durumda, Id özelliği).The Get method with a key parameter looks up a product by its key (in this case, the Id property).

[Enablequery] özniteliği, istemcilerin $filter, $sort ve $Page gibi sorgu seçeneklerini kullanarak sorguyu değiştirmesini sağlar.The [EnableQuery] attribute enables clients to modify the query, by using query options such as $filter, $sort, and $page. Daha fazla bilgi için bkz. OData sorgu seçeneklerini destekleme.For more information, see Supporting OData Query Options.

Varlık kümesine varlık eklemeAdd an entity to the entity set

İstemcilerin veritabanına yeni bir ürün eklemesini sağlamak için aşağıdaki yöntemi ProductsControllerekleyin.To enable clients to add a new product to the database, add the following method to ProductsController.

public async Task<IHttpActionResult> Post(Product product)
{
    if (!ModelState.IsValid)
    {
        return BadRequest(ModelState);
    }
    db.Products.Add(product);
    await db.SaveChangesAsync();
    return Created(product);
}

Varlığı güncelleştirmeUpdate an entity

OData, bir varlığı güncelleştirmek için iki farklı semantiğini destekler, yama ve PUT.OData supports two different semantics for updating an entity, PATCH and PUT.

  • Düzeltme Eki kısmi bir güncelleştirme gerçekleştirir.PATCH performs a partial update. İstemci yalnızca güncelleştirilecek özellikleri belirtir.The client specifies just the properties to update.
  • PUT, tüm varlığın yerini alır.PUT replaces the entire entity.

PUT 'in dezavantajı, istemcinin, değişmeyen değerler de dahil olmak üzere varlıktaki tüm özelliklerin değerlerini gönderebilmesi gerekir.The disadvantage of PUT is that the client must send values for all of the properties in the entity, including values that are not changing. OData özelliği , düzeltme ekinin tercih edildiğini belirtir.The OData spec states that PATCH is preferred.

Her durumda, hem düzeltme eki hem de PUT yöntemlerinin kodu aşağıda verilmiştir:In any case, here is the code for both PATCH and PUT methods:

public async Task<IHttpActionResult> Patch([FromODataUri] int key, Delta<Product> product)
{
    if (!ModelState.IsValid)
    {
        return BadRequest(ModelState);
    }
    var entity = await db.Products.FindAsync(key);
    if (entity == null)
    {
        return NotFound();
    }
    product.Patch(entity);
    try
    {
        await db.SaveChangesAsync();
    }
    catch (DbUpdateConcurrencyException)
    {
        if (!ProductExists(key))
        {
            return NotFound();
        }
        else
        {
            throw;
        }
    }
    return Updated(entity);
}
public async Task<IHttpActionResult> Put([FromODataUri] int key, Product update)
{
    if (!ModelState.IsValid)
    {
        return BadRequest(ModelState);
    }
    if (key != update.Id)
    {
        return BadRequest();
    }
    db.Entry(update).State = EntityState.Modified;
    try
    {
        await db.SaveChangesAsync();
    }
    catch (DbUpdateConcurrencyException)
    {
        if (!ProductExists(key))
        {
            return NotFound();
        }
        else
        {
            throw;
        }
    }
    return Updated(update);
}

Düzeltme durumunda, denetleyici değişiklikleri izlemek için Delta<t> türünü kullanır.In the case of PATCH, the controller uses the Delta<T> type to track the changes.

Bir varlığı silmeDelete an entity

İstemcilerin bir ürünü veritabanından silmesini sağlamak için aşağıdaki yöntemi ProductsControllerekleyin.To enable clients to delete a product from the database, add the following method to ProductsController.

public async Task<IHttpActionResult> Delete([FromODataUri] int key)
{
    var product = await db.Products.FindAsync(key);
    if (product == null)
    {
        return NotFound();
    }
    db.Products.Remove(product);
    await db.SaveChangesAsync();
    return StatusCode(HttpStatusCode.NoContent);
}