RazorSlices 0.5.0

There is a newer version of this package available.
See the version list below for details.

dotnet add package RazorSlices --version 0.5.0

NuGet\Install-Package RazorSlices -Version 0.5.0

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="RazorSlices" Version="0.5.0" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

paket add RazorSlices --version 0.5.0

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: RazorSlices, 0.5.0"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

// Install RazorSlices as a Cake Addin
#addin nuget:?package=RazorSlices&version=0.5.0

// Install RazorSlices as a Cake Tool
#tool nuget:?package=RazorSlices&version=0.5.0

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

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
Installation
Features

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:

<img width="583" alt="image" src="https://user-images.githubusercontent.com/249088/160220117-7e79822e-a18a-445c-89ff-b3d9ca84892f.png">
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; }
- Conditional attribute rendering
- 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;
    }
}
```
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, and TextWriter outputs including optimizations for not boxing struct values, zero-allocation rendering of primitives like numbers, etc. (rather than just calling ToString() on everything)
Return a slice instance directly as an IResult in minimal APIs via @inherits RazorSliceHttpResult and Results.Extensions.RazorSlice("/Slices/Hello.cshtml")
Avoiding slice lookup costs at render time via RazorSlice.ResolveSliceFactory(string sliceName) which returns a SliceFactory delegate that can be cached and then used to directly create an instance of the slice whenever needed. Use SliceFactory<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)
DI-activated properties via @inject
Support for Hot Reload
Support for rendering to a Stream

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 an async method unless the template contains await 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
Rendering directly to a string, StringBuilder, etc.

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.)

Product	Compatible and additional computed target framework versions.
.NET	net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 is compatible. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed.

Product

.NET

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

net6.0
- No dependencies.
net7.0
- No dependencies.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on RazorSlices:

Package	Downloads
Toolshed.Mailman A library to assist with sending mail in ASP.NET Core using MailKit and Razor Views.	15.2K

GitHub repositories (2)

Showing the top 2 popular GitHub repositories that depend on RazorSlices:

Repository	Stars
dodyg/practical-aspnetcore Practical samples of ASP.NET Core 9, 8.0, 7.0, 6.0, 5.0, 3.1, 2.2, and 2.1,projects you can use. Readme contains explanations on all projects.	9.5K
aspnet/Benchmarks Benchmarks for ASP.NET Core	1.2K

Version	Downloads	Last updated
0.8.1	17,942	6/7/2024
0.8.0	110	6/7/2024
0.7.0	20,558	6/3/2023
0.6.2	175	5/31/2023
0.6.1	169	5/30/2023
0.6.0	147	5/30/2023
0.5.0	234	4/5/2023
0.4.0	261	3/24/2023
0.3.0	3,002	3/13/2023
0.2.0	237	3/10/2023
0.1.2	256	3/8/2023
0.1.1	244	3/8/2023
0.1.0	254	3/8/2023
0.1.0-pre.20230307.10	118	3/7/2023