ASP.NET Core と Visual Studio for Windows で Web API を作成するCreate a web API with ASP.NET Core and Visual Studio for Windows

作成者: Rick AndersonMike WassonBy Rick Anderson and Mike Wasson

このチュートリアルでは、"to-do" 項目の一覧を管理する Web API を構築します。This tutorial builds a web API for managing a list of "to-do" items. ユーザー インターフェイス (UI) は作成されません。A user interface (UI) isn't created.

このチュートリアルには 3 つのバージョンがあります。There are 3 versions of this tutorial:

概要Overview

このチュートリアルでは、次の API を作成します。This tutorial creates the following API:

APIAPI 説明Description 要求本文Request body 応答本文Response body
GET /api/todoGET /api/todo すべての To Do アイテムを取得します。Get all to-do items なしNone To Do アイテムの配列Array of to-do items
GET /api/todo/{id}GET /api/todo/{id} ID でアイテムを取得します。Get an item by ID なしNone To Do アイテムTo-do item
POST /api/todoPOST /api/todo 新しいアイテムを追加します。Add a new item To Do アイテムTo-do item To Do アイテムTo-do item
PUT /api/todo/{id}PUT /api/todo/{id} 既存のアイテムを更新します。 Update an existing item   To Do アイテムTo-do item なしNone
DELETE /api/todo/{id}    DELETE /api/todo/{id}     アイテムを削除します    Delete an item     なしNone なしNone


次の図は、アプリの基本デザインを示しています。The following diagram shows the basic design of the app.

クライアントは左側のボックスで表され、要求を送信し、アプリケーション (右側に描画されたボックス) から応答を受信します。

  • クライアントとは、Web API を使用するもの (モバイル アプリやブラウザーなど) です。The client is whatever consumes the web API (mobile app, browser, etc.). このチュートリアルでは、クライアントは作成しません。This tutorial doesn't create a client. アプリのテストでは、Postman または curl をクライアントとして使用します。Postman or curl is used as the client to test the app.

  • モデルは、アプリのデータを表すオブジェクトです。A model is an object that represents the data in the app. ここでは、唯一のモデルが to-do 項目です。In this case, the only model is a to-do item. モデルは C# クラスで表され、POCO (Plain Old C# Object。つまり、単純な従来の C# オブジェクト) とも呼ばれます。Models are represented as C# classes, also know as Plain Old C# Object (POCOs).

  • コントローラーは、HTTP 要求を処理し、HTTP 応答を作成するオブジェクトです。A controller is an object that handles HTTP requests and creates the HTTP response. このアプリのコントローラーは 1 つです。This app has a single controller.

  • このチュートリアルを簡潔にするために、アプリでは永続的なデータベースを使用しません。To keep the tutorial simple, the app doesn't use a persistent database. サンプル アプリでは、メモリ内データベースに To Do アイテムを格納します。The sample app stores to-do items in an in-memory database.

必須コンポーネントPrerequisites

以下をインストールします。Install the following:

ASP.NET Core 1.1 バージョンについては、この PDF をご覧ください。See this PDF for the ASP.NET Core 1.1 version.

プロジェクトの作成Create the project

Visual Studio で、[ファイル] メニュー、[新規] > [プロジェクト] の順に選択します。From Visual Studio, select File menu, > New > Project.

[ASP.NET Core Web アプリケーション (.NET Core)] プロジェクト テンプレートを選択します。Select the ASP.NET Core Web Application (.NET Core) project template. プロジェクトに TodoApi という名前を付け、[OK] をクリックします。Name the project TodoApi and select OK.

[新しいプロジェクト] ダイアログ

[New ASP.NET Core Web Application - TodoApi](新しい ASP.NET Core Web アプリケーション - TodoApi) ダイアログで、[Web API] テンプレートを選択します。In the New ASP.NET Core Web Application - TodoApi dialog, select the Web API template. [OK] を選択します。Select OK. [Enable Docker Support](Docker サポートを有効にする)選択しないでください。Do not select Enable Docker Support.

