建立 ASP.NET Web API 專案的幾種方式

前端工程與行動裝置的風行,讓問世多年的 ASP.NET Web API 取代 ASP.NET MVC 的態勢愈來愈明顯,網站開發已經由使用單一 framework 處理前後端轉變為由後端只提供資料,畫面顯示部份由前端專責工程師處理或是行動裝置取代

很明顯的改變就是以往建立專案多是使用 ASP.NET MVC ,而近幾年 ASP.NET MVC 已經少見很多,取而代之的都是 ASP.NET Web API。既然 ASP.NET Web API 這麼盛行,也問世好幾年,但一直都沒有好好了解它。剛好最近的專案需要建立多個 ASP.NET Web API 站台,趁這個機會紀錄一下

如何建立 ASP.NET Web API 專案

  1. 使用 ASP.NET Web API 專案範本

    1webapitemplate

    • 預設專案結構

    4webapistructure

    • 預設安裝 MVCWeb Api 功能

    5defaultinstall

    • 因為使用 HelpPage 需要用到 MVC,所以會進行完整安裝

    • 優點:

      • 具備 MVCWeb Api 完整功能,可以直接開發及部署
    • 缺點:

      • 預設安裝了不一定需要套件(e.g. 不一定需要 HelpPage,可以直接使用 Swagger 取代,導致 MVC 多餘)
  2. 使用 Empty 專案範本 - 加入 Web API 資料夾與參考

    2emptywithwebapi

    • 預設專案結構

    6emptywebapistructure

    • 預設安裝 Web Api 功能

    7defaultwebapi

    • 優點:

      • 具備 Web Api 完整功能,加入 api controller 就可以正常運行
    • 缺點:

      • 啟動畫面會是 403.14,對其他使用者較不友善

      8403.14

  3. 使用 Empty 專案範本

    3empty

    • 預設專案結構

    9empty

    • 完全沒有預設安裝
    • 優點:

      • 非常乾淨,需要什麼完全自訂
    • 缺點:

      • 需要較多步驟才能建立可執行的程式
    • 內含了兩種建立方法

      • 使用 Microsoft.AspNet.WebApi
      • 使用 Microsoft.AspNet.WebApi.Core
    • 使用 Microsoft.AspNet.WebApi 建立 ASP.NET Web API

      • NuGet 安裝 Microsoft.AspNet.WebApi

        2017/07/23 最新版為 v5.2.3

        10mswebapi

      • 加入 App_StartControllers 兩個資料夾至專案中

        11twofolder

      • App_start 中加入 WebApiConfig.cs

        • 引用 using System.Web.Http;

          using System.Web.Http;
          
        • 加入註冊 api route 設定

          public static void Register(HttpConfiguration config)
          {
              // Web API routes
              config.MapHttpAttributeRoutes();
              config.Routes.MapHttpRoute(
                  name: "DefaultApi",
                  routeTemplate: "api/{controller}/{id}",
                  defaults: new { id = RouteParameter.Optional }
              );
          }
          
        • 完整程式碼

          using System.Web.Http;
          namespace EmptyWebApi.App_Start
          {
              public static  class WebApiConfig
              {
                  public static void Register(HttpConfiguration config)
                  {
                      // Web API routes
                      config.MapHttpAttributeRoutes();
                      config.Routes.MapHttpRoute(
                          name: "DefaultApi",
                          routeTemplate: "api/{controller}/{id}",
                          defaults: new { id = RouteParameter.Optional }
                      );
                  }
              }
          }
          
      • 加入 Global.asax 檔案

        • 專案 按右鍵 –> Add –> New Item… –> 搜尋 Global –> Global Application Class

          12global

        • 刪除所有內容,只保留 Application_Start 並加上 api route 註冊

          protected void Application_Start(object sender, EventArgs e)
          {
              GlobalConfiguration.Configure(WebApiConfig.Register);
          }
          
        • 完整程式碼

          using EmptyWebApi.App_Start;
          using System;
          using System.Web.Http;
          namespace EmptyWebApi
          {
              public class Global : System.Web.HttpApplication
              {
                  protected void Application_Start(object sender, EventArgs e)
                  {
                      GlobalConfiguration.Configure(WebApiConfig.Register);
                  }
              }
          }
          
      • 在 Controllers 資料夾新增 controller 即可

    • 使用 Microsoft.AspNet.WebApi.Core 建立 ASP.NET Web API

      這個方式其實就是使用 Owin 來 host web app

      • NuGet 安裝 Microsoft.AspNet.WebApi.Core

        2017/07/23 最新版為 v5.2.3

        13emptycore

      • NuGet 安裝 Microsoft.Owin.Host.SystemWeb

        2017/07/23 最新版為 v3.1.0

        14owinsystemweb

      • NuGet 安裝 Microsoft.AspNet.WebApi.Owin

        2017/07/23 最新版為 v5.2.3

        15owinwebapi

      • 加入 App_StartControllers 兩個資料夾至專案中

        11twofolder

      • App_start 中加入 WebApiConfig.cs

        • 引用 using System.Web.Http;

          using System.Web.Http;
          
        • 加入註冊 api route 設定

          public static void Register(HttpConfiguration config)
          {
              // Web API routes
              config.MapHttpAttributeRoutes();
                          config.Routes.MapHttpRoute(
                  name: "DefaultApi",
                  routeTemplate: "api/{controller}/{id}",
                  defaults: new { id = RouteParameter.Optional }
              );
          }
          
        • 完整程式碼

          using System.Web.Http;
          namespace EmptyWebApi.App_Start
          {
              public static class WebApiConfig
              {
                  public static void Register(HttpConfiguration config)
                  {
                      // Web API routes
                      config.MapHttpAttributeRoutes();
                                  config.Routes.MapHttpRoute(
                          name: "DefaultApi",
                          routeTemplate: "api/{controller}/{id}",
                          defaults: new { id = RouteParameter.Optional }
                      );
                  }
              }
          }
          
      • 加入 Startup.cs 檔案

        • 專案 按右鍵 –> Add –> New Item… –> Class
        • 加上 api route 註冊

          public void Configuration(IAppBuilder appbuilder)
          {
              var httpConfiguration = new HttpConfiguration();
              WebApiConfig.Register(httpConfiguration);
              appbuilder.UseWebApi(httpConfiguration);
          }
          
        • 完整程式碼

          using EmptyWebApi.App_Start;
          using System;
          using System.Web.Http;
                      namespace EmptyWebApi
          {
              public class Startup
              {
                  public void Configuration(IAppBuilder appbuilder)
                  {
                      var httpConfiguration = new HttpConfiguration();
                      WebApiConfig.Register(httpConfiguration);
                      appbuilder.UseWebApi(httpConfiguration);
                  }
              }
          }
          
      • AssemblyInfo.cs 中加上 Owin 啟動定義

        • 模式

          [assembly: OwinStartup(typeof({ProjectName}.Startup))]
          
        • 範例

          [assembly: OwinStartup(typeof(EmptyWebApi.Startup))]
          
      • 在 Controllers 資料夾新增 controller 即可

心得

建立 ASP.NET Web API 專案最少有以上幾種,尤其透過 Owin 的方式來建立,還可以使用 console 或是其他 host 方式,可以說是各有優缺點,可以依實際需求來選擇適合的建立方式

一般情況下使用 Empty Template with Web Api 是最平衡的,不僅保有快速產生專案架構的好處也不至於安裝太多無用 package

參考資訊

  1. Create Web API project:
  2. Web API for .NET Part 1: Creating Your First Project
  3. Can’t get the OWIN Startup class to run in IIS Express after renaming ASP.NET project file