ASP.NET Web API 應用教程（一） ——資料流使用

 

相信已經有很多文章來介紹ASP.Net Web API 技術，本系列文章主要介紹如何使用資料流，HTTPS，以及可擴充套件的Web API 方面的技術，系列文章主要有三篇內容。

主要內容如下：

I  資料流

II 使用HTTPS

III 可擴充套件的Web API 文件

 

專案環境要求

• VS 2012（SP4）及以上，
• .Net 框架4.5.1
• Nuget包,可在packages.config 檔案中查尋

本文涉及的知識點

1. ActionFilter
2. AuthorizationFilter
3. DelegateHandler
4. Different Web API routing 屬性
5. MediaTypeFormatter
6. OWIN
7. Self Hosting
8. Web API 文件及可擴充套件功能

.Net 框架

1. Async/Await
2. .NET reflection
3. Serialization
4. ASP.NET Web API/MVC Error handling
5. IIS ,HTTPS 及Certificate
6. 設計準則及技術

前言

 

自從ASP.NET MVC 4之後.Net 框架開始支援ASP.NET Web API ，ASP.NET Web API 基於HTTP 協議建立的，是構建 RESTful 服務和處理資料的理想平臺，旨在使用HTTP 技術實現對多平臺的支援。

ASP.NET Web API 以request-response 的訊息轉換模式為主，客戶端向伺服器傳送請求，伺服器端響應客戶端請求。響應可同步或非同步。

 個人認為使用Web API建立應用需要注意的三個關鍵點：

• 採用服務及方法滿足的目標
• 每個方法的輸入，如請求
• 每個方法的輸出，如響應

通常情況下，Asp.Net Web API 定義method語法與HTTP方法一一對應的，如自定義方法名 GetPysicians()，則與HTTP中Get 方法匹配。下圖是常用匹配表。

 

但是此方法在很多情況下，並不實用，假如你想在單個API controller 類中定義多個Get 或Post 方法，在這種情況下，需要定義包含action 的路徑，將Action 作為URI 的一部分。以下是配置程式碼：

public static void Register(HttpConfiguration config)
{
    // Web API configuration and services
    // Web API routes
     config.MapHttpAttributeRoutes();

     config.Routes.MapHttpRoute(name: "PhysicianApi",
                routeTemplate: "{controller}/{action}/{id}",
                defaults: new { id = RouteParameter.Optional });
}

但是此方法不足以應對所有情況，如果想實現從中央倉庫刪除檔案，並且想呼叫同一個方法來獲取檔案，這種情況下，Web API 框架需要偽裝Get 及Delete對應的HTTP 方法屬性。如圖所示：

RemoveFile 方法可被Delete(HttpDelete) 或 Get(HttpGet)方法同時呼叫，從某種程度來說，HTTP 方法使開發人員命名 API“方法”變得簡單而標準。

Web API框架也提供了一些其他功能來處理路徑方面的問題，與MVC 的路徑處理方法相似。因此可定義不同型別的Action方法。 

資料流

網路App 最常見的執行操作就是獲取資料流。ASP.NET Web API 能夠處理客戶端與伺服器端傳輸的重量級的資料流，資料流可來源於目錄檔案，也可是資料庫中的二進位制檔案。本文主要介紹兩種方法“Download”和“Upload”實現資料流相關的功能，Download是從伺服器下載資料操作，而Upload則是上傳資料到伺服器。

相關專案

• WebAPIDataStreaming
• WebAPIClient
• POCOLibrary

在對程式碼解釋之前，首先來了解如何配置IIS（7.5）和Web API 服務Web.Config 檔案。

1. 保證Downloads/Uploads 涉及的檔案具有讀寫許可權。

2. 保證有足夠容量的內容或因公安空間處理大檔案。

3. 如果檔案較大

a. 配置Web.Config 檔案時，保證 maxRequestLength 時響應時間 executionTimeout 合理。具體的值主要依賴於資料大小，允許一次性上傳的最大資料為2 GB

b. 保證 maxAllowedContentLength 在requestFiltering部分配置下正確設定，預設值為30MB，最大值4GB

一旦完成預先配置，那麼建立資料流服務就非常簡單了，首先 需要定義檔案流“ApiController”，如下：

