From 5bcd31ab75a2624293e15baa9655fdaa1667806c Mon Sep 17 00:00:00 2001 From: Steve Smith Date: Thu, 2 Jul 2015 09:41:58 -0400 Subject: [PATCH] Initial progress on Request Features --- aspnet/fundamentals/request-features.rst | 143 ++++++++++++++++++++++- 1 file changed, 138 insertions(+), 5 deletions(-) diff --git a/aspnet/fundamentals/request-features.rst b/aspnet/fundamentals/request-features.rst index b896ff5686..acc4b33451 100644 --- a/aspnet/fundamentals/request-features.rst +++ b/aspnet/fundamentals/request-features.rst @@ -1,8 +1,141 @@ -.. include:: /../common/stub-topic.txt +Request Features +================ -|stub-icon| Request Features -============================ +By `Steve Smith`_ -.. include:: /../common/stub-notice.txt +Individual web server features related to how HTTP requests and responses are handled have been factored into separate interfaces, defined in the `HttpAbstractions `_ package. These abstractions are used by individual server implementations and middleware to create and modify the application's hosting pipeline. -.. _issue: https://github.com/aspnet/Docs/issues/293 +In this article: + - `Feature interfaces`_ + - `Feature collections`_ + +Feature interfaces +------------------ + +ASP.NET 5 defines a number of `Http Feature Interfaces `_, which are used by servers to identify which features they support. The most basic features of a web server are the ability to handle requests and return responses, as defined by the following feature interfaces: + +`IHttpRequestFeature `_ + Defines the structure of an HTTP request, including the protocol, path, QueryString, headers, and body. + +`IHttpResponseFeature `_ + Defines the structure of an HTTP response, including the status code, headers, and body of the response. + +`IHttpAuthenticationFeature `_ + Defines support for identifying users based on a ``ClaimsPrincipal`` and specifying an authentication handler. + +`IHttpUpgradeFeature `_ + Defines support for `HTTP Upgrades `_, which allow the client to specify which additional protocols it would like to use if the server wishes to switch protocols. + +`IHttpBufferingFeature `_ + Defines methods for disabling buffering of requests and/or responses. + +`IHttpConnectionFeature `_ + Defines properties for local and remote addresses and ports. + +`IHttpRequestLifetimeFeature `_ + Defines support for aborting connections. + +`IHttpSendFileFeature `_ + Defines a method for sending files asynchronously. + +`IHttpWebSocketFeature `_ + Defines an API for supporting web sockets. + +`IRequestIdentifierFeature `_ + Adds a property that can be implemented to uniquely identify requests. + +`ISessionFeature `_ + Defines ``ISessionFactory`` and ``ISession`` abstractions for supporting user sessions. + +`ITlsConnectionFeature `_ + Defines an API for retrieving client certificates. + +`ITlsTokenBindingFeature `_ + Defines methods for working with TLS token binding parameters. + + +Feature collections +------------------- + +The HttpAbstractions repository includes a FeatureModel package. Its main ingredient is the `FeatureCollection `_ type, which is used frequently by :doc:`servers` and their requests, as well as :doc:`middleware`, to identify which features they support. The `HttpContext `_ type defined in ``Microsoft.AspNet.Http.Abstractions`` (not to be confused with the ``HttpContext`` defined in ``System.Web``) provides an interface for getting and setting these features. The `OwinEnvironment `_ class provides some examples of how application code can verify the presence of needed features, and react accordingly. + +.. code-block:: c# + + public OwinEnvironment(HttpContext context) + { + if (context.GetFeature() == null) + { + throw new ArgumentException("Missing required feature: " + + nameof(IHttpRequestFeature) + ".", nameof(context)); + } + if (context.GetFeature() == null) + { + throw new ArgumentException("Missing required feature: " + + nameof(IHttpResponseFeature) + ".", nameof(context)); + } + // Code removed for brevity + } + +In the example above, ``OwinEnvironment``'s constructor verifies that the ``HttpContext`` it is working with has, at a minimum, support for HTTP requests and responses, and throws an exception otherwise. Similarly, support for features can be specified, as is done in the default constructor for `DefaultHttpContext `_: + +.. code-block:: c# + + public DefaultHttpContext() + : this(new FeatureCollection()) + { + SetFeature(new HttpRequestFeature()); + SetFeature(new HttpResponseFeature()); + } + +Since feature collections are mutable, even within the context of a request, middleware can be used to modify the collection and add support for additional features. + +Summary +------- + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file