5.5 HTTP Cookies in ASP.NET Web API 5.5 ASP.NET Web API中的HTTP Cookie 本文引自：http://www.asp.net/web-api/overview/working-with-http/http-cookies By Mike W ...

5.5 HTTP Cookies in ASP.NET Web API
5.5 ASP.NET Web API中的HTTP Cookie

本文引自：http://www.asp.net/web-api/overview/working-with-http/http-cookies

By Mike Wasson|September 17, 2012
作者：Mike Wasson | 日期：2012-9-17

This topic describes how to send and receive HTTP cookies in Web API.
本主題描述如何在Web API中發送和接收HTTP Cookie。

Background on HTTP Cookies
HTTP Cookie的背景知識

This section gives a brief overview of how cookies are implemented at the HTTP level. For details, consult RFC 6265.
本小節給出在HTTP層面上如何實現Cookies，詳細參考RFC 6265。

A cookie is a piece of data that a server sends in the HTTP response. The client (optionally) stores the cookie and returns it on subsequet requests. This allows the client and server to share state. To set a cookie, the server includes a Set-Cookie header in the response. The format of a cookie is a name-value pair, with optional attributes. For example:
Cookie是伺服器在HTTP響應中發送的一個數據片段。客戶端存儲此Cookie（可選），併在後繼的請求中返回它。這讓客戶端和伺服器端可以共用狀態。為了設置一個Cookie，伺服器需要在響應中包含一個Set-Cookie報頭。Cookie的格式是一個“名字-值”對，並帶有一些可選屬性。例如：

Set-Cookie: session-id=1234567

Here is an example with attributes:
以下是一個帶有屬性的示例：

Set-Cookie: session-id=1234567; max-age=86400; domain=example.com; path=/;

To return a cookie to the server, the client includes a Cookie header in later requests.
為了將一個Cookie返回給伺服器，客戶端在後繼的請求中要包含一個Cookie報頭。

Cookie: session-id=1234567

An HTTP response can include multiple Set-Cookie headers.
一個HTTP響應可以包含多個Set-Cookie報頭。

Set-Cookie: session-token=abcdef;
Set-Cookie: session-id=1234567;

The client returns multiple cookies using a single Cookie header.
客戶端用一個單一的Cookie報頭返回多個Cookie。

Cookie: session-id=1234567; session-token=abcdef;

The scope and duration of a cookie are controlled by following attributes in the Set-Cookie header:
Cookie的範圍和期限是受Set-Cookie報頭的以下屬性控制的：

Domain: Tells the client which domain should receive the cookie. For example, if the domain is “example.com”, the client returns the cookie to every subdomain of example.com. If not specified, the domain is the origin server.
Domain（主域，或簡稱為域）：告訴客戶端哪一個域應當接收此Cookie。例如，如果Domain是“example.com”，那麼客戶端要把Cookie返回給example.com的每個子域。如果未指定，這個域便是原伺服器。
Path: Restricts the cookie to the specified path within the domain. If not specified, the path of the request URI is used.
Path（路徑）：將Cookie限制到主域的特定路徑。如果未指定，則使用請求URI的路徑。
Expires: Sets an expiration date for the cookie. The client deletes the cookie when it expires.
Expires（過期）：設置Cookie的過期日期。當Cookie過期時，客戶端刪除此Cookie。
Max-Age: Sets the maximum age for the cookie. The client deletes the cookie when it reaches the maximum age.
Max-Age（最大年齡）：設置Cookie的最大年齡。當Cookie達到最大年齡時，客戶端刪除此Cookie。

If both Expires and Max-Age are set, Max-Age takes precedence. If neither is set, the client deletes the cookie when the current session ends. (The exact meaning of “session” is determined by the user-agent.)
如果Expires和Max-Age都設置，則Max-Age優先。如果都未設置，在當前會話結束時，客戶端刪除Cookie。（“會話”的確切含意是由用戶代理確定的。）

However, be aware that clients may ignore cookies. For example, a user might disable cookies for privacy reasons. Clients may delete cookies before they expire, or limit the number of cookies stored. For privacy reasons, clients often reject “third party” cookies, where the domain does not match the origin server. In short, the server should not rely on getting back the cookies that it sets.
然而，要意識到客戶端可能會忽略Cookie。例如，一個用戶可能由於私人原因禁用了Cookies。客戶端可能會在過期之前刪除Cookies，或限制保存Cookies的數目。出於私有原因，客戶端通常會拒絕與源伺服器域不匹配的“第三方”Cookie。簡言之，伺服器不應該對取回它所設置的Cookie有依賴性。

