URL エンコーディング

URL エンコーディングの定義と、それを扱うための .NET Framework のライブラリを検証しました。

パーセント エンコーディングと URL エンコーディング

パーセント エンコーディングとは、文字列を UTF-8 でエンコードし、各バイトをパーセント記号 % とその 16 進数を用いて表すことです。
例えば、"/" は "%2F" に、"あ" は "%E3%81%82" に変換されます。

URL エンコーディングとは、URI の中で使われている記号と混在しないように一部の文字列をパーセント エンコーディングにより
変換することです。両者の言葉を区別せずに使うこともあります。

URL エンコーディング

RFC 3986 では、文字は次のように分類されます。

• 非予約文字
  • エンコードしなくても利用できる文字
  • アルファベット、数字、および 4 種類の記号 -._~
• 予約文字
  • URI で意味を持つ記号
  • 18 種類の記号 !#$&'()*+,/:;=?@[]
• その他の文字
  • エンコードが必要な文字
  • 11 種類の記号 " %<>\^`{|} 、その他のすべての文字 (日本語など)

URL エンコーディングは、主に次の 2 通りで利用されます。

• URI の各セグメント (クエリ文字列を除く)
  • https://tempuri.org/messages/Hello%20World%21 の messages や Hello%20World%21 の部分
  • 非予約文字以外をパーセント エンコーディング
    • ただし、Web フレームワーク個別の仕様により、パーセント エンコーディングしても使用を制限されることがある
• URI のクエリ文字列や、POST などで送信するときの本文 (フォーム)
  • key=value&message=Hello+World%21 の key や Hello+World%21 の部分
  • 非予約文字以外をパーセント エンコーディングし、さらに %20 (スペース) を + に変換
  • MIME タイプ application/x-www-form-urlencoded と定義されている

 

.NET Framework のライブラリ

.NET Framework では、URL エンコーディングのために次の方法が用意されています。

• System.Uri.EscapeDataString メソッド
  • RFC 3986 に従って非予約文字以外をパーセント エンコーディング
• System.Uri.EscapeUriString メソッド
  • RFC 3986 に従って非予約文字・予約文字以外をパーセント エンコーディング
  • 既に全体が URI の形式になっているときに利用する
    • クエリ文字列も同様の規則で変換される。application/x-www-form-urlencoded には変換されない
• System.Uri インスタンスの AbsoluteUri プロパティ
  • 基本的に Uri.EscapeUriString メソッドと同じだが、下記の点が異なる
  • %XX の形式になっているかどうかで扱いが異なる
    • https://tempuri.org/%2 は https://tempuri.org/%252 に
    • https://tempuri.org/%25 は https://tempuri.org/%25 のまま
  • クエリ文字列でない部分の \ は / に変換される
• System.Net.WebUtility.UrlEncode メソッド
  • RFC 2396 (旧版) に近い仕様で非予約文字以外をパーセント エンコーディングし、さらに %20 (スペース) を + に変換
• System.Web.HttpUtility.UrlEncode メソッド
  • System.Net.WebUtility.UrlEncode メソッドと同じだが、小文字になる
• System.Net.Http.FormUrlEncodedContent クラス
  • key-value データをまとめて application/x-www-form-urlencoded に変換

 

 

.NET では System.Uri.EscapeDataString メソッド、System.Uri.EscapeUriString メソッド、
System.Net.Http.FormUrlEncodedContent クラスを使えばよいでしょう。

アプリケーションから HTTP 接続をするために System.Net.Http.HttpClient クラスを使うことが多いと思いますが、
接続先の URI を string で渡しても、HttpClient の内部では Uri インスタンスで扱われます。
したがって、URI を HttpClient に渡す前に、セグメントもクエリ文字列も URL エンコーディングしておくのがよさそうです。

 

作成したサンプル

• ConversionSample (GitHub)
• AspNetWebApiSample (GitHub)

バージョン情報

• .NET Framework 4.5

参照

• Percent-encoding
• URIで使用できる文字
• URLエンコードについておさらいしてみた
• application/x-www-form-urlencoded
• URLエンコード、URLデコードを行う

広告

ASP.NET Core Web API の Tips

ASP.NET Core で Web API を利用する際の注意点や備忘録です。ほぼ箇条書きです。
ASP.NET Web API 版は以前に書きました。

ルーティング、コントローラーなど

ASP.NET Web API と細かい差異はありますが、説明は省略します。
公式解説を参照するとよいでしょう。

• ASP.NET Core のルーティング
• ASP.NET Core 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 コマンドによるビルド

作成したサンプル

• AspNetCoreWebApiSample (GitHub)

バージョン情報

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

参照

• ASP.NET Core で Web API を構築する
• ASP.NET Web API の Tips (1)

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

 

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

作成したサンプル

• NetStandardSample (GitHub)

バージョン情報

• .NET Core 2.0

参照

• dotnet build コマンド
• dotnet publish コマンド
• dotnet pack コマンド
• .NET Coreでコンソールアプリを配置する