/// <summary>
/// File streaming API
/// </summary>
[RoutePrefix("filestreaming")]
[RequestModelValidator]
public class StreamFilesController : ApiController
{
    /// <summary>
    /// Get File meta data
    /// </summary>
    /// <param name="fileName">FileName value</param>
    /// <returns>FileMeta data response.</returns>
    [Route("getfilemetadata")]
    public HttpResponseMessage GetFileMetaData(string fileName)
    {
        // .........................................
        // Full code available in the source control
        // .........................................

    }

    /// <summary>
    /// Search file and return its meta data in all download directories
    /// </summary>
    /// <param name="fileName">FileName value</param>
    /// <returns>List of file meta datas response</returns>
    [HttpGet]
    [Route("searchfileindownloaddirectory")]
    public HttpResponseMessage SearchFileInDownloadDirectory(string fileName)
    {
        // .........................................
        // Full code available in the source control
        // .........................................
    }

    /// <summary>
    /// Asynchronous Download file
    /// </summary>
    /// <param name="fileName">FileName value</param>
    /// <returns>Tasked File stream response</returns>
    [Route("downloadasync")]
    [HttpGet]
    public async Task<HttpResponseMessage> DownloadFileAsync(string fileName)
    {
        // .........................................
        // Full code available in the source control
        // .........................................
    }

    /// <summary>
    /// Download file
    /// </summary>
    /// <param name="fileName">FileName value</param>
    /// <returns>File stream response</returns>
    [Route("download")]
    [HttpGet]
    public HttpResponseMessage DownloadFile(string fileName)
    {
        // .........................................
        // Full code available in the source control
        // .........................................
    }

    /// <summary>
    /// Upload file(s)
    /// </summary>
    /// <param name="overWrite">An indicator to overwrite a file if it exist in the server</param>
    /// <returns>Message response</returns>
    [Route("upload")]
    [HttpPost]
    public HttpResponseMessage UploadFile(bool overWrite)
    {
        // .........................................
        // Full code available in the source control
        // .........................................
    }

    /// <summary>
    /// Asynchronous Upload file
    /// </summary>
    /// <param name="overWrite">An indicator to overwrite a file if it exist in the server</param>
    /// <returns>Tasked Message response</returns>
    [Route("uploadasync")]
    [HttpPost]
    public async Task<HttpResponseMessage> UploadFileAsync(bool overWrite)
    {
        // .........................................
        // Full code available in the source control
        // .........................................
    }
}

Download 服務方法首先需要確認請求的檔案是否存在，如果未找到，則返回錯誤提示“file is not found”,如果找到此檔案，內容則轉換為位元組附加到響應物件，為“application/octet-stream” MIMI 內容型別。

