Home

Awesome

Safe Routing Source Generator for ASP.NET Core

SafeRouting NuGet Package GitHub Release

Safe Routing is a source generator which analyses a project's razor pages and MVC controllers, producing strongly-typed representations of those routes as you type. This enables you to link between pages with compile time safety instead of using the standard "stringly typed" approach.

Table of Contents

Usage Example

Consider the following contrived example of a controller class.

public sealed class ProductController : Controller
{
  [FromRoute]
  public int? Limit { get; set; }

  [Route("/Product/Search/{name}/{Limit?}")]
  public IActionResult Search(string name) => Ok();
}

Redirecting to the Search action could be rewritten as follows:

BEFORE:

return RedirectToAction("Search", "Product", new { Name = "chair", Limit = 10 });

AFTER:

return Routes.Controllers.Product.Search("chair", 10).Redirect(this);

The controller name, action name, names of action method parameters, and names of bound properties on the controller are no longer referenced with strings, and are instead referenced with C# classes, methods, parameters, and properties that offer compile time safety.

Similarly, consider the following razor page model class:

public sealed class EditModel : PageModel
{
  [FromRoute]
  public int Id { get; set; }

  public void OnGet()
  {
    // ...
  }

  public void OnPost()
  {
    // ...
  }
}

The generated code enables you to access the URL for the OnGet handler with the following code:

string? editUrl = Routes.Pages.Edit.Get(123).Url(Url);

Installation

<!-- See https://github.com/dotnet/roslyn/blob/main/docs/wiki/NuGet-packages.md and https://learn.microsoft.com/en-au/dotnet/core/porting/versioning-sdk-msbuild-vs#lifecycle to determine SDK/VS versions based on Microsoft.CodeAnalysis.CSharp version used by SafeRouting.Generator -->

To install, simply add the SafeRouting package to your ASP.NET Core project. You must have .NET SDK 6.0.1xx or greater installed which is included in Visual Studio 17.0 or greater.

Tag Helpers

To enable the included tag helpers, add the following line to _ViewImports.cshtml files where required.

@addTagHelper SafeRouting.TagHelpers.*, SafeRouting.Common

This enables for-route attributes to be added to <a>, <button>, <img>, and <form> elements, for example:

@{
  var controllerRoute = Routes.Controllers.Product.Search("chair", 10);
  var pageRoute = Routes.Pages.Edit.Post(Model.Id);
  var pageHandlerRoute = Routes.Pages.Product.PostDelete();
}

<!-- Adds the URL in the href attribute -->
<a for-route="controllerRoute">Search for chairs</a>

<!-- Adds the URL in the src attribute -->
<img for-route="controllerRoute" alt="" />

<!-- Adds the URL in the action attribute -->
<form for-route="pageRoute" method="post"></form>

<!-- Adds the URL in the button's formaction attribute -->
<form method="post">
  <button type="submit" for-route="pageHandlerRoute">Delete</button>
</form>

Extension Methods

The Redirect extension methods return RedirectToActionResult or RedirectToPageResult values as appropriate for the particular route, and accept the active controller or page model as a parameter. The Url extension methods return a string with a URL for the route, accepting an IUrlHelper instance as a parameter.

For projects using C# 8 or 9, add using SafeRouting.Extensions; to your source code to access the extension methods Redirect() and Url(). Projects using C# 10 or above will automatically have access to these extension methods via a generated global using static directive.

Getting Started

The following code snippet demonstrates accessing, modifying, and retrieving generated route information for the ProductController class defined above.

// For C# 9 and below include this using directive to enable the Redirect() and Url() extension methods:
//using SafeRouting.Extensions;

// Get route information for the Search method on ProductController with a name value of "chair" and limit unset
// Route: /Product/Search/chair
var route = Routes.Controllers.Product.Search("chair", limit: null);

// Assign a value for the Limit property (defined on the controller class)
// Route: /Product/Search/chair/5
route[route.Properties.Limit] = 5;

// Set the value of a parameter
// Route: /Product/Search/book/5
route[route.Parameters.Name] = "book";

// Set a value using the Set method
// Route: /Product/Search/book/10
route.Set(route.Properties.Limit, 10);

// Remove a route value
// Route: /Product/Search/book
route.Remove(route.Properties.Limit);

// Access the URL for the route using an IUrlHelper
// Value: "/Product/Search/book"
string? routeUrl = route.Url(Url);

// Get route information for the OnGet method on the /Edit page
var pageRoute = Routes.Pages.Edit.Get(123);

// "/Edit?Id=123"
var path = pageRoute.Path(linkGenerator);

