Refactoring of MVC packages

rynowak commented 9 years ago

What is it?

We've split up the MVC runtime features into a set of more granular packages based on what features they provide and what dependencies they have.

For most users there will be no change, and you should continue to use AddMvc() and UseMvc(...) in your startup code.

For the truly brave, there's now a configuration experience where you can start with a minimal MVC pipeline and add features to get a customized framework.

public void ConfigureServices(IServiceCollection services)
{
    services
        .AddMvcCore()
        .AddAuthorization()
        .AddJsonFormatters(j => j.Formatting = Formatting.Indented);
}

AddMvcCore() is an advanced experience that gives an application developer fine-grained control over what features are provided by MVC - you can mix and match dependencies with 3rd party frameworks, or avoid dependencies altogether that aren't needed.

For 3rd party library authors, this change allows you to target a more minimal set of dependencies if your requirements allow it.

Breaking Changes

Some options that used to be on MvcOptions have moved:

AntiforgeryOptions - use ConfigureAntiforgery(...)
ClientModelValidatorProviders - use ConfigureMvcViews(...)
HtmlHelperOptions - use ConfigureMvcViews(...)
SerializerSettings (JSON.NET) - use ConfigureMvcJson
ViewEngines - use ConfigureMvcViews(...)

If you're using AddMvc() we don't intend any changes in functionality other than the options changes.

If you're using AddMvcCore() configuring relevant options is more streamlined when adding a feature to the builder. The various Add<feature>(...) extensions methods take an Action<T> which will point you more directly to what's configurable for that feature.

    services
        .AddMvcCore()
        .AddJsonFormatters(SerializerSettings json => json.Formatting = Formatting.Indented);

Feedback

For anyone experimenting with AddMvcCore(...) we'd like to know about any surprises you encounter. Does something work that shouldn't? Does something break that should be available?

Regarding the layering, what chunks of features are the right size? What should be broken down smaller? Are things to granular?

Please include what you're trying to accomplish (what kind of site are you building) when leaving feedback. If you don't include this information, I'm just going to ask for it anyway :+1:

Description of Packages/Features

Here's an updated listing of each package, as well as what Add<feature>(...) methods are exposed by each.

Microsoft.AspNet.Mvc.Abstractions

Defines the core abstractions for MVC.

Microsoft.AspNet.Mvc.Core

Defines the implementation of the MVC runtime features. This is the only required reference to produce something that can serve requests using AddMvcCore(...).

AddMvcCore(...) - adds the minimal runtime services, and returns an IMvcBuilder to compose with other features.

Also

AddFormatterMappings(...) - adds support for maping file-extensions in the URL to content-types.

And

AddAuthorization(...) - adds support for discoving [Authorize(...)] attributes on controllers and actions and applying authorization policy. This must be used with an authorization middleware, and only adds support for MVC to recognize the attributes.

Microsoft.AspNet.Mvc.ApiExplorer

Defines the implementation of the IApiDescriptionProvider and other infrastructure for describing API endpoints in an application. Required if using Swashbuckle or a similar package.

AddApiExplorer(...) - adds the API Explorer services.

Microsoft.AspNet.Mvc.Cors

Defines the discovery and implementation of CORS policies to be applied at the action or controller level in MVC. Adding these services will allow MVC to recognize [EnableCors(...)] and [DisableCors] attributes.

AddCors(...) - adds the CORS services. Also adds the services from Microsoft.AspNet.Cors.Core to the service collection (like calling services.AddCors()).

Microsoft.AspNet.Mvc.DataAnnotations

Defines the ModelMetadata and validation support for the attributes defined in System.ComponentModel.DataAnnotations. Almost no request validation will take place without including these validators.

AddDataAnnotations(...) - adds model metadata and validation support for data annotations attributes.

Microsoft.AspNet.Mvc.Formatters.Json

Includes the JSON input and output formatters and also the JSON-patch input formatter - using Json.NET. Includes JsonResult.

AddJsonFormatters(...) - adds the JSON and JSON-patch formatters

Using AddJsonFormatters(...) isn't required to use JsonResult, but it's the recommended way to configure the shared SerializerSettings.

Microsoft.AspNet.Mvc.Formatters.Xml

Includes the XML input/output formatters for using XmlSerializer or DataContractSerializer.

For now for don't have an updated way of configuring these formatters :disappointed:. You'll have to use options.AddXmlDataContractSerializerFormatter(...) for DCS, and using XmlSerializer is somewhat more manual.

Microsoft.AspNet.Mvc.Localization

Includes services for producing localized text in Razor Views.

For now we don't have an updated way of configuring these services. Use services.AddMvcLocalization(...).

Microsoft.AspNet.Mvc.Razor

Includes services for using the Razor view engine implementation in MVC.

AddRazorViewEngine(...) - adds the Razor view engine. Calling AddRazorViewEngine(...) also calls AddViews(...) to add the basic view support and rendering features.

Microsoft.AspNet.Mvc.Razor.Host

Includes implementation of Razor code generation for MVC. Used as a dependency by Microsoft.AspNet.Mvc.Razor and by tooling.

Microsoft.AspNet.Mvc.TagHelpers

Includes implementations of TagHelpers for MVC. Used as a dependency by Microsoft.AspNet.Mvc.ViewFeatures.

Microsoft.AspNet.Mvc.ViewFeatures

Includes the definitions of view abstractions IView, IViewEngine and implementations of IHtmlHelper, View Components, IJsonHelper and other view rendering features. Includes the definition of Controller.

AddViews(...) - adds view rendering features. Will also add services for AddDataAnnocations(...) as well as Antiforgery, Data Protection, and Web Encoders.

Note that AddViews(...) on its own isn't complete, you will need to add a view engine to actually use views.

Microsoft.AspNet.Mvc.WebApiCompatShim

This is a compatibility package for porting WebAPI 2 applications. It doesn't mix and match with the AddMvcCore(...) experience.

Microsoft.AspNet.PageExecutionInstrumentation.Interfaces

Infrastructure for BrowserLink. Ignore this.

rynowak commented 9 years ago

In accordance with the discussion in #47 - this post is locked to avoid flooding watchers of this repo. See the corresponding issue aspnet/Mvc#2872 for feedback and discussion.

rynowak commented 9 years ago

I've been informed by @dougbu that I made a factual error:

~~Includes implementations of TagHelpers for MVC. Used as a dependency by Microsoft.AspNet.Mvc.ViewFeatures.~~

Updated description for TagHelpers:

Includes implementations of TagHelpers for MVC. This remains an optional package which you can just use. Requires AddViews().

aspnet / Announcements