/// <summary>
/// Download file
/// </summary>
/// <param name="fileName">FileName value<param>
/// <returns>File stream response<returns>
[Route("download")]
[HttpGet]
public HttpResponseMessage DownloadFile(string fileName)
{
    HttpResponseMessage response = Request.CreateResponse();
    FileMetaData metaData = new FileMetaData();
    try
    {
        string filePath = Path.Combine(this.GetDownloadPath(), @"\", fileName);
        FileInfo fileInfo = new FileInfo(filePath);

        if (!fileInfo.Exists)
        {
            metaData.FileResponseMessage.IsExists = false;
            metaData.FileResponseMessage.Content = string.Format("{0} file is not found !", fileName);
            response = Request.CreateResponse(HttpStatusCode.NotFound, metaData, new MediaTypeHeaderValue("text/json"));
        }
        else
        {
            response.Headers.AcceptRanges.Add("bytes");
            response.StatusCode = HttpStatusCode.OK;
            response.Content = new StreamContent(fileInfo.ReadStream());
            response.Content.Headers.ContentDisposition = new ContentDispositionHeaderValue("attachment");
            response.Content.Headers.ContentDisposition.FileName = fileName;
            response.Content.Headers.ContentType = new MediaTypeHeaderValue("application/octet-stream");
            response.Content.Headers.ContentLength = fileInfo.Length;
        }
    }
    catch (Exception exception)
    {
        // Log exception and return gracefully
        metaData = new FileMetaData();
        metaData.FileResponseMessage.Content = ProcessException(exception);
        response = Request.CreateResponse(HttpStatusCode.InternalServerError, metaData, new MediaTypeHeaderValue("text/json"));
    }
    return response;
}

Upload服務方法則會在multipart/form-data MIMI 內容型別執行，首先會檢測HTTP 請求的內容型別是否是多主體，如果是，則對比內容長度是否超過最大尺寸，如果沒有超過，則開始上傳內容，當操作完成之後，則提示相應的資訊。

程式碼片段如下：

/// <summary>
/// Upload file(s)
/// </summary>
/// <param name="overWrite">An indicator to overwrite a file if it exist in the server.</param>
/// <returns>Message response</returns>
[Route("upload")]
[HttpPost]
public HttpResponseMessage UploadFile(bool overWrite)
{
    HttpResponseMessage response = Request.CreateResponse();
    List<FileResponseMessage> fileResponseMessages = new List<FileResponseMessage>();
    FileResponseMessage fileResponseMessage = new FileResponseMessage { IsExists = false };

    try
    {
        if (!Request.Content.IsMimeMultipartContent())
        {
            fileResponseMessage.Content = "Upload data request is not valid !";
            fileResponseMessages.Add(fileResponseMessage);
            response = Request.CreateResponse(HttpStatusCode.UnsupportedMediaType, fileResponseMessages, new MediaTypeHeaderValue("text/json"));
        }

        else
        {
            response = ProcessUploadRequest(overWrite);
        }
    }
    catch (Exception exception)
    {
        // Log exception and return gracefully
        fileResponseMessage = new FileResponseMessage { IsExists = false };
        fileResponseMessage.Content = ProcessException(exception);
        fileResponseMessages.Add(fileResponseMessage);
        response = Request.CreateResponse(HttpStatusCode.InternalServerError, fileResponseMessages, new MediaTypeHeaderValue("text/json"));

    }
    return response;
}

/// <summary>
/// Asynchronous Upload file
/// </summary>
/// <param name="overWrite">An indicator to overwrite a file if it exist in the server.<param>
/// <returns>Tasked Message response</returns>
[Route("uploadasync")]
[HttpPost]
public async Task<HttpResponseMessage> UploadFileAsync(bool overWrite)
{
    return await new TaskFactory().StartNew(
       () =>
       {
           return UploadFile(overWrite);
       });
}

/// <summary>
/// Process upload request in the server
/// </summary>
/// <param name="overWrite">An indicator to overwrite a file if it exist in the server.</param>
/// </returns>List of message object</returns>
private HttpResponseMessage ProcessUploadRequest(bool overWrite)
{
    // .........................................
    // Full code available in the source control
    // .........................................
}

呼叫download 及 upload 檔案方法是控制檯應用，App 假定檔案流服務通過HttpClient和相關類。基本下載檔案程式碼，建立下載HTTP 請求物件。

/// <summary>
/// Download file
/// </summary>
/// <returns>Awaitable Task object</returns>
private static async Task DownloadFile()
{
    Console.ForegroundColor = ConsoleColor.Green;
    Console.WriteLine("Please specify file name  with extension and Press Enter :- ");
    string fileName = Console.ReadLine();
    string localDownloadPath = string.Concat(@"c:\", fileName); // the path can be configurable
    bool overWrite = true;
    string actionURL = string.Concat("downloadasync?fileName=", fileName);

    try
    {
        Console.WriteLine(string.Format("Start downloading @ {0}, {1} time ",
            DateTime.Now.ToLongDateString(),
            DateTime.Now.ToLongTimeString()));


        using (HttpClient httpClient = new HttpClient())
        {
            httpClient.BaseAddress = baseStreamingURL;
            HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Get, actionURL);

            await httpClient.SendAsync(request, HttpCompletionOption.ResponseHeadersRead).
                ContinueWith((response)
                    =>
                {
                    Console.WriteLine();
                    try
                    {
                        ProcessDownloadResponse(localDownloadPath, overWrite, response);
                    }
                    catch (AggregateException aggregateException)
                    {
                        Console.ForegroundColor = ConsoleColor.Red;
                        Console.WriteLine(string.Format("Exception : ", aggregateException));
                    }
                });
        }
    }
    catch (Exception ex)
    {
        Console.ForegroundColor = ConsoleColor.Red;
        Console.WriteLine(ex.Message);
    }
}


/// <summary>
/// Process download response object
/// </summary>
/// <param name="localDownloadFilePath">Local download file path</param>
/// <param name="overWrite">An indicator to overwrite a file if it exist in the client.</param>
/// <param name="response">Awaitable HttpResponseMessage task value</param>
private static void ProcessDownloadResponse(string localDownloadFilePath, bool overWrite,
    Task<HttpResponseMessage> response)
{
    if (response.Result.IsSuccessStatusCode)
    {
        response.Result.Content.DownloadFile(localDownloadFilePath, overWrite).
            ContinueWith((downloadmessage)
                =>
            {
                Console.ForegroundColor = ConsoleColor.Green;
                Console.WriteLine(downloadmessage.TryResult());
            });
    }
    else
    {
        ProcessFailResponse(response);
    }
}

 

注意上述程式碼中HttpClient 物件傳送請求，並等待響應傳送Header內容（HttpCompletionOption.ResponseHeadersRead ）。而不是傳送全部的響應內容檔案。一旦Response header 被讀，則執行驗證，一旦驗證成功，則執行下載方法。

以下程式碼呼叫upload 檔案流，與下載方法類似，建立多主體表單資料，併傳送給伺服器端。

/// <summary>
/// Upload file
/// </summary>
/// <returns>Awaitable task object</returns>
private static async Task UploadFile()
{
    try
    {
        string uploadRequestURI = "uploadasync?overWrite=true";

        MultipartFormDataContent formDataContent = new MultipartFormDataContent();

        // Validate the file and add to MultipartFormDataContent object
        formDataContent.AddUploadFile(@"c:\nophoto.png");
        formDataContent.AddUploadFile(@"c:\ReadMe.txt");

        if (!formDataContent.HasContent()) // No files found to be uploaded
        {
            Console.ForegroundColor = ConsoleColor.Red;
            Console.Write(formDataContent.GetUploadFileErrorMesage());
            return;
        }
        else
        {
            string uploadErrorMessage = formDataContent.GetUploadFileErrorMesage();
            if (!string.IsNullOrWhiteSpace(uploadErrorMessage)) // Some files couldn't be found
            {
                Console.ForegroundColor = ConsoleColor.Red;
                Console.Write(uploadErrorMessage);
            }

            HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, uploadRequestURI);
            request.Content = formDataContent;

            using (HttpClient httpClient = new HttpClient())
            {
                Console.ForegroundColor = ConsoleColor.Green;
                Console.WriteLine(string.Format("Start uploading @ {0}, {1} time ",
                DateTime.Now.ToLongDateString(),
                DateTime.Now.ToLongTimeString()));

                httpClient.BaseAddress = baseStreamingURL;
                await httpClient.SendAsync(request).
                      ContinueWith((response)
                          =>
                          {
                              try
                              {
                                  ProcessUploadResponse(response);
                              }
                              catch (AggregateException aggregateException)
                              {
                                  Console.ForegroundColor = ConsoleColor.Red;
                                  Console.WriteLine(string.Format("Exception : ", aggregateException));
                              }
                          });
            }
        }
    }
    catch (Exception ex)
    {
        Console.ForegroundColor = ConsoleColor.Red;
        Console.WriteLine(ex.Message);
    }
}

