Razor Slices
Lightweight Razor-based templates for ASP.NET Core without MVC, Razor Pages, or Blazor, optimized for high-performance rendering. Great for returning HTML from Minimal APIs, middleware, etc. Supports .NET 6+
Getting Started
-
Install the NuGet package into your ASP.NET Core project (.NET 6+):
> dotnet add package RazorSlices
-
Create a directory in your project called Slices and add a _ViewImports.cshtml file to it with the following content:
@inherits RazorSliceHttpResult @using System.Globalization; @using Microsoft.AspNetCore.Razor; @using Microsoft.AspNetCore.Http.HttpResults; @tagHelperPrefix __disable_tagHelpers__: @removeTagHelper *, Microsoft.AspNetCore.Mvc.Razor
-
In the same directory, add a Hello.cshtml file with the following content:
@inherits RazorSliceHttpResult<DateTime> <!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <title>Hello from Razor Slices!</title> </head> <body> <p> Hello from Razor Slices! The time is @Model </p> </body> </html>
-
Add a minimal API to return the slice in your Program.cs:
app.MapGet("/hello", () => Results.Extensions.RazorSlice("/Slices/Hello.cshtml", DateTime.Now));
Installation
NuGet Releases
This package is currently available from nuget.org:
> dotnet add package RazorSlices
CI Builds
If you wish to use builds from this repo's main
branch you can install them from this repo's package feed.
-
Create a personal access token for your GitHub account with the
read:packages
scope with your desired expiration length: -
At the command line, navigate to your user profile directory and run the following command to add the package feed to your NuGet configuration, replacing the
<GITHUB_USER_NAME>
and<PERSONAL_ACCESS_TOKEN>
placeholders with the relevant values:~> dotnet nuget add source -n GitHub -u <GITHUB_USER_NAME> -p <PERSONAL_ACCESS_TOKEN> https://nuget.pkg.github.com/DamianEdwards/index.json
-
You should now be able to add a reference to the package specifying a version from the repository packages feed
-
See these instructions for further details about working with GitHub package feeds.
Features
The library is still new and features are being actively added.
Currently supported
-
ASP.NET Core 6.0 and above
-
Strongly-typed models (via
@inherits RazorSlice<MyModel>
or@inherits RazorSliceHttpResult<MyModel>
) -
Razor constructs:
-
Implicit expressions, e.g.
@someVariable
-
Explicit expressions, e.g.
@(someBool ? thisThing : thatThing)
-
Control structures, e.g.
@if()
,@switch()
, etc. -
Looping, e.g.
@for
,@foreach
,@while
,@do
-
Code blocks, e.g.
@{ var someThing = someOtherThing; }
-
Functions, e.g.
@functions { private readonly string _someString = "A very important string"; private int DoAThing() => 123; }
-
Templated Razor delegates, e.g.
@inherits RazorSlice<Todo> <h1>@Title(Model)</h1> @functions { private IHtmlContent Title(Todo todo) { <text>Todo @todo.Id: @todo.Title</text> return HtmlString.Empty; } }
-
-
DI-activated properties via
@inject
-
Asynchronous rendering, i.e. the template can contain
await
statements, e.g.@await WriteTheThing()
-
Writing UTF8
byte[]
values directly to the output -
Rendering directly to
IBufferWriter<byte>
,PipeWriter
,Stream
,TextWriter
,StringBuilder
, andstring
outputs, including optimizations for not boxing struct values, zero-allocation rendering of primitives like numbers, etc. (rather than just callingToString()
on everything) -
Return a slice instance directly as an
IResult
in minimal APIs via@inherits RazorSliceHttpResult
andResults.Extensions.RazorSlice("/Slices/Hello.cshtml")
-
Avoiding slice lookup costs at render time via
RazorSlice.ResolveSliceFactory(string sliceName)
which returns aSliceFactory
delegate that can be cached and then used to directly create an instance of the slice whenever needed. UseSliceFactory<TModel> RazorSlice.ResolveSliceFactory<TModel>(string sliceName, TModel model)
for slices with strongly-typed models.
Not yet supported but planned
- Layouts and sections
- Rendering slices from slices (aka partials)
- Support for Hot Reload
Interested in supporting but not sure yet
- An HTML helper like experience, e.g.
@Html.Form()
, etc. - Getting small updates to the Razor compiler itself to get some usability and performance improvements, e.g.:
- Don't mark the template's
ExecuteAsync
method as anasync
method unless the template containsawait
statements to save on the async state machine overhead - Support compiling static template elements to UTF8 string literals (
ReadOnlySpan<char>
) instead of string literals to save on the UTF16 to UTF8 conversion during rendering - Support disabling the default registered
@addtaghelper
and@inject
directives which rely on MVC
- Don't mark the template's
No intention to support
- Tag Helpers and View Components (they're tied to MVC and are intrinsically "heavy")
@model
directive (the Razor compiler does not support its use in conjunction with custom base-types via@inherits
)@attribute [Authorize]
(wrong layer of abstraction for minimal APIs, etc.)