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.

Request/Response Environment Host and Server Keys

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.

Environment keys specific to SystemWeb

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.

Environment keys specific to HttpListener

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.

IAppBuilder.Properties

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.

Capabilities

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.

WebSockets

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.

Sending files

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).