.NET Magazine國際中文電子雜誌
作 者:許薰尹
審 稿:張智凱
文章編號:N131114202
出刊日期:2013/11/20
ASP.NET Web API的架構分為三層:裝載程式 (Hosting)、訊息處理常式 (Message Handler)與控制器 (Controller)。裝載程式 (Hosting) 主要負責底層的通訊,監聽指定的埠號,檢視HTTP請求的內容…等等。
預設ASP.NET Web API提供兩種裝載程式:
- · ASP.NET 裝載程式:裝載在微軟的Internet Information Services (IIS) 伺服器上執行。使用實作在System.Web.Http.WebHost.dll組件中的HttpControllerHandler類別進行裝載。HttpControllerHandler收到第一個請求後,便會建立HttpServer物件,你可以利用GlobalConfiguration.Configuration的靜態屬性來進行組態。
- · 自我裝載入Self-Hosting):自行撰寫裝載程式碼,使用實作在System.Web.Http.SelfHost.dll組件中的HttpSelfHostServer類別進行裝載。此外需要建立System.Web.Http.SelfHost命名空間下的HttpSelfHostConfiguration類別(或其子類別)的實體,進行組態設定,例如設定逾期時間、監聽的埠號等等。
IIS本身已經提供非常完整的裝載環境,不過有時你可能想要更精確地掌控裝載環境,這時就可以選擇撰寫自我裝載的程式碼,本篇文章將要介紹如何撰寫自我裝載ASP.NET Web API。
裝載在主控台應用程式
ASP.NET Web API不一定要裝載在IIS伺服器執行,接下來我們將說明如何利用Visual Studio 2013開發工具,設計一個主控台應用程式來裝載ASP.NET Web API。
使用Visual Studio 2013開發工具建立一個新的主控台應用程式專案。從「File」-「New」-「Project」,選擇「Installed」- Visual C#程式語言,選取「Windows」分類-「Console Application」,將「Name」設為「WebAPIHost」,然後按下「OK」按鈕,請參考下圖所示:

圖 1:建立一個新的主控台應用程式專案。
在Visual Studio 2013開發工具中,利用「Manage NuGet Packages」工具來安裝裝載程式必要的套件。從Visual Studio 2013開發工具-「Solution Explorer」視窗 - WebAPIHost專案 - 按滑鼠右鍵,從快捷選單選取「Manage NuGet Packages」開啟-「Manage NuGet Packages」對話盒,選取左方「Online」清單項目, 在右上方文字方塊中輸入「web api self host」關鍵字,搜尋「Microsoft ASP.NET Web API 2 Self Host」,按下「Install」按鈕安裝,請參考下圖所示:

圖 2:安裝「Microsoft ASP.NET Web API 2 Self Host」套件。
下一步定義WEB API。從Visual Studio 2013開發工具 -「Solution Explorer」視窗- WebAPIHost專案上方按滑鼠右鍵,從快捷選單選擇「Add」- 「New Item」,開啟「Add New Item」對話盒,從右上方文字方塊輸入「Class」搜尋,選取Class,設定名稱為「ValuesController」,然後按下「Add」按鈕,建立新類別,請參考下圖所示:

圖 3:建立ValuesController類別。
在ValuesController.cs檔案最上方,引用命名空間:
using System.Web.Http;
ValuesController類別繼承ApiController,並在ValuesController類別中加入以下方法,其中沒有參數的Get方法會回傳兩個字串「value1」、「value2」;有id參數的Get方法會回傳一個字串串接id值回傳:
public class ValuesController : ApiController {
// GET api/values
public IEnumerable<string> Get( ) {
return new string [ ] { "value1" , "value2" };
}
// GET api/values/5
public string Get( int id ) {
return "value : " + id.ToString( );
}
// POST api/values
public void Post( [FromBody]string value ) {
}
// PUT api/values/5
public void Put( int id , [FromBody]string value ) {
}
// DELETE api/values/5
public void Delete( int id ) {
}
}
在Program.cs檔案最上方,引用命名空間:
using System.Web.Http;
using System.Web.Http.SelfHost;
修改Program.cs的Main方法,加入以下程式碼:
namespace WebAPIHost {
class Program {
static void Main( string [ ] args ) {
var config = new HttpSelfHostConfiguration( "http://localhost:8000" );
config.Routes.MapHttpRoute(
"API Default" , "api/{controller}/{id}" ,
new { id = RouteParameter.Optional } );
using ( HttpSelfHostServer server = new HttpSelfHostServer( config ) ) {
server.OpenAsync( ).Wait( );
Console.WriteLine( "Host is running...." );
Console.ReadLine( );
}
}
}
}
在啟動HttpSelfHostServer之前,你需要先建立HttpSelfHostConfiguration物件進行一些必要的組態,例如設定接聽的埠號、指定路由規則等等。在建立HttpSelfHostConfiguration物件之後,就可以建立HttpSelfHostServer物件,並將HttpSelfHostConfiguration物件傳入HttpSelfHostServer的建構函式之中,接著便可以叫用OpenAsync方法來載入服務執行。實際上HttpSelfHostServer底層是使用WCF來進行通訊的。
撰寫用戶端
裝載程式完成之後,就可以撰寫用戶端,我們將使用簡單的主控台應用程式來叫用ASP.NET Web API。加入一個主控台應用程式,從Visual Studio 2013開發工具-「File」-「Add」-「New Project」,在「New Project」對話方塊中,選取「Installed」- Visual C#程式語言 - 「Windows」分類,選取「Console Application」,建立一個主控台應用程式,將專案名稱設定為「WebAPIClient」,請參考下圖所示:

圖 4:建立WebAPIClient主控台應用程式。
在WebAPIClient主控台應用程式專案安裝「Microsoft ASP.NET Web API 2 Client」套件。從Visual Studio 2013開發工具-「Solution Explorer」- WebAPIClient專案 – 按滑鼠右鍵,從快捷選單選取「Manage NuGet Packages」,開啟「Manage NuGet Packages」對話盒,選取左方「Online」清單項目, 在右上方文字方塊中輸入「web api client」關鍵字,搜尋「Microsoft ASP.NET Web API 2 Client」,按下「Install」按鈕安裝,請參考下圖所示:

圖 5:安裝「Microsoft ASP.NET Web API 2 Client」套件。
在Program.cs檔案最上方,引用命名空間:
using System.Net.Http;
在Program類別之中加入以下程式碼叫用ASP.NET WEB API:
namespace WebAPIClient {
class Program {
static void Main( string [ ] args ) {
Console.WriteLine("Client is running...Press any key to run.");
GetAllData( );
GetDataByID( 1 );
Console.ReadLine( );
}
private static void GetAllData( ) {
HttpClient client = new HttpClient( );
client.BaseAddress = new Uri( "http://localhost:8000/" );
HttpResponseMessage resp = client.GetAsync( "api/values" ).Result;
IEnumerable<string> data = null;
if ( resp.IsSuccessStatusCode ) {
data = resp.Content.ReadAsAsync<IEnumerable<string>>( ).Result;
foreach ( var d in data ) {
Console.WriteLine( d );
}
}
}
private static void GetDataByID( int id ) {
HttpClient client = new HttpClient( );
client.BaseAddress = new Uri( "http://localhost:8000/" );
HttpResponseMessage resp = client.GetAsync( string.Format( "api/values/{0}" , id.ToString( ) ) ).Result;
if ( resp.IsSuccessStatusCode ) {
var data = resp.Content.ReadAsAsync<string>( ).Result;
Console.WriteLine( data );
}
}
}
}
範例中建立HttpClient類別來叫用服務。設定BaseAddress屬性為ASP.NET WEB API所在的URI。HttpClient 類別的GetAsync方法傳送一個HTTP GET請求到指定的URI,例如:「api/values」。接著從HttpResponseMessage類別的IsSuccessStatusCode屬性判斷執行結果是否沒有例外錯誤。若執行成功,則叫用HttpContent類別的擴充方法ReadAsAsync<T>將回應還原序列化為.NET物件。ReadAsAsync<T>方法會回傳一個Task物件,我們便可以從Result屬性取得執行的結果。
測試
設定兩個專案同時執行。從Visual Studio 2013開發工具-「Solution Explorer」視窗,點選「Solution…」,按滑鼠右鍵,從快捷選單選取「Properties」,選取「Multiple startup projects」項目,將WebAPIHost與WebAPIClient兩個專案的「Action」設定為「Start」。並按下右方的向上、向下箭頭,調整專案的執行順序為先WebAPIHost專案再WebAPIClient專案,請參考下圖所示:

圖 6:設定兩個專案同時執行。
按CTRL+F5同時執行兩個專案,裝載程式執行結果,請參考下圖所示:

圖 7:裝載程式執行結果。
用戶端執行結果,請參考下圖所示:

圖 8:用戶端執行結果。
裝載在Windows Service應用程式
Windows Service應用程式是一個在作業系統背景執行的應用程式,在沒有使用者登入的情況下就可以自動執行,很適合拿來裝載ASP.NET WEB API,接下來讓我們來看看如何在Windows Service應用程式中裝載裝載ASP.NET WEB API。
建立一個新的Windows Service專案。從「File」-「Add」-「New Project」- 選擇「Installed」- Visual C#程式語言,選取「Windows」分類-「Windows Service」,將「Name」設為「WindowsServiceHost」,然後按下「OK」按鈕,請參考下圖所示:

圖 9:建立一個新的Windows Service專案。
安裝裝載程式必要的組件。從Visual Studio 2013開發工具-「Solution Explorer」- WindowsServiceHost專案上方按滑鼠右鍵,從快捷選單選擇 「Manage NuGet Packages」,開啟「Manage NuGet Packages」對話盒,選取左方「Online」清單項目, 在右上方文字方塊中輸入「web api self host」關鍵字,搜尋「Microsoft ASP.NET Web API 2 Self Host」,按下「Install」按鈕安裝,請參考下圖所示:

圖 10:安裝「Microsoft ASP.NET Web API 2 Self Host」。
從Visual Studio 2013開發工具 -「Solution Explorer」視窗- WindowsServiceHost專案上方按滑鼠右鍵,從快捷選單選擇「Add」- 「New Item」,開啟「Add New Item」對話盒,從右上方文字方塊輸入「Class」搜尋,選取Class,設定名稱為「ValuesController」,然後按下「Add」按鈕,建立ValuesController類別,請參考下圖所示:

圖 11:建立ValuesController類別。
在ValuesController.cs檔案最上方,引用命名空間:
using System.Web.Http;
加入以下程式碼到ValuesController類別:
namespace WindowsServiceHost {
public class ValuesController : ApiController {
// GET api/values
public IEnumerable<string> Get( ) {
return new string [ ] { "value1" , "value2" };
}
// GET api/values/5
public string Get( int id ) {
return "value : " + id.ToString( );
}
// POST api/values
public void Post( [FromBody]string value ) {
}
// PUT api/values/5
public void Put( int id , [FromBody]string value ) {
}
// DELETE api/values/5
public void Delete( int id ) {
}
}
}
在Service1.cs檔案最上方,引用命名空間:
using System.Web.Http;
using System.Web.Http.SelfHost;
在OnStart、OnStop方法中撰寫以下程式碼,ASP.NET Web API將聽在8001埠:
namespace WindowsServiceHost {
public partial class Service1 : ServiceBase {
public Service1( ) {
InitializeComponent( );
}
HttpSelfHostServer server ;
protected override void OnStart( string [ ] args ) {
var config = new HttpSelfHostConfiguration( "http://localhost:8001" );
config.Routes.MapHttpRoute(
"API Default" , "api/{controller}/{id}" ,
new { id = RouteParameter.Optional } );
server = new HttpSelfHostServer( config ) ;
server.OpenAsync( ).Wait( );
}
protected override void OnStop( ) {
server.CloseAsync( ).Wait( );
server.Dispose( );
}
}
}
在Service1設計視窗上按滑鼠右鍵選取「Add Installer」。接著專案會新增一個ProjectInstaller類別,請參考下圖所示:

圖 12:「Add Installer」。
在ProjectInstaller的設計視窗中自動會新增ServiceInstaller1與ServiceProcessInstaller1二個項目,請參考下圖所示:

圖 13:新增ServiceInstaller1與ServiceProcessInstaller1二個項目。
設定ServiceInstaller1的屬性如下:
屬性 | 設定值 |
Description | myWebApiHost |
DisplayName | myWebApiHost |
StartType | Automatic |
完成的結果請參考下圖所示:

圖 14:設定ServiceInstaller1的屬性。
設定ServiceProcessInstaller1的屬性如下:
屬性 | 設定值 |
Account | LocalSystem |
圖 15:設定ServiceProcessInstaller1的屬性
完成的結果請參考下圖所示:

圖 16:設定ServiceProcessInstaller1的屬性。
選取Visual Studio 2013的「Build」-「Build Solution」建置專案,建置成功之後便可使用工具程式安裝服務。執行「Developer Command Prompt for VS2013」。在命令提示列上輸入:
installutil -i WindowsServiceHost.exe
開啟「Computer Management」管理工具,檢視「Services」,在服務的管理視窗中,你看到安裝完成的服務項目。在「myWebApiHost」的服務項目上,按滑鼠右鍵選取「Start」,請參考下圖所示:

圖 17:啟動服務。
未來若想要移除服務,執行「Developer Command Prompt for VS2012」,移除服務,在命令提示列上輸入
InstallUtil WindowsServiceHost.exe /u
撰寫用戶端
我們可以利用前文建立的WebAPIClient專案來測試ASP.NET Web API的呼叫,只要修改呼叫的BaseAddress為新URI就可以了:
HttpClient client = new HttpClient();
client.BaseAddress = new Uri("http://localhost:8001/");
設定WebAPIClient專案為起始專案。從「Solution Explorer」視窗,選取WebAPIClient專案,按滑鼠右鍵,選取「Set as StartUp Project」,請參考下圖所示:

圖 18:設定WebAPIClient專案為起始專案。
按CTRL+F5執行,用戶端執行結果,請參考下圖所示:

圖 19:用戶端執行結果。