具有 ASP.NET Core 的 Open Web Interface for .NET (OWIN)

  • 發行項

作者：Steve Smith 和 Rick Anderson

ASP.NET Core：

  • 支援 .NET 的開放式 Web 介面 (OWIN)。
  • 具有適用於 Microsoft.Owin.* (Katana) 程式庫的 .NET Core 相容取代項目。

OWIN 可讓 Web 應用程式獨立於網頁伺服器。 它會定義中介軟體要在管線中用來處理要求和相關聯回應的標準方式。 ASP.NET Core 應用程式和中介軟體可以與以 OWIN 為基礎的應用程式、伺服器及中介軟體進行交互操作。

OWIN 提供分離層，可讓兩個利用不同物件模型的架構一起使用。 Microsoft.AspNetCore.Owin 套件提供兩個配接器實作：

  • ASP.NET Core 至 OWIN
  • OWIN 至 ASP.NET Core

這可讓 ASP.NET Core 裝載在 OWIN 相容的伺服器/主機之上，或讓其他 OWIN 相容的元件在 ASP.NET Core 之上執行。

注意

使用這些配接器將伴隨效能成本增加。 僅使用 ASP.NET Core 元件的應用程式不應使用 Microsoft.AspNetCore.Owin 套件或配接器。

檢視或下載範例程式碼 \(英文\) (如何下載)

在 ASP.NET Core 管線中執行 OWIN 中介軟體

ASP.NET Core 的 OWIN 支援部署為 Microsoft.AspNetCore.Owin 套件的一部分。 您可以藉由安裝此套件，將 OWIN 支援匯入您的專案中。

OWIN 中介軟體符合 OWIN 規格，它需要設定 Func<IDictionary<string, object>, Task> 介面和特定的索引鍵 (例如 owin.ResponseBody)。 下列簡單的 OWIN 中介軟體會顯示 "Hello World"：

public Task OwinHello(IDictionary<string, object> environment)
{
    string responseText = "Hello World via OWIN";
    byte[] responseBytes = Encoding.UTF8.GetBytes(responseText);

    // OWIN Environment Keys: https://owin.org/spec/spec/owin-1.0.0.html
    var responseStream = (Stream)environment["owin.ResponseBody"];
    var responseHeaders = (IDictionary<string, string[]>)environment["owin.ResponseHeaders"];

    responseHeaders["Content-Length"] = new string[] { responseBytes.Length.ToString(CultureInfo.InvariantCulture) };
    responseHeaders["Content-Type"] = new string[] { "text/plain" };

    return responseStream.WriteAsync(responseBytes, 0, responseBytes.Length);
}

範例簽章會傳回 Task，並依照 OWIN 的要求接受 IDictionary<string, object>。

下列程式碼示範如何使用 UseOwin 擴充方法，將 OwinHello 中介軟體 (如上所示) 新增至 ASP.NET Core 管線。

public void Configure(IApplicationBuilder app)
{
    app.UseOwin(pipeline =>
    {
        pipeline(next => OwinHello);
    });
}

您可以設定在 OWIN 管線內進行其他動作。

注意

只能在第一次寫入回應資料流之前修改回應標頭。

注意

基於效能考量，建議您不要多次呼叫 UseOwin。 OWIN 元件如果群組在一起，其運作效能最佳。

app.UseOwin(pipeline =>
{
    pipeline(next =>
    {
        return async environment =>
        {
            // Do something before.
            await next(environment);
            // Do something after.
        };
    });
});

在以 OWIN 為基礎的伺服器上執行 ASP.NET Core 並使用其 WebSocket 支援

ASP.NET Core 如何利用以 OWIN 為基礎之伺服器功能的另一個範例是存取 WebSocket 等功能。 在上述範例中使用的 .NET OWIN 網頁伺服器支援內建的 Web 通訊端，供 ASP.NET Core 應用程式加以利用。 下列範例顯示的簡單 Web 應用程式支援 Web 通訊端，並透過 Websocket 回應傳送至伺服器的所有項目。