/// <summary>
/// Process download response object
/// </summary>
/// <param name="response">Awaitable HttpResponseMessage task value</param>
private static void ProcessUploadResponse(Task<HttpResponseMessage> response)
{
    if (response.Result.IsSuccessStatusCode)
    {
        string uploadMessage = string.Format("\nUpload completed @ {0}, {1} time ",
                    DateTime.Now.ToLongDateString(),
                    DateTime.Now.ToLongTimeString());
        Console.ForegroundColor = ConsoleColor.Green;
        Console.WriteLine(string.Format("{0}\nUpload Message : \n{1}", uploadMessage,
            JsonConvert.SerializeObject(response.Result.Content.ReadAsAsync<List<FileResponseMessage>>().TryResult(), Formatting.Indented)));
    }
    else
    {
        ProcessFailResponse(response);
    }
}

 

資料流專案由可擴充套件類和方法組成，本文就不再詳述。下篇文章中將介紹“使用HTTPS 開發專案”

資料流是資料傳輸中的重要部分，學習了本節內容有助於大家更好地進行ASP.NET的開發。當然，還可以藉助一些開發工具來助力開發過程。ComponentOne Studio for ASP.NET 提供了一整套完備的開發工具包，用於在各種瀏覽器中建立和設計具有現代風格的Web應用程式。

 

下載原始碼

原文連結：http://www.codeproject.com/Articles/838274/Web-API-Thoughts-of-Data-Streaming#Hist