Cookies in Web API
Web API中的Cookies

To add a cookie to an HTTP response, create a CookieHeaderValue instance that represents the cookie. Then call the AddCookies extension method, which is defined in the System.Net.Http. HttpResponseHeadersExtensions class, to add the cookie.
為了對一個HTTP響應添加Cookie，需要創建一個表示Cookie的CookieHeaderValue實例。然後調用AddCookies擴展方法（這是在System.Net.Http.HttpResponseHeadersExtensions類中定義的），以添加一個Cookie。

For example, the following code adds a cookie within a controller action:
例如，以下代碼在一個控制器動作中添加了一個Cookie：

public HttpResponseMessage Get() 
{ 
    var resp = new HttpResponseMessage(); 

    var cookie = new CookieHeaderValue("session-id", "12345"); 
    cookie.Expires = DateTimeOffset.Now.AddDays(1); 
    cookie.Domain = Request.RequestUri.Host; 
    cookie.Path = "/"; 

    resp.Headers.AddCookies(new CookieHeaderValue[] { cookie }); 
    return resp; 
}

Notice that AddCookies takes an array of CookieHeaderValue instances.
註意，AddCookies採用的是一個CookieHeaderValue實例數組。

To extract the cookies from a client request, call the GetCookies method:
為了提取客戶端請求的Cookie，需要調用GetCookies方法：

string sessionId = ""; 

CookieHeaderValue cookie = Request.Headers.GetCookies("session-id").FirstOrDefault(); 
if (cookie != null) 
{ 
    sessionId = cookie["session-id"].Value; 
}

A CookieHeaderValue contains a collection of CookieState instances. Each CookieState represents one cookie. Use the indexer method to get a CookieState by name, as shown.
CookieHeaderValue含有CookieState實例的集合。每個CookieState表示一個Cookie。使用索引器方法（指上述代碼最後一行的cookie["session-id"] — 譯者註）可以得到由名稱表示的CookieState，如上所示。

Structured Cookie Data
結構化的Cookie數據

Many browsers limit how many cookies they will store—both the total number, and the number per domain. Therefore, it can be useful to put structured data into a single cookie, instead of setting multiple cookies.
許多瀏覽器會限制其存儲的Cookie數 — Cookie總數和每個域的Cookie數。因此，把結構化的數據放入一個Cookie而不是設置多個Cookie可能是有用的。

RFC 6265 does not define the structure of cookie data.
RFC 6265並未定義Cookie數據的結構。

Using the CookieHeaderValue class, you can pass a list of name-value pairs for the cookie data. These name-value pairs are encoded as URL-encoded form data in the Set-Cookie header:
使用CookieHeaderValue類，你可以為Cookie數據傳遞一組“名字-值”對。這些“名字-值”對是在Set-Cookie報頭中作為URL編碼的表單數據進行編碼的：

var resp = new HttpResponseMessage();

var nv = new NameValueCollection(); 
nv["sid"] = "12345"; 
nv["token"] = "abcdef"; 
nv["theme"] = "dark blue"; 
var cookie = new CookieHeaderValue("session", nv);  

resp.Headers.AddCookies(new CookieHeaderValue[] { cookie });

The previous code produces the following Set-Cookie header:
上述代碼產生以下Set-Cookie報頭：

Set-Cookie: session=sid=12345&token=abcdef&theme=dark+blue;

The CookieState class provides an indexer method to read the sub-values from a cookie in the request message:
CookieState類提供了一個索引器方法，以讀取請求消息中Cookie的子值（Sub-values）：

string sessionId = ""; 
string sessionToken = ""; 
string theme = ""; 

CookieHeaderValue cookie = Request.Headers.GetCookies("session").FirstOrDefault(); 
if (cookie != null) 
{ 
    CookieState cookieState = cookie["session"]; 

    sessionId = cookieState["sid"]; 
    sessionToken = cookieState["token"]; 
    theme = cookieState["theme"]; 
}

Example: Set and Retrieve Cookies in a Message Handler
示例：在消息處理器中設置和接收Cookie