// "https://example.org/Edit?Id=123"
var uri = pageRoute.Url(linkGenerator, "https", new HostString("example.org"));

// Redirect from within a controller action method or a page handler method
return route.Redirect(this);

Binding Source Attributes

The generated methods will closely resemble your original controller action methods and page handler methods, but will only include parameters which can be bound via the URL. Consider the following action method:

public IActionResult Index(
  string standard,
  [FromBody] string fromBody,
  [FromForm] string fromForm,
  [FromHeader] string fromHeader,
  [FromQuery] string fromQuery,
  [FromRoute] string fromRoute,
  [FromServices] string fromServices)
{
  // ...
}

The generated route helper method omits the parameters with the attributes [FromBody], [FromForm], [FromHeader], and [FromServices] because they are not bound to any part of the URL. The generated helper method instead looks like this:

public static IndexRouteInfo Index(string standard, string fromQuery, string fromRoute)
{
  // ...
}

Properties on the controller or page model class which are annotated with [FromRoute], [FromQuery], or [BindProperty(SupportsGet = true)] attributes, and properties within a class annotated with [BindProperties(SupportsGet = true)] are automatically included in the signatures of all generated methods for that class. This ensures that all route values necessary for constructing a URL are provided when calling the methods. E.g; consider the following razor page model:

public sealed class EditModel : PageModel
{
  [FromRoute]
  public int ProductId { get; set; }

  public void OnGet()
  {
    // ...
  }

  public void OnPost(string name)
  {
    // ...
  }
}

The route-bound ProductId property is added to each of the generated methods, resulting in the following method signatures:

Support.Pages_Edit.GetRouteValues Get(int productId);
Support.Pages_Edit.PostRouteValues Post(string name, int productId);

Bundled Attributes

A couple of included attributes allow you to customise how the source generator interprets your code. [ExcludeFromRouteGenerator] can be applied to a class, property, method, or parameter to have it be ignored by the analyser. [RouteGeneratorName] allows you to rename any symbol (class, property, method, or parameter) in the generated code, which can help you avoid naming conflicts.

Areas

By default, the generated helper classes for controller and page routes will be added to the namespaces Routes.Controllers and Routes.Pages, respectively. Controllers adorned with the [Area] attribute, and pages within an /Areas/{area-name}/Pages/ directory structure have their helper classes added to Routes.Areas.AreaName.Controllers and Routes.Areas.AreaName.Pages respectively (replacing AreaName with the name of the area).

Controller Methods with the Same Name

There are a couple of situations to be mindful of involving controllers with multiple methods of the same name. Firstly, consider the following controller:

public class ProductController : Controller
{
  public IActionResult Edit(int productId)
  {
    // ...
  }

  [HttpPost]
  public IActionResult Edit(int productId, [FromForm] string name)
  {
    // ...
  }
}

Because of the way that the generated methods only include parameters which can be bound via the URL, the the above methods would both result in generated methods with the same signature. Because of this, the above code results in a compile error. To work around this, you could either rename one of the methods, or apply the [RouteGeneratorName] attribute to one of the methods to rename the generated method into something unique.

The other situation to be aware of is when you have multiple overloads with different resulting signatures, the generated route values classes returned by the generated methods will be named with sequential numbers to ensure uniqueness. For example, if the above class was written without the [FromForm] attribute, the generated methods would be written with the following signatures:

Support.Controllers_Product.EditRouteValues Edit(int productId);
Support.Controllers_Product.Edit2RouteValues Edit(int productId, string name);

It is recommended that you don't directly reference the names of the classes returned by those methods, and instead use the var keyword if you need to capture the result into a variable. I.e.;

var route = Routes.Controllers.Product.Edit(1, "Blanket");

Using Razor Class Libraries

Route information is only generated for source code within each project which references the SafeRouting package. In order to reference routes within another library, that library must reference SafeRouting and be configured to use the public access modifier for classes (which is the default).

Configuration

This source generator can be configured via a Global AnalyzerConfig file.

Example .globalconfig file:

is_global = true

safe_routing.generated_access_modifier = internal
safe_routing.generated_namespace = Example.Namespace.Routes

Available Configuration Options

OptionDescription
safe_routing.generated_access_modifierThe access modifier used for all generated classes. Can be public or internal. Defaults to public.
safe_routing.generated_namespaceThe namespace under which all generated route classes are created. Defaults to Routes.
safe_routing.generated_parameter_caseThe case used for parameters in generated methods. Can be standard (camel case) or pascal. Defaults to standard.

Limitations

Working with the Source Code

Projects

Building the NuGet Package

dotnet tool install -g dotnet-script

dotnet script build.csx -- 1.2.3