-
Notifications
You must be signed in to change notification settings - Fork 332
OWIN Keys
The OWIN world revolves around IDictionary<string, object>, for both the primary environment dictionary as well as the various extensions like the IAppBuilder.Properties and the WebSocket environment. Several keys and values are defined in the core owin spec, as well as in the various extensions.
Katana implements all of the required and optional keys outlined in the OWIN spec, as well as some from the extensions and its own. Here are the keys implemented by the various Katana components, excluding those from the OWIN spec. Keep in mind that all keys not defined in the OWIN spec are optional, and may only be present under some conditions.
Key | Value | SystemWeb | HttpListener | Hosting | Description |
---|---|---|---|---|---|
host.TraceOutput | TextWriter | x | x | Available to the application for writing out low volume debug statements. | |
host.AppName | string | x | x | A name describing this instance of the application. This may be derived from the entry point type name (Startup). | |
host.AppMode | string | x | x | The value 'development' to indicate that this application is being run in development mode. | |
host.OnAppDisposing | CancellationToken | x | x | Signaled when the application is preparing to shut down. | |
server.User | IPrincipal | x | x | The user identity. May be anonymous or null | |
server.OnSendingHeaders | Action<<Action, object> | x | x | An event that fires just before the response headers are sent back to the client. The object passed in is a state object that will be returned passed to your callback. This may not fire for error responses. | |
server.Capabilities | IDictionary<string, object> | x | x | A collection that describes the capabilities of the server. This may be augmented by middleware. The content is defined in a separate table below. | |
server.RemoteIpAddress | string | x | x | The IP address of the caller. Note this is only the intimidate caller and may not be the address of the original caller in cases where proxies are involved. | |
server.RemotePort | string | x | x | The port of the caller. | |
server.LocalIpAddress | string | x | x | The local IP address for this connection. | |
server.LocalPort | string | x | x | The local port for this connection | |
server.IsLocal | bool | x | x | Indicates if the request has come from the same machine (e.g. the remote and local IP addresses match) | |
ssl.ClientCertificate | X509Certificate | x | x | The client certificate, if any was provided. | |
ssl.LoadClientCertAsync | Func | x | x | Asynchronously load the client's certificate. | |
ssl.ClientCertificateErrors | Exception | x | Any errors encountered while processing the client's certificate. | ||
sendfile.SendAsync | Func<string, long, long?, CancellationToken, Task> | x | An API used to transmit a file efficiently as part of the response body. See the SendFile OWIN extension spec. | ||
websocket.Accept | * | x | x | See the WebSocket OWIN extension spec. Available on Windows 8 and later. |
Key | Value | Description |
---|---|---|
server.DisableResponseBuffering | Action | Disables response buffering for this request. This will result in the server sending Transfer-Encoding: chunked. Must be called before the last write to have any affect. |
systemweb.DisableResponseCompression | Action | Removes the request's Accept-Encoding header to force IIS to not compress the response. |
System.Web.HttpContextBase | HttpContextBase | The underlying request context. |
System.Web.Routing.RequestContext | RequestContext | The underlying routing context. |
Key | Value | Description |
---|---|---|
System.Net.HttpListenerContext | HttpListenerContext | The underlying request context. |
System.Net.HttpListener | HttpListener | The underlying server instance. |
Microsoft.Owin.Host.HttpListener.OwinHttpListener | OwinHttpListener | The OWIN adapter around the HttpListener server instance. |
The IAppBulder.Properties IDictionary<string, object> is used to share application config information during start-up.
Key | Value | SystemWeb | HttpListener | Hosting | Description |
---|---|---|---|---|---|
server.Capabilities | IDictionary<string, object> | x | x | A collection that describes the capabilities of the server. This may be augmented by middleware. The content is defined in a separate table below. | |
host.Addresses | IList<IDictionary<string, object>> | x | Addresses the server will accept requests on. The following keys are defined with string values: scheme, host, port, path. | ||
host.TraceOutput | TextWriter | x | x | A debug log output destination. | |
host.AppName | string | x | x | A name describing this instance of the application. This may be derived from the entry point type name (Startup). | |
host.AppMode | string | x | x | The value 'development' to indicate that this application is being run in development mode. | |
host.OnAppDisposing | CancellationToken | x | x | Signaled when the application is preparing to shut down. | |
System.Net.HttpListener | HttpListener | x | A configurable instance that will be used to listen for requests. | ||
Microsoft.Owin.Host.HttpListener.OwinHttpListener | OwinHttpListener | x | The OWIN adapter around the HttpListener server instance. |
Platform capabilities are announced as described in section 5 of the Common Keys spec. This IDictionary is included in both the startup IAppBuilder.Properties, as well as the per-request environment dictionary. Capabilities currently listed by SystemWeb and HttpListener include WebSockets and SendFile, as outlined below. Also included is the key "server.Name" with a string identifying the name and version of the server for debugging purposes.
The .NET 4.5 versions of HttpListener and SystemWeb implement WebSockets as described in version 0.4.0 of the OWIN WebSocket extension spec. In addition to the keys defined in the spec, the following key is also added to the websocket environment dictionary:
Key | Value |
---|---|
System.Net.WebSockets.WebSocketContext | The underlying WebSocket context. This may be used directly in place of the OWIN Func abstractions. |
HttpListener v2.1.0 also accepts the following keys in the input properties dictionary:
Key | Value |
---|---|
websocket.ReceiveBufferSize | An int representing the internal receive buffer size. |
websocket.KeepAliveInterval | A TimeSpan representing the keep-alive ping interval. |
websocket.Buffer | An ArraySegment representing a pre-allocated buffer to use with this instance. |
SystemWeb implements version 0.3.0 of the OWIN SendFile extension spec, used to efficiently transmit the contents of a file as part of the message response body. The StaticFileMiddleware uses this capability if available. The SendFileMiddleware can be used to provide fallback support for the same extension if the underlying server does not support it directly (i.e. HttpListener).