Replacement for @helper in ASP.NET Core

Question

According to the following Github issue, it looks like @helper is coming back and will be included in asp .net core 3.0.0 preview 4.

https://github.com/aspnet/AspNetCore/issues/5110

UPDATE

Starting in asp .net core 3, you can now define a local function within a Razor code block.

@{
    void RenderName(string name)
    {
        <p>Name: <strong>@name</strong></p>
    }

    RenderName("Mahatma Gandhi");
    RenderName("Martin Luther King, Jr.");
}

https://docs.microsoft.com/en-us/aspnet/core/mvc/views/razor?view=aspnetcore-3.1#razor-code-blocks

Alternatively you can use the @functions directive like this:

@{
    RenderName("Mahatma Gandhi");
    RenderName("Martin Luther King, Jr.");
}

@functions {
    private void RenderName(string name)
    {
        <p>Name: <strong>@name</strong></p>
    }
}

https://docs.microsoft.com/en-us/aspnet/core/mvc/views/razor?view=aspnetcore-3.1#functions

@{
    Func<String, IHtmlContent> foo = @<div>Say @item</div>;
}

I'd like to expand on @Alexaku's answer and show how I've implemented a helper like function. It's only useful on one specific page but it allows you to execute a piece of razor code multiple times with input parameters. The syntax is not great but I've found it very useful in the absence of razor's @helper function. First declare some kind of Dto that will contain the input parameters into the function.

@functions {
   private class Dto
   {
      public string Data { get;set; }
   }
}

Then declare the razor function. Note that the displayItem value can be multi-line and also note that you access the Dto variable using the @item.

@{
   Func<Dto, IHtmlContent> displayItem = @<span>@item.Data</span>;
}

Then when you want to use the razor template you can call it like the following from anywhere in the page.

<div>
   @displayItem(new Dto {Data = "testingData1" });
</div>
<div>
   @displayItem(new Dto {Data = "testingData2" });
</div>

For .NET Core 3, you can use local functions:

@{
    void RenderName(string name)
    {
        <p>Name: <strong>@name</strong></p>
    }

    RenderName("Mahatma Gandhi");
    RenderName("Martin Luther King, Jr.");
}

https://docs.microsoft.com/en-us/aspnet/core/mvc/views/razor?view=aspnetcore-3.1#razor-code-blocks

The @helper directive was removed since it was incomplete and its current design did not fit in the new 'ASP.NET 5 way'. One of the reasons is that helpers should be declared in the App_Code folder while ASP.NET 5 has no concept of special folders. Therefore the team decided to temporarily remove the feature.

There are plans to bring it back in the future though. See this and this.

As @scott pointed out in his answer, local functions are finally available as of .NET Core 3. In prior versions one can resort to templated Razor delegates.

But none of the answers addresses the question "what happened to the App_Code folder?" The aforementioned features are local solutions, that is, helper functions defined in these ways cannot be shared between multiple views. But global helper functions could often be more convenient than the solutions MS provide out-of-the-box for view-related code re-use. (Tag helpers, partial views, view components all have their cons.) This was thoroughly discussed in this and this GitHub issue. According to these discourses, unfortunately, there's not much understanding from MS's side, so not much hope is left that this feature will be added any time soon, if ever.

However, after digging into the framework sources, I think, I could come up with a viable solution to the problem.

The core idea is that we can utilize the Razor view engine to look up an arbitrary view for us: e.g. a partial view which defines some local functions we want to use globally. Once we manage to get hold of a reference to this view, nothing prevents us from calling its public methods.

The GlobalRazorHelpersFactory class below encapsulates this idea:

public interface IGlobalRazorHelpersFactory
{
    dynamic Create(string helpersViewPath, ViewContext viewContext);
    THelpers Create<THelpers>(ViewContext viewContext) where THelpers : class;
}

public class GlobalRazorHelpersOptions
{
    public Dictionary<Type, string> HelpersTypeViewPathMappings { get; } = new Dictionary<Type, string>();
}

public sealed class GlobalRazorHelpersFactory : IGlobalRazorHelpersFactory
{
    private readonly ICompositeViewEngine _viewEngine;
    private readonly IRazorPageActivator _razorPageActivator;

    private readonly ConcurrentDictionary<Type, string> _helpersTypeViewPathMappings;

    public GlobalRazorHelpersFactory(ICompositeViewEngine viewEngine, IRazorPageActivator razorPageActivator, IOptions<GlobalRazorHelpersOptions>? options)
    {
        _viewEngine = viewEngine ?? throw new ArgumentNullException(nameof(viewEngine));
        _razorPageActivator = razorPageActivator ?? throw new ArgumentNullException(nameof(razorPageActivator));

        var optionsValue = options?.Value;
        _helpersTypeViewPathMappings = new ConcurrentDictionary<Type, string>(optionsValue?.HelpersTypeViewPathMappings ?? Enumerable.Empty<KeyValuePair<Type, string>>());
    }