[新しい ASP.NET Core Web アプリケーション] ダイアログ。ASP.NET Core テンプレートから Web API プロジェクト テンプレートが選択されています。

アプリの起動Launch the app

Visual Studio で、CTRL を押しながら F5 を押し、アプリを起動します。In Visual Studio, press CTRL+F5 to launch the app. Visual Studio でブラウザーが起動し、http://localhost:port/api/values にアクセスします。ポートはランダムに選択されたポート番号になります。Visual Studio launches a browser and navigates to http://localhost:port/api/values, where port is a randomly chosen port number. Chrome、Microsoft Edge、Firefox では次の出力が表示されます。Chrome, Microsoft Edge, and Firefox display the following output:

["value1","value2"]

モデル クラスの追加Add a model class

モデルは、アプリのデータを表すオブジェクトです。A model is an object that represents the data in the app. ここでは、唯一のモデルが to-do 項目です。In this case, the only model is a to-do item.

"Models" という名前のフォルダーを追加します。Add a folder named "Models". ソリューション エクスプローラーで、プロジェクトを右クリックします。In Solution Explorer, right-click the project. [追加] > [新しいフォルダー] の順に選択します。Select Add > New Folder. フォルダーに Models という名前を付けます。Name the folder Models.

注: モデル クラスはプロジェクト内のどこでも使用できます。Note: The model classes go anywhere in the project. 通例として、モデル クラス用に Models フォルダーを使用しています。The Models folder is used by convention for model classes.

TodoItem クラスを追加します。Add a TodoItem class. Models フォルダーを右クリックし、[追加] > [クラス] の順にクリックします。Right-click the Models folder and select Add > Class. クラスに TodoItem という名前を付け、[追加] を選択します。Name the class TodoItem and select Add.

TodoItem クラスを次のコードで更新します。Update the TodoItem class with the following code:

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

TodoItem が作成されるとき、データベースは Id を生成します。The database generates the Id when a TodoItem is created.

データベース コンテキストの作成Create the database context

データベース コンテキストは、所与のデータ モデルに対し、Entity Framework 機能を調整するメイン クラスです。The database context is the main class that coordinates Entity Framework functionality for a given data model. このクラスは Microsoft.EntityFrameworkCore.DbContext クラスから派生させて作成します。This class is created by deriving from the Microsoft.EntityFrameworkCore.DbContext class.

TodoContext クラスを追加します。Add a TodoContext class. Models フォルダーを右クリックし、[追加] > [クラス] の順にクリックします。Right-click the Models folder and select Add > Class. クラスに TodoContext という名前を付け、[追加] を選択します。Name the class TodoContext and select Add.

このクラスを次のコードで置き換えます。Replace the class with the following code:

using Microsoft.EntityFrameworkCore;

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

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

    }
}

データベース コンテキストの登録Register the database context

この手順では、依存性の注入コンテナーにデータベース コンテキストを登録します。In this step, the database context is registered with the dependency injection container. サービス (DB コンテキストなど) を依存性の注入 (DI) コンテナーに登録すると、コントローラーで使用できるようになります。Services (such as the DB context) that are registered with the dependency injection (DI) container are available to the controllers.

DB コンテキストをサービス コンテナーに登録するには、依存性の注入の組み込みサポートを使用します。Register the DB context with the service container using the built-in support for dependency injection. Startup.cs ファイルの内容を次のコードに置き換えます。Replace the contents of the Startup.cs file with the following code:

using Microsoft.AspNetCore.Builder;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using TodoApi.Models;

namespace TodoApi
{
    public class Startup
    {       
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddDbContext<TodoContext>(opt => opt.UseInMemoryDatabase("TodoList"));
            services.AddMvc();
        }

        public void Configure(IApplicationBuilder app)
        {
            app.UseMvc();
        }
    }
}

上のコードでは以下の操作が行われます。The preceding code:

  • 使用されていないコードが削除されます。Removes the code that's not used.
  • メモリ内データベースがサービス コンテナーに挿入されるように指定します。Specifies an in-memory database is injected into the service container.