The previous examples showed how to use cookies from within a Web API controller. Another option is to use message handlers. Message handlers are invoked earlier in the pipeline than controllers. A message handler can read cookies from the request before the request reaches the controller, or add cookies to the response after the controller generates the response.
前述示例演示瞭如何使用來自Web API控制器的Cookie。另一種選擇是使用“消息處理器（Message Handler，也可以稱為消息處理程式 — 譯者註）”。消息處理器的調用在請求管線中要早於控制器。消息處理器可以在請求到達控制器之前讀取請求的Cookie，或者，在控制器生成響應之後將Cookie添加到響應（如下圖所示）。

The following code shows a message handler for creating session IDs. The session ID is stored in a cookie. The handler checks the request for the session cookie. If the request does not include the cookie, the handler generates a new session ID. In either case, the handler stores the session ID in the HttpRequestMessage.Properties property bag. It also adds the session cookie to the HTTP response.
以下代碼演示了一個創建會話ID的消息處理器。會話ID是存儲在一個Cookie中的。該處理器檢查請求的會話Cookie。如果請求不包含Cookie，處理器便生成一個新會話的ID。在任一情況下，處理器都會將這個會話ID存儲在HttpRequestMessage.Properties屬性包中。它也將這個會話Cookie添加到HTTP響應。

This implementation does not validate that the session ID from the client was actually issued by the server. Don't use it as a form of authentication! The point of the example is to show HTTP cookie management.
如果客戶端的會話ID實際是由伺服器發佈的，該實現不會驗證它。不要把它用於認證場合！本例的關鍵是演示HTTP Cookie的管理。

using System; 
using System.Linq; 
using System.Net; 
using System.Net.Http; 
using System.Net.Http.Headers; 
using System.Threading; 
using System.Threading.Tasks; 
using System.Web.Http; 

public class SessionIdHandler : DelegatingHandler 
{ 
    static public string SessionIdToken = "session-id"; 

    async protected override Task
  
    SendAsync( 
        HttpRequestMessage request, CancellationToken cancellationToken) 
    { 
        string sessionId; 
   

        // Try to get the session ID from the request; otherwise create a new ID. 
        // 嘗試獲取請求的會話ID，否則創建一個新的ID
        var cookie = request.Headers.GetCookies(SessionIdToken).FirstOrDefault(); 
        if (cookie == null) 
        { 
            sessionId = Guid.NewGuid().ToString(); 
        } 
        else  
        { 
            sessionId = cookie[SessionIdToken].Value; 
            try 
            { 
                Guid guid = Guid.Parse(sessionId); 
            } 
            catch (FormatException) 
            { 
                // Bad session ID. Create a new one. 
                // 劣質會話ID，創建一個新的
                sessionId = Guid.NewGuid().ToString(); 
            } 
        } 
   

        // Store the session ID in the request property bag. 
        // 在請求的屬性包中存儲會話ID 
        request.Properties[SessionIdToken] = sessionId; 
   

        // Continue processing the HTTP request. 
        // 繼續處理HTTP請求
        HttpResponseMessage response = await base.SendAsync(request, cancellationToken); 
   

        // Set the session ID as a cookie in the response message. 
        // 將會話ID設置為響應消息中的一個Cookie
        response.Headers.AddCookies(new CookieHeaderValue[] { 
            new CookieHeaderValue(SessionIdToken, sessionId)  
        }); 
   

        return response; 
    } 
}

A controller can get the session ID from the HttpRequestMessage.Properties property bag.
控制器可以通過HttpRequestMessage.Properties屬性包來獲取會話ID。

public HttpResponseMessage Get() 
{ 
    string sessionId = Request.Properties[SessionIdHandler.SessionIdToken] as string; 

    return new HttpResponseMessage() 
    { 
        Content = new StringContent("Your session ID = " + sessionId) 
    }; 
}

看完此文如果覺得有所收穫，請給個推薦

參考頁面：

http://www.yuanjiaocheng.net/webapi/action-method-returntype.html

http://www.yuanjiaocheng.net/webapi/web-api-reqresq-format.html

http://www.yuanjiaocheng.net/webapi/media-formatter.html

http://www.yuanjiaocheng.net/webapi/webapi-filters.html

http://www.yuanjiaocheng.net/webapi/create-crud-api-1.html

it學習資料