public class Startup
{
    public void Configure(IApplicationBuilder app)
    {
        app.Use(async (context, next) =>
        {
            if (context.WebSockets.IsWebSocketRequest)
            {
                WebSocket webSocket = await context.WebSockets.AcceptWebSocketAsync();
                await EchoWebSocket(webSocket);
            }
            else
            {
                await next();
            }
        });

        app.Run(context =>
        {
            return context.Response.WriteAsync("Hello World");
        });
    }

    private async Task EchoWebSocket(WebSocket webSocket)
    {
        byte[] buffer = new byte[1024];
        WebSocketReceiveResult received = await webSocket.ReceiveAsync(
            new ArraySegment<byte>(buffer), CancellationToken.None);

        while (!webSocket.CloseStatus.HasValue)
        {
            // Echo anything we receive
            await webSocket.SendAsync(new ArraySegment<byte>(buffer, 0, received.Count), 
                received.MessageType, received.EndOfMessage, CancellationToken.None);

            received = await webSocket.ReceiveAsync(new ArraySegment<byte>(buffer), 
                CancellationToken.None);
        }

        await webSocket.CloseAsync(webSocket.CloseStatus.Value, 
            webSocket.CloseStatusDescription, CancellationToken.None);
    }
}

OWIN 環境

您可以使用 HttpContext 建構 OWIN 環境。


   var environment = new OwinEnvironment(HttpContext);
   var features = new OwinFeatureCollection(environment);

OWIN 索引鍵

OWIN 仰賴 IDictionary<string,object> 物件在 HTTP 要求/回應交換中傳遞資訊。 ASP.NET Core 會實作下面所列的索引鍵。 請參閱主要規格、模組延伸和 OWIN Key Guidelines and Common Keys (OWIN 索引鍵指導方針和共用索引鍵)。

要求資料 (OWIN 1.0.0 版)

按鍵 值 (類型) 描述
owin.RequestScheme String
owin.RequestMethod String
owin.RequestPathBase String
owin.RequestPath String
owin.RequestQueryString String
owin.RequestProtocol String
owin.RequestHeaders IDictionary<string,string[]>
owin.RequestBody Stream

要求資料 (OWIN 1.1.0 版)

按鍵 值 (類型) 描述
owin.RequestId String 選擇性

回應資料 (OWIN 1.0.0 版)

按鍵 值 (類型) 描述
owin.ResponseStatusCode int 選擇性
owin.ResponseReasonPhrase String 選擇性
owin.ResponseHeaders IDictionary<string,string[]>
owin.ResponseBody Stream

其他資料 (OWIN 1.0.0 版)

按鍵 值 (類型) 描述
owin.CallCancelled CancellationToken
owin.Version String

共同索引鍵

按鍵 值 (類型) 描述
ssl.ClientCertificate X509Certificate
ssl.LoadClientCertAsync Func<Task>
server.RemoteIpAddress String
server.RemotePort String
server.LocalIpAddress String
server.LocalPort String
server.OnSendingHeaders Action<Action<object>,object>

SendFiles 0.3.0 版

按鍵 值 (類型) 描述
sendfile.SendAsync 請參閱委派簽章 每個要求

Opaque 0.3.0 版

按鍵 值 (類型) 描述
opaque.Version String
opaque.Upgrade OpaqueUpgrade 請參閱委派簽章
opaque.Stream Stream
opaque.CallCancelled CancellationToken

WebSocket 0.3.0 版

按鍵 值 (類型) 描述
websocket.Version String
websocket.Accept WebSocketAccept 請參閱委派簽章
websocket.AcceptAlt 非規格
websocket.SubProtocol String 請參閱 RFC6455 4.2.2 節的步驟 5.5
websocket.SendAsync WebSocketSendAsync 請參閱委派簽章
websocket.ReceiveAsync WebSocketReceiveAsync 請參閱委派簽章
websocket.CloseAsync WebSocketCloseAsync 請參閱委派簽章
websocket.CallCancelled CancellationToken
websocket.ClientCloseStatus int 選擇性
websocket.ClientCloseDescription String 選擇性

其他資源