ASP.NET Core Web API の Tips

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] を指定する

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 メソッド内で次のようにします。

さらに、コントローラーまたはアクションに Produces 属性を指定することで、利用可能な Content-Type を制限することもできます。

[Produces("application/json", "application/xml")]

公式解説: ASP.NET Core Web API の応答データの書式設定

 

前回: dotnet コマンドによるビルド

作成したサンプル

バージョン情報

  • Microsoft.AspNetCore.All 2.0.8
  • Microsoft.AspNetCore.Cors 2.0.3
  • Swashbuckle.AspNetCore 2.5.0

参照

広告
カテゴリー: .NET Core. タグ: , . 3 Comments »

dotnet コマンドによるビルド

前回の .NET Core と .NET Standard に引き続き、今回はコマンドラインでアプリやライブラリをビルドする方法を検証しました。
まず、ビルドに関連する dotnet コマンドの一覧を挙げます。
基本的にはプロジェクト フォルダー上で実行しますが、build や pack などは ソリューション フォルダー上でも実行できます。

  • dotnet restore
    • NuGet 参照を解決する
  • dotnet build
    • MSBuild.exe を実行する
    • 内部で restore する (ソースコードしかない状態でも実行できる)
  • dotnet msbuild
    • MSBuild.exe と同じ引数を指定する
    • 内部で restore しない (ソースコードしかない状態では失敗)
  • dotnet publish
    • publish フォルダーに発行する
    • 内部で build する (ソースコードしかない状態でも実行できる)
  • dotnet pack
    • NuGet パッケージを作成する
    • 参照先の DLL は含まれず、依存関係が設定される
    • 内部で build しない (ソースコードしかない状態では失敗)
  • dotnet clean
    • 前回のビルド結果を消去する
    • restore の結果は残る
  • dotnet run
    • ソースコードからアプリを実行する
    • 内部で build する
  • dotnet App1.dll
    • ビルド済みのアプリを実行する

 

以下、詳細について記述していきます。

dotnet msbuild と msbuild

dotnet msbuild と msbuild の動作は同じです。

dotnet msbuild /p:Configuration=Release /t:Rebuild
msbuild /p:Configuration=Release /t:Rebuild

ただし、msbuild は環境変数の PATH に設定されていないため、
cmd や PowerShell で実行するにはそのパスを指定しなければなりませんが、
dotnet は PATH に設定されているため cmd や PowerShell でそのまま実行できて便利です。

アセンブリのビルド・発行

リビルドするには --no-incremental を指定します。

dotnet build -c Release --no-incremental

ただし build では、.NET Core を対象とする場合、NuGet 参照の DLL がコピーされません。
build では開発環境が想定されており、.dev.json ファイルに NuGet 参照が記述されます。
(.NET Framework を対象とする場合は NuGet 参照の DLL もコピーされます。)

配置用にすべての DLL を含めるには publish を使います。
プロジェクトに対象のフレームワークが複数ある場合、-f で一つだけ指定します。

dotnet clean -c Release
dotnet publish -c Release -f netcoreapp2.0

なお、publish 単独ではリビルドができないため、先に clean を実行しています。

NuGet パッケージ作成

出力先のディレクトリを変更するには -o を指定します。

dotnet pack -c Release -o pkg

または、

dotnet msbuild /p:Configuration=Release /t:pack

[構築時に NuGet パッケージを生成する] (.csproj では GeneratePackageOnBuild) を設定して build する方法もあります。

dotnet build -c Release --no-incremental

GeneratePackageOnBuild

 

前回: .NET Core と .NET Standard
次回: ASP.NET Core Web API の Tips

作成したサンプル

バージョン情報

  • .NET Core 2.0

参照

カテゴリー: .NET Core, .NET Framework, ツール. タグ: . 2 Comments »

.NET Core と .NET Standard

.NET Core の登場以降、Visual Studio で新しいプロジェクトを作成しようとすると、
従来の .NET Framework のほかに .NET Core と .NET Standard 向けのプロジェクト テンプレートが現れます。

NewProject

それぞれのプロジェクトにおけるアセンブリの参照可否をまとめると次のようになります。

  • .NET Framework 向けプロジェクト
    • .NET Framework アセンブリを参照可能
    • .NET Core アセンブリを参照不可
    • .NET Standard アセンブリを参照可能
  • .NET Core 向けプロジェクト
    • .NET Framework アセンブリを参照不可
    • .NET Core アセンブリを参照可能
    • .NET Standard アセンブリを参照可能

.NET Framework と .NET Core はランタイムが異なるため、
両方に対応するクロスプラットフォームのクラス ライブラリを作成するには .NET Standard をターゲットにします。
なお、.NET Standard 2.0 アセンブリは .NET Framework 4.6.1 以上で参照可能です。

.NET Core および .NET Standard のプロジェクト テンプレートには、次の特徴があります。

  • .csproj ファイルの記述が簡略化されている
    • アセンブリ情報は .csproj ファイルに含まれ、AssemblyInfo.cs は不要
  • NuGet パッケージを簡単に作成できる
    • ビルド時に作成するように設定できる

クラス ライブラリの .csproj ファイルの内容は次のようになっています。


<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
  </PropertyGroup>

</Project>


TargetFramework を TargetFrameworks に変更すれば、対象のフレームワークをセミコロン区切りで複数指定できます。
ここで指定する netstandard2.0net40 は、Target Framework Moniker と呼ばれます。

<TargetFrameworks>netstandard2.0;net40</TargetFrameworks>

これで複数のフレームワークを対象にしたアセンブリを一度にビルドできます。

TargetFrameworks

.NET Framework 向けのみのアセンブリを作成したい場合であっても、
.NET Core 向けのテンプレートから作成して TargetFramework を変更する方法が有効です。

次に、OutputTypeExe を指定すればコンソール アプリになります (指定がなければクラス ライブラリ)。

<OutputType>Exe</OutputType>
<TargetFrameworks>netcoreapp2.0;net45</TargetFrameworks>

コンソール アプリをビルドすると、.NET Framework 向けでは .exe が生成されますが、.NET Core 向けでは .dll となります。
(自己完結型デプロイにより、各プラットフォーム向けの実行可能ファイルを生成することもできます。ただし 60MB 前後になります。)

NetCoreConsole

DLL の状態の .NET Core 向けアプリを実行するには、dotnet コマンドを実行します。

dotnet ConsoleApp1.dll

その他の注意点

  • 例えば System.Security.Cryptography 名前空間は .NET Standard で利用可能ですが、
    .NET Framework と .NET Core ではクラス構成に差異があります。
    ビルドできても実行時にエラーとなることもあります (HashAlgorithm.Create メソッドなど)。

 

次回: dotnet コマンドによるビルド

作成したサンプル

バージョン情報

  • Visual Studio 2017
  • .NET Core 2.0

参照