ASP.NET Core で Web API を利用する際の注意点や備忘録です。ほぼ箇条書きです。
ASP.NET Web API 版は以前に書きました。
ルーティング、コントローラーなど
ASP.NET Web API と細かい差異はありますが、説明は省略します。
公式解説を参照するとよいでしょう。
CORS
- NuGet で Microsoft.AspNetCore.Cors をインストールする
- Startup.cs で AddCors メソッドおよび UseCors メソッドを呼び出すことで機能を有効にする
- AddMvc メソッドおよび UseMvc メソッドの前で呼び出す必要がある
- コントローラー、アクションの単位では
[EnableCors]を指定する
| using System; | |
| using System.Collections.Generic; | |
| using System.Linq; | |
| using Microsoft.AspNetCore.Builder; | |
| using Microsoft.AspNetCore.Hosting; | |
| using Microsoft.Extensions.Configuration; | |
| using Microsoft.Extensions.DependencyInjection; | |
| namespace SampleWebApi | |
| { | |
| public class Startup | |
| { | |
| public Startup(IConfiguration configuration) | |
| { | |
| Configuration = configuration; | |
| } | |
| public IConfiguration Configuration { get; } | |
| // This method gets called by the runtime. Use this method to add services to the container. | |
| public void ConfigureServices(IServiceCollection services) | |
| { | |
| services.AddCors(); | |
| services.AddMvc(); | |
| } | |
| // This method gets called by the runtime. Use this method to configure the HTTP request pipeline. | |
| public void Configure(IApplicationBuilder app, IHostingEnvironment env) | |
| { | |
| if (env.IsDevelopment()) | |
| { | |
| app.UseDeveloperExceptionPage(); | |
| } | |
| app.UseCors(b => b.AllowAnyOrigin()); | |
| app.UseMvc(); | |
| } | |
| } | |
| } |
CORS が機能しているかどうかをテストするには、現在実行中のものとは異なるドメインを Origin ヘッダーに付加して API を呼び出します。
応答に Access-Control-Allow-Origin ヘッダーが含まれていれば OK です。
要求ヘッダー
Origin: https://tempuri.org
応答ヘッダー
Access-Control-Allow-Origin: *
ツールとしては Advanced REST client などを使えばよいでしょう。
公式解説: ASP.NET Core でのクロス オリジン要求 (CORS) を有効にする
ヘルプ ページ
コードの XML ドキュメントから、ユーザー向けのヘルプ ページを自動的に生成する機能です。
ASP.NET Core では、OpenAPI (Swagger) の .NET 向け実装である Swashbuckle を利用します。
API を呼び出すためのテスト UI も含まれていて便利です。
- NuGet で Swashbuckle.AspNetCore をインストールする
- プロジェクトのプロパティで、XML ドキュメントの出力を有効にする
- Startup.cs で AddSwaggerGen メソッド、UseSwagger メソッドおよび UseSwaggerUI メソッドを呼び出すことで機能を有効にする
ソースコード: Startup.cs
- ヘルプ ページの URI は既定で
/swaggerとなるが、ルートに変更するには、RoutePrefix を空文字列に設定する - アクション メソッドの戻り値が IActionResult の場合、
[ProducesResponseType(200, Type = typeof(string))]のように属性でデータの型を指定する - このサンプルではアセンブリ情報の値をタイトルなどに設定している
公式解説: Swashbuckle と ASP.NET Core の概要
フォーマット
ASP.NET Core Web API では、既定でテキスト (text/plain) と JSON が有効になっています。
テキストを無効にして XML を有効にするには、Startup.ConfigureServices メソッド内で次のようにします。
| using System; | |
| using Microsoft.AspNetCore.Mvc.Formatters; | |
| using Microsoft.Extensions.DependencyInjection; | |
| namespace SampleWebApi | |
| { | |
| public class Startup | |
| { | |
| public void ConfigureServices(IServiceCollection services) | |
| { | |
| services.AddCors(); | |
| // テキスト形式を無効化、XML 形式を有効化 | |
| services.AddMvc(options => | |
| { | |
| options.OutputFormatters.RemoveType<StringOutputFormatter>(); | |
| options.OutputFormatters.Add(new XmlSerializerOutputFormatter()); | |
| }); | |
| // XML 形式を有効化 | |
| //services.AddMvc().AddXmlSerializerFormatters(); | |
| // 以下略 | |
| } | |
| } | |
| } |
さらに、コントローラーまたはアクションに Produces 属性を指定することで、利用可能な Content-Type を制限することもできます。
[Produces("application/json", "application/xml")]
公式解説: ASP.NET Core Web API の応答データの書式設定
作成したサンプル
バージョン情報
- Microsoft.AspNetCore.All 2.0.8
- Microsoft.AspNetCore.Cors 2.0.3
- Swashbuckle.AspNetCore 2.5.0
参照
Do Design Space 