    public IRazorPage CreateRazorPage(string helpersViewPath, ViewContext viewContext)
    {
        var viewEngineResult = _viewEngine.GetView(viewContext.ExecutingFilePath, helpersViewPath, isMainPage: false);

        var originalLocations = viewEngineResult.SearchedLocations;

        if (!viewEngineResult.Success)
            viewEngineResult = _viewEngine.FindView(viewContext, helpersViewPath, isMainPage: false);

        if (!viewEngineResult.Success)
        {
            var locations = string.Empty;

            if (originalLocations.Any())
                locations = Environment.NewLine + string.Join(Environment.NewLine, originalLocations);

            if (viewEngineResult.SearchedLocations.Any())
                locations += Environment.NewLine + string.Join(Environment.NewLine, viewEngineResult.SearchedLocations);

            throw new InvalidOperationException($"The Razor helpers view '{helpersViewPath}' was not found. The following locations were searched:{locations}");
        }

        var razorPage = ((RazorView)viewEngineResult.View).RazorPage;

        razorPage.ViewContext = viewContext;

        // we need to save and restore the original view data dictionary as it is changed by IRazorPageActivator.Activate
        // https://github.com/dotnet/aspnetcore/blob/v3.1.6/src/Mvc/Mvc.Razor/src/RazorPagePropertyActivator.cs#L59
        var originalViewData = viewContext.ViewData;
        try { _razorPageActivator.Activate(razorPage, viewContext); }
        finally { viewContext.ViewData = originalViewData; }

        return razorPage;
    }

    public dynamic Create(string helpersViewPath, ViewContext viewContext) => CreateRazorPage(helpersViewPath, viewContext);

    public THelpers Create<THelpers>(ViewContext viewContext) where THelpers : class
    {
        var helpersViewPath = _helpersTypeViewPathMappings.GetOrAdd(typeof(THelpers), type => "_" + (type.Name.StartsWith("I", StringComparison.Ordinal) ? type.Name.Substring(1) : type.Name));

        return (THelpers)CreateRazorPage(helpersViewPath, viewContext);
    }
}

After introducing the singleton IGlobalRazorHelpersFactory service to DI, we could inject it in views and call the Create method to acquire an instance of the view which contains our helper functions.

By using the @implements directive in the helper view, we can even get type-safe access:

@inherits Microsoft.AspNetCore.Mvc.Razor.RazorPage
@implements IMyGlobalHelpers

@functions {
    public void MyAwesomeGlobalFunction(string someParam)
    {
        <div>@someParam</div>
    }
}

(One can define the interface type to view path mappings explicitly by configuring the GlobalRazorHelpersOptions in the ordinary way - by services.Configure<GlobalRazorHelpersOptions>(o => ...) - but usually we can simply rely on the naming convention of the implementation: in the case of the IMyGlobalHelpers interface, it will look for a view named _MyGlobalHelpers.cshtml at the regular locations. Best to put it in /Views/Shared.)

Nice so far but we can do even better! It'd be much more convenient if we could inject the helper instance directly in the consumer view. We can easily achieve this using the ideas behind IOptions<T>/HtmlLocalizer<T>/ViewLocalizer:

public interface IGlobalRazorHelpers<out THelpers> : IViewContextAware
    where THelpers : class
{
    THelpers Instance { get; }
}

public sealed class GlobalRazorHelpers<THelpers> : IGlobalRazorHelpers<THelpers>
    where THelpers : class
{
    private readonly IGlobalRazorHelpersFactory _razorHelpersFactory;

    public GlobalRazorHelpers(IGlobalRazorHelpersFactory razorHelpersFactory)
    {
        _razorHelpersFactory = razorHelpersFactory ?? throw new ArgumentNullException(nameof(razorHelpersFactory));
    }

    private THelpers? _instance;
    public THelpers Instance => _instance ?? throw new InvalidOperationException("The service was not contextualized.");

    public void Contextualize(ViewContext viewContext) => _instance = _razorHelpersFactory.Create<THelpers>(viewContext);
}

Now we have to register our services in Startup.ConfigureServices:

services.AddSingleton<IGlobalRazorHelpersFactory, GlobalRazorHelpersFactory>();
services.AddTransient(typeof(IGlobalRazorHelpers<>), typeof(GlobalRazorHelpers<>));

Finally, we're ready for consuming our global Razor functions in our views:

@inject IGlobalRazorHelpers<IMyGlobalHelpers> MyGlobalHelpers;

@{ MyGlobalHelpers.Instance.MyAwesomeGlobalFunction("Here we go!"); }

This is a bit more complicated than the original App_Code + static methods feature but I think this is the closest we can get. According to my tests, the solution also works nicely with runtime compilation enabled. I haven't had the time so far to do benchmarks but, in theory, it should generally be faster than using partial views as the shared view is looked up only once per consumer view and after that it's just plain method calls. I'm not sure about tag helpers though. It'd be interesting to do some benchmarks comparing them. But I leave that up to the adopter.

(Tested on .NET Core 3.1.)

Update

You can find a working demo of this concept in my ASP.NET boilerplate project:

• Infrastructure (relevant files are only those whose name contains GlobalRazorHelpers)

• Registration

• Helper interface sample

• Helper implementation sample

• Usage sample