Microsoft.AspNetCore.Razor refactoring and breaking changes

[rynowak]

Microsoft.AspNetCore.Razor refactoring and breaking changes

As usual, announcement threads are locked to prevent spam. Please use the discussion topic here for feedback and questions. Thanks!

Summary

We're making some significant changes to the Microsoft.AspNetCore.Razor and Microsoft.AspNetCore.Razor.Runtime for ASP.NET Core 2.0.0 as part of the Razor re-engineering work we conducting. We've discussed the re-engineering work previously here but now we're ready to announce some of the breaking changes that will come from this effort.

Microsoft.AspNetCore.Razor will only contain the small set of types used for authoring Tag Helpers. This assembly will no longer contain the Razor Parser and Code Generator.

Microsoft.AspNetCore.Razor.Runtime will only contain the set of types used for authoring Tag Helpers. This assembly will no longer contain the infrastructure and types used to discover Tag Helpers.

Microsoft.AspNetCore.Razor.Evolution (a new assembly) will contain the Razor Parser and Code Generator. This name is not final and will change to something less whimsical before we release 2.0.0.

Impact

If you have written Tag Helpers against ASP.NET Core 1.0.0 there is a small chance that you will be affected by this change. It is our intent (within reason) that the 2.0.0 Microsoft.AspNetCore.Razor and
Microsoft.AspNetCore.Razor.Runtime assemblies will be binary-and-source-compatible with the API surface used to write Tag Helpers (mostly the Microsoft.AspNetCore.Razor.TagHelpers namespace). You should continue to reference the Microsoft.AspNetCore.Razor.Runtime package in your Tag Helpers - this will transitively pull in Microsoft.AspNetCore.Razor.

If you have written extensibility against Microsoft.AspNetCore.Razor or are re-hosting Razor for use in a templating engine, you should expect minor changes. You should reference Microsoft.AspNetCore.Razor.Evolution, where you will find all of the functionality that was removed from Microsoft.AspNetCore.Razor and Microsoft.AspNetCore.Razor.Runtime. APIs have changed, but you'll likely find conceptually-equivalent functionality in the new package. See the RazorPageGenerator for an example of using the new version of RazorTemplateEngine. Much of the extensibility surface is in flux here, so while you might want to take a look, you're better off sticking with 1.1.X until we're closer to release.

Rationale

We wrote a bit about this earlier here, and we perhaps now share a bit more.

We're doing a lot of work right now in Razor to improve the design and engineering of the Razor compiler and tooling. I want to emphasize that this release doesn't make language changes to Razor, and is entirely focused on improving the factoring, APIs, and fundamentals. In addition to the new Microsoft.AspNetCore.Razor.Evolution (real name pending) package, we're also builiding language services and runtime features that more closely leverage Roslyn. We're excited by the enthusiasm around Tag Helpers and we're making an investment in our future.

Part of this work is the factoring of the assemblies. We don't want the code generator and the APIs targeted by the code generator to be a single unit. We want to keep the set of dependencies for the compiler as thin as possible so it can easily live in tooling/VS. It also doesn't make much sense for libraries of tag helpers to reference the compiler. We also wanted to preserve as much compatibility for existing tag helper code. For anyone extending Razor or using the template engine, it's likely you'd be broken by our API changes in some small way, so moving to another assembly is small potatoes. This is how we settled on final split.

As usual, announcement threads are locked to prevent spam. Please use the discussion topic here for feedback and questions. Thanks!

[rynowak]

As usual, announcement threads are locked to prevent spam. Please use the discussion topic here for feedback and questions. Thanks!

[rynowak]

An update here, we've renamed Microsoft.AspNetCore.Razor.Evolution to Microsoft.AspNetCore.Razor.Language.