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 開發專案”

下載原始碼

原文連結：