Breaking changes list and migration guidance are needed

[evil-shrike]

It is commonly claimed that MVC 6 is "almost the same as MVC 5". I read and heard this in many videos on AspNet5\Mvc6. But the more I dive into it the more different it seems. Similar but different. Converting an Mvc5\WebApi2 app onto AspNet5\Mvc6 is a pain. There're some guidances on the Internet how cool creating Mvc6 apps is. But I found nothing about how to migrate existing code onto Mvc6 (and AspNet5 in general). The things are even worse due to terrible branding - "ASP.NET 5 MVC 6" (considering we have "MVC 5" already). Just google for "Migrating onto ASP.NET 5 MVC 6".

So it's highly desirable to provide some list of breaking changes. It should consist of two parts at least: Api compatibility and UseCases compatibility. Let me clarify. Api compatibility is a list of changes in types, methods and so on. UseCases compatibility is a list of common use-cases in developing apps which are changed. For example:

• register a startup hook
  • before: via assembly-level attribute WebActivator.PreApplicationStartMethod
  • now: Startup class
• configuring Mvc\WebApi components
  • before: all components were in HttpConfiguration (Filters, Formatters, MessageHandlers, Services)
  • now: setup MvcOptions object in callback passed to IServiceCollection.Configure<MvcOptions>()
• configuring Json formatter
  • before: via HttpConfiguration.Formatters.JsonFormatter.SerializerSettings
  • now: find JsonInputFormatter in MvcOptions.InputFormatters or JsonOutputFormatter in MvcOptions.OutputFormatters (there're two formatters now - input and output)
• passing objects with HttRequestMessage
  • before: it was common to put arbitrary objects into HttRequestMessage.Properties (usually with extension-methods like request.SetUserRights() where SetUserRights just put an object into request.Properties[HttpPropertyKey.UserRights] ).
  • now: WHAT?
• IoC\DI
  • before: register IDependencyResolver implementations (there were two ones: in System.Web.Http and in System.Web.Mvc) in HttpConfiguration.Services
  • now: there're two options: remove usage of your 3rd-party DI completely (as AspNet5 now provides a DI-container by default) or provider a custom implementation of IServiceProvider to IApplicationBuilder.ApplicationServices in Startup.Configure)
• BrowserCapabilities - understand what browser is being used
  • before: using HttpBrowserCapabilitiesBase instance from Request.Browser
  • now: WHAT?
• Api controller working with raw Http-types
  • before: create an ApiController's method with a arg of HttpRequstMessage and return type of HttpResponseMessage. To create response: Request.CreateResponse. Easy.
  • now: WHAT?
• Api controller returns a fine-tuned http-response (for cache controlling)
  • before: create a HttpRequestMessage and assign Headers (typed!):

var response = Request.CreateResponse(HttpStatusCode.OK);
response.Content = new StringContent(content);
response.Content.Headers.ContentType = new MediaTypeHeaderValue("text/cache-manifest");
response.Headers.CacheControl = new CacheControlHeaderValue {NoCache = true, Public = true};
response.Headers.ETag = new EntityTagHeaderValue("\"" + etag + "\"");

• • now: WHAT?
• Api controller returns a non-OK response with payload
  • before: return Request.CreateResponse(statusCode, someObj)
  • now: WHAT? I can create new HttpStatusCodeResult((int)statusCode) but how to pass the payload?
• ValueProvider (applicable?)
• content negotiation (applicable?)

and so on..

I personally encountered with the following "surprises" - disappearing of types/methods/properties

• Mvc: disappeared type WebViewPage
• Mvc: disappeared type HttpRequestBase
• Mvc: disappeared type HttpCookieCollection
• WebApi: disappeared type DelegatingHandler
• WebApi: typed access to HttpRequestMessage.Headers (like request.Headers.AcceptLanguage)
• disappeared property HttpRequest.Properties
• disappeared method HttpRequest.CreateResponse
• Razor: disappeared @RenderPage
• AspNet: disappeared type HttpBrowserCapabilitiesBase (it's type of Request.Browser property)
• AspNet: why does HttpStatusCodeResult not use HttpStatusCode enum?
• What happened with System.Net.Http ? Can I use types from it (like FormDataCollection) in AspNet5 apps?
• WebApi: disappeared types ValueProvider\RouteDataValueProviderFactory
• WebApi: Request.CreateResponse(statusCode, someObj)

[Eilon]

@evil-shrike indeed there are quite a few differences between MVC 5 and 6, especially concerning Web API.

We have some brand new documentation that is in progress and hosted here: http://aspnet.readthedocs.org/en/latest/

In particular, these articles:

• Migrating From ASP.NET MVC 5 to MVC 6
• Migrating Configuration From ASP.NET MVC 5 to MVC 6
• Migrating From ASP.NET Web API 2 to MVC 6

Please have a look through those documents and if you feel there is still content missing, please file a bug on https://github.com/aspnet/Docs/issues (though some bugs are already opened, so please take a quick look at those too and add any applicable comments).

[evil-shrike]

Thanks! Sorry I didn't find that resource. I think it'd make sense to put the link in https://github.com/aspnet/Home#documentation-and-further-learning

[Eilon]

Done, thanks!

[sulhome]

these links are dead

[Eilon]

@sulhome sorry about that! Not too long ago we moved the documentation to a new site, but with the same content (though much of it has been updated).

The main migration page moved to Migration, which has sub topics for:

• Migrating From ASP.NET MVC 5 to MVC 6
• Migrating Configuration From ASP.NET MVC 5 to MVC 6
• Migrating From ASP.NET Web API 2 to MVC 6
• Migrating Authentication and Identity From ASP.NET MVC 5 to MVC 6

[sulhome]

@Eilon thank you

[sulhome]

@evil-shrike please check this question on stackoverflow https://stackoverflow.com/questions/33178983/how-to-create-a-response-message-and-add-content-string-to-it-in-asp-net-5-mvc