Discussion: Microsoft.AspNetCore.Razor refactoring and breaking changes

[rynowak]

Microsoft.AspNetCore.Razor refactoring and breaking changes

This is the discussion thread for aspnet/Announcements#227 - please post your questions and feedback here!

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.

This is the discussion thread for aspnet/Announcements#227 - please post your questions and feedback here!

[Vasim-DigitalNexus]

RE: Microsoft.AspNetCore.Razor.Evolution

Why not call it what it is: Microsoft.AspNetCore.Razor.Parser

[Bartmax]

This is great news!!

Hope you get a better name than Evolution ;)

[rynowak]

Feel free to make suggestions, ideally we'll have a new name picked out within a week or two.

[ctolkien]

Razor Core?

[nil4]

Microsoft.AspNetCore.Razor.Engine?

[Kukkimonsuta]

Thank you for getting Razor some love 👍

I'd like to ask some questions about VS tooling:

1. will updated tooling be able to pickup our custom base types @inherits MyPage without adding extra hardcoded things that are web specific?
2. will it be possible to introduce custom keywords like @model MyModel and instruct VS tooling to handle them without writing VS extension / altering VS settings (so that it's project specific)?
3. will it be possible to introduce new file extensions (and maybe set default base class for them) and instruct VS tooling to handle them without writing VS extension / altering VS settings (so that it's project specific)?
4. will the tooling work from non-web projects (class library) without introducing web related dependencies?

[NTaylorMullen]

will updated tooling be able to pickup our custom base types @inherits MyPage without adding extra hardcoded things that are web specific?

You'll have to clarify. Razor can always use your own base type, it just has specific requirements to be runnable/compilable.

will it be possible to introduce custom keywords like @model MyModel and instruct VS tooling to handle them without writing VS extension / altering VS settings (so that it's project specific)?

Definitely. This isn't currently possible in our Razor language service (it's preview after all) but it's high on our priority list to complete.

will it be possible to introduce new file extensions (and maybe set default base class for them) and instruct VS tooling to handle them without writing VS extension / altering VS settings (so that it's project specific)?

We don't currently have any plans to support this on the tooling front. We did an experiment and investigated what it would take to change Razors file extension; long story short, it's a massive amount of work.

will the tooling work from non-web projects (class library) without introducing web related dependencies?

Mostly yes. We currently have an issue here tracking using new Razor in class libraries. That issue is the first step to getting new Razor in class libraries. To address your question about introducing web related dependencies: If the base type that your Razor file is using requires it, then you will need to include those dependencies in order to avoid errors when editing your cshtml files.

[Kukkimonsuta]

Those are some great news, thank you 👍

You'll have to clarify. Razor can always use your own base type, it just has specific requirements to be runnable/compilable.

The tooling currently does pickup extra properties from custom base type, but it also inserts web/mvc related helpers like Html, Json, ModelExpressionProvider, however based on your answer to the second point I assume this won't be an issue with the new tooling.

[NTaylorMullen]

@Kukkimonsuta those are automatically injected into every view. In the future we'll enable ways that you can modify these default inclusions; not supported yet but definitely on our radar 😄

[rynowak]

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