コントローラーの追加Add a controller

ソリューション エクスプローラーで、Controllers フォルダーを右クリックします。In Solution Explorer, right-click the Controllers folder. [追加] > [新しい項目] の順に選択します。Select Add > New Item. [新しい項目の追加] ダイアログで、[Web API コントローラー クラス] テンプレートを選択します。In the Add New Item dialog, select the Web API Controller Class template. クラスに TodoController という名前を付けます。Name the class TodoController.

[新しい項目の追加] ダイアログ。検索ボックスに「controller」と入力されています。Web API コントローラーが選択されています。

このクラスを次のコードで置き換えます。Replace the class with the following code:

using System.Collections.Generic;
using Microsoft.AspNetCore.Mvc;
using TodoApi.Models;
using System.Linq;

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

        public TodoController(TodoContext context)
        {
            _context = context;

            if (_context.TodoItems.Count() == 0)
            {
                _context.TodoItems.Add(new TodoItem { Name = "Item1" });
                _context.SaveChanges();
            }
        }       
    }
}

上のコードでは以下の操作が行われます。The preceding code:

  • 空のコントローラー クラスを定義します。Defines an empty controller class. 次のセクションでは、API を実装するメソッドを追加します。In the next sections, methods are added to implement the API.
  • コンストラクターでは、依存性の注入を使ってデータベース コンテキスト (TodoContext) がコントローラーに挿入されています。The constructor uses Dependency Injection to inject the database context (TodoContext) into the controller. データベース コンテキストは、コントローラーの各 CRUD メソッドで使用されます。The database context is used in each of the CRUD methods in the controller.
  • アイテムが存在しない場合は、コンストラクターがメモリ内データベースにアイテムを追加します。The constructor adds an item to the in-memory database if one doesn't exist.

To Do アイテムの取得Getting to-do items

To Do アイテムを取得するには、TodoController クラスに次のメソッドを追加します。To get to-do items, add the following methods to the TodoController class.

[HttpGet]
public IEnumerable<TodoItem> GetAll()
{
    return _context.TodoItems.ToList();
}

[HttpGet("{id}", Name = "GetTodo")]
public IActionResult GetById(long id)
{
    var item = _context.TodoItems.FirstOrDefault(t => t.Id == id);
    if (item == null)
    {
        return NotFound();
    }
    return new ObjectResult(item);
}

これらのメソッドでは、以下の 2 つの GET メソッドを実装します。These methods implement the two GET methods:

  • GET /api/todo
  • GET /api/todo/{id}

GetAll メソッドの HTTP 応答例を以下に示します。Here is an example HTTP response for the GetAll method:

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

Postman または curl を使用して HTTP 応答を表示する方法については、後で説明します。Later in the tutorial I'll show how the HTTP response can be viewed with Postman or curl.

ルーティングと URL パスRouting and URL paths

[HttpGet] 属性では HTTP GET メソッドを指定します。The [HttpGet] attribute specifies an HTTP GET method. 各メソッドの URL パスは次のように構成されます。The URL path for each method is constructed as follows:

  • コントローラーの Route 属性でテンプレート文字列を使用します。Take the template string in the controller's Route attribute:
namespace TodoApi.Controllers
{
    [Route("api/[controller]")]
    public class TodoController : Controller
    {
        private readonly TodoContext _context;
  • [controller] をコントローラーの名前 ("Controller" サフィックスを除くコントローラー クラス名) に置き換えます。Replaces [controller] with the name of the controller, which is the controller class name minus the "Controller" suffix. このサンプルでは、コントローラー クラス名は TodoController で、ルート名は "todo" です。For this sample, the controller class name is TodoController and the root name is "todo". ASP.NET Core のルーティングでは大文字と小文字は区別されません。ASP.NET Core routing isn't case sensitive.
  • [HttpGet] 属性にルート テンプレート ([HttpGet("/products")] など) がある場合は、それをパスに追加します。If the [HttpGet] attribute has a route template (such as [HttpGet("/products")], append that to the path. このサンプルではテンプレートを使用しません。This sample doesn't use a template. 詳細については、「Attribute routing with Http[Verb] attributes」 (Http[Verb] 属性を使用する属性のルーティング) を参照してください。See Attribute routing with Http[Verb] attributes for more information.

GetById メソッドの場合:In the GetById method:

[HttpGet("{id}", Name = "GetTodo")]
public IActionResult GetById(long id)
{
    var item = _context.TodoItems.FirstOrDefault(t => t.Id == id);
    if (item == null)
    {
        return NotFound();
    }
    return new ObjectResult(item);
}

"{id}" は、todo アイテムの ID に対するプレースホルダー変数です。"{id}" is a placeholder variable for the ID of the todo item. GetById が呼び出されると、メソッドの id パラメーターに URL の "{id}" の値が割り当てられます。When GetById is invoked, it assigns the value of "{id}" in the URL to the method's id parameter.

Name = "GetTodo" により名前付きのルートを作成します。Name = "GetTodo" creates a named route. 名前付きのルートの役割は次のとおりです。Named routes:

  • アプリで、ルート名を使用して HTTP リンクを作成できるようにします。Enable the app to create an HTTP link using the route name.
  • 説明は後ほど行います。Are explained later in the tutorial.

戻り値Return values

GetAll メソッドは IEnumerable を返します。The GetAll method returns an IEnumerable. MVC は自動的にオブジェクトを JSON にシリアル化して、応答メッセージの本文に JSON を書き込みます。MVC automatically serializes the object to JSON and writes the JSON into the body of the response message. このメソッドの応答コードは 200 で、ハンドルされない例外がないものと想定します The response code for this method is 200, assuming there are no unhandled exceptions. (ハンドルされない例外は 5xx エラーに変換されます)。(Unhandled exceptions are translated into 5xx errors.)

これに対し、GetById メソッドは、広範囲の戻り値の型を表す、より一般的な IActionResult 型を返します。In contrast, the GetById method returns the more general IActionResult type, which represents a wide range of return types. GetById には、次の 2 つの異なる戻り値の型があります。GetById has two different return types:

  • 要求された ID と一致するアイテムがない場合、メソッドは 404 エラーを返します。If no item matches the requested ID, the method returns a 404 error. 戻り値が NotFound の場合、HTTP 404 応答が返されます。Returning NotFound returns an HTTP 404 response.

  • それ以外の場合、メソッドは JSON 応答本文で 200 を返します。Otherwise, the method returns 200 with a JSON response body. 戻り値が ObjectResult の場合、HTTP 200 応答が返されます。Returning ObjectResult returns an HTTP 200 response.

アプリの起動Launch the app

Visual Studio で、CTRL を押しながら F5 を押し、アプリを起動します。In Visual Studio, press CTRL+F5 to launch the app. Visual Studio でブラウザーが起動し、http://localhost:port/api/values にアクセスします。ポートはランダムに選択されたポート番号になります。Visual Studio launches a browser and navigates to http://localhost:port/api/values, where port is a randomly chosen port number. http://localhost:port/api/todoTodo コントローラーに移動します。Navigate to the Todo controller at http://localhost:port/api/todo.

その他の CRUD 操作の実装Implement the other CRUD operations

次のセクションでは、CreateUpdateDelete の各メソッドをコントローラーに追加します。In the following sections, Create, Update, and Delete methods are added to the controller.

作成Create

次の Create メソッドを追加します。Add the following Create method.

[HttpPost]
public IActionResult Create([FromBody] TodoItem item)
{
    if (item == null)
    {
        return BadRequest();
    }

    _context.TodoItems.Add(item);
    _context.SaveChanges();

    return CreatedAtRoute("GetTodo", new { id = item.Id }, item);
}

上記のコードは HTTP POST メソッドです。[HttpPost] 属性を使用します。The preceding code is an HTTP POST method, indicated by the [HttpPost] attribute. MVC は、[FromBody] 属性により、HTTP 要求の本文から to-do 項目の値を取得するよう指示されます。The [FromBody] attribute tells MVC to get the value of the to-do item from the body of the HTTP request.

CreatedAtRoute メソッド:The CreatedAtRoute method:

  • 201 応答を返します。Returns a 201 response. HTTP 201 は、サーバーに新しいリソースを作成する HTTP POST メソッドに対する標準の応答です。HTTP 201 is the standard response for an HTTP POST method that creates a new resource on the server.
  • 応答に場所ヘッダーを追加します。Adds a Location header to the response. 場所ヘッダーでは、新しく作成された To Do アイテムの URI を指定します。The Location header specifies the URI of the newly created to-do item. 10.2.2 201 Created」 (10.2.2 201 生成) を参照してください。See 10.2.2 201 Created.
  • "GetTodo" という名前のルートを使用して、URL を作成します。Uses the "GetTodo" named route to create the URL. "GetTodo" という名前のルートは GetById で定義します。The "GetTodo" named route is defined in GetById:
[HttpGet("{id}", Name = "GetTodo")]
public IActionResult GetById(long id)
{
    var item = _context.TodoItems.FirstOrDefault(t => t.Id == id);
    if (item == null)
    {
        return NotFound();
    }
    return new ObjectResult(item);
}

Postman を使用した作成要求の送信Use Postman to send a Create request

Postman コンソール

  • HTTP メソッド名を POST に設定します。Set the HTTP method to POST
  • [Body] ラジオ ボタンを選択します。Select the Body radio button
  • [raw] ラジオ ボタンを選択します。Select the raw radio button
  • 型を JSON に設定します。Set the type to JSON
  • キー/値エディターで次のような To do 項目を追加します。In the key-value editor, enter a Todo item such as
{
    "name":"walk dog",
    "isComplete":true
}
  • [Send] を選択します。Select Send
  • 次のように、下のウィンドウの [Headers] タブを選択して、[Location] ヘッダーをコピーします。Select the Headers tab in the lower pane and copy the Location header:

Postman コンソールの [Headers] タブ

場所ヘッダー URI を使用して新しいアイテムにアクセスできます。The Location header URI can be used to access the new item.

更新Update

次の Update メソッドを追加します。Add the following Update method:

[HttpPut("{id}")]
public IActionResult Update(long id, [FromBody] TodoItem item)
{
    if (item == null || item.Id != id)
    {
        return BadRequest();
    }

    var todo = _context.TodoItems.FirstOrDefault(t => t.Id == id);
    if (todo == null)
    {
        return NotFound();
    }

    todo.IsComplete = item.IsComplete;
    todo.Name = item.Name;

    _context.TodoItems.Update(todo);
    _context.SaveChanges();
    return new NoContentResult();
}

UpdateCreate と似ていますが、HTTP PUT を使用します。Update is similar to Create, but uses HTTP PUT. 応答は 204 (No Content) となります。The response is 204 (No Content). HTTP 仕様に従って、PUT 要求では、デルタのみでなく、更新されたエンティティ全体を送信するようクライアントに求めます。According to the HTTP spec, a PUT request requires the client to send the entire updated entity, not just the deltas. 部分的な更新をサポートするには、HTTP PATCH を使用します。To support partial updates, use HTTP PATCH.

204 (No Content) の応答を示す Postman コンソール

削除Delete

次の Delete メソッドを追加します。Add the following Delete method:

[HttpDelete("{id}")]
public IActionResult Delete(long id)
{
    var todo = _context.TodoItems.FirstOrDefault(t => t.Id == id);
    if (todo == null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(todo);
    _context.SaveChanges();
    return new NoContentResult();
}

Delete の応答は 204 (No Content) となります。The Delete response is 204 (No Content).

Delete をテストします。Test Delete:

204 (No Content) の応答を示す Postman コンソール

次の手順Next steps