<input><\/code> tag and passing a\u200c reference to a property on your PageModel, in this case Input.Email:
\n`<\/p>\n<\/p>\n
`<\/p>\n
The Tag Helper is activated by the presence of the attribute and gets a chance to augment the tag when rendering to HTML. The Input Tag Helper uses the name of the property to set the tag\u2019s name and id properties, the value of the model to set the value property, and the presence of attributes such as [Required] or [EmailAddress] to add attributes for validations:\u200c\u200c\u200c<\/p>\n
<input type="email" id="Input_Email" name="Input.Email" value="test@example.com" data-val="true"\ndata-val-email="The Email Address field is not a valid e-mail address."\n\ndata-val-required="The Email Address field is required."\n\/><\/code><\/pre>\nTag Helpers help reduce the duplication in your code, or they can simplify common patterns. In this section I show how you can create your own custom Tag Helpers.<\/p>\n
In section 32.1.1 you\u2019ll create a system information Tag Helper, which prints details about the name and operating system of the server your app is running on. In section 32.1.2 you\u2019ll create a Tag Helper that you can use to conditionally show or hide an element based on a C# Boolean property. In section 32.1.3 you\u2019ll create a Tag Helper that reads the Razor content written inside the Tag Helper and transforms it.<\/p>\n
32.1.1 Printing environment information with a custom Tag Helper\u200c<\/h3>\n
A common problem you may run into when you start running your web applications in production, especially if you\u2019re using a server-farm setup, is working out which machine rendered the page you\u2019re currently looking at. Similarly, when deploying frequently, it can be useful to know which version of the application is running. When I\u2019m developing and testing, I sometimes like to add a little \u201cinfo dump\u201d at the bottom of my layouts so I can easily work out which server generated the current page, which environment it\u2019s running in, and so on.<\/p>\n
In this section I\u2019m going to show you how to build a custom Tag Helper to output system information to your layout. You\u2019ll be able to toggle the information it displays, but by default it displays the machine name and operating system on which the app is running, as shown in \ufb01gure 32.1.<\/p>\n
![\"alt](\"\/images\/aspnetcoreinaction\/3201.jpg\")
<\/p>\n
Figure 32.1 The SystemInfoTagHelper displays the machine name and operating system on which the application is running. It can be useful for identifying which instance of your app handled the request when running in a web-farm scenario.<\/p>\n
You can call this Tag Helper from Razor by creating a <system-info><\/code> element in your template:<\/p>\n<footer>\n<system-info><\/system-info>\n<\/footer><\/code><\/pre>\nTIP<\/b> You might not want to expose this sort of information in production, so you could also wrap it in an Tag Helper, as you saw in chapter 18.<\/p>\nThe easiest way to create a custom Tag Helper is to derive from the TagHelper base class and override the Process() or ProcessAsync() function that describes how the class should render itself. The following listing shows your complete custom Tag Helper, SystemInfoTagHelper, which renders the system information to a <\/p>\n
. You could easily extend this class if you wanted to display additional \ufb01elds or add options.\u200c\u200c\u200c<\/p>\nListing 32.1 SystemInfoTagHelper to render system information to a view<\/p>\n
public class SystemInfoTagHelper : TagHelper \u2776\n{\nprivate readonly HtmlEncoder _htmlEncoder; \u2777\npublic SystemInfoTagHelper(HtmlEncoder htmlEncoder) \u2777\n{\n_htmlEncoder = htmlEncoder;\n}\n[HtmlAttributeName("add-machine")] \u2778\npublic bool IncludeMachine { get; set; } = true;\n[HtmlAttributeName("add-os")] \u2778\npublic bool IncludeOS { get; set; } = true;\npublic override void Process( \u2779\nTagHelperContext context, TagHelperOutput output) \u2779\n{\noutput.TagName = "div"; \u277a\noutput.TagMode = TagMode.StartTagAndEndTag; \u277b\nvar sb = new StringBuilder();\nif (IncludeMachine) \u277c\n{ \u277c\nsb.Append(" <strong>Machine<\/strong> "); \u277c\nsb.Append(_htmlEncoder.Encode(Environment.MachineName)); \u277c\n} \u277c\nif (IncludeOS) \u277d\n{ \u277d\nsb.Append(" <strong>OS<\/strong> "); \u277d\nsb.Append( \u277d\n_htmlEncoder.Encode(RuntimeInformation.OSDescription)); \u277d\n} \u277d\noutput.Content.SetHtmlContent(sb.ToString()); \u277e\n}\n}<\/code><\/pre>\n\u2776 Derives from the TagHelper base class
\n\u2777 An HtmlEncoder is necessary when writing HTML content to the page.
\n\u2778 Decorating properties with HtmlAttributeName allows you to set their values from Razor markup.
\n\u2779 The main function called when an element is rendered.
\n\u277a Replaces the <system-info><\/code> element with a <div><\/code> element
\n\u277b Renders both the <div><\/code> <\/div><\/code> start and end tag
\n\u277c If required, adds a <strong> <\/code> element and the HTML-encoded machine name
\n\u277d If required, adds a <strong><\/code> element and the HTML-encoded OS name
\n\u277e Sets the inner content of the <\/p>\n tag with the HTML-encoded value stored in the string builder<\/p>\nThere\u2019s a lot of new code in this example, so we\u2019ll work through it line by line. First, the class name of the Tag Helper de\ufb01nes the name of the element you must create in your Razor template, with the su\ufb03x removed and converted to kebab-case. As this Tag Helper is called SystemInfoTagHelper, you must create a <system- info><\/code> element.\u200c<\/p>\nTIP<\/b> If you want to customize the name of the element, for example to <env-info><\/code>, but you want to keep the same class name, you can apply [HtmlTargetElement] with the desired name, such as [HtmlTargetElement("Env-Info")]. HTML tags are not case-sensitive, so you could use "Env-Info" or "env-info".<\/p>\nInject an HtmlEncoder into your Tag Helper so you can HTML-encode any data you write to the page. As you saw in chapter 29, you should always HTML-encode data you write to the page to avoid cross-site scripting (XSS) vulnerabilities and to ensure that the data is displayed correctly.<\/p>\n
You\u2019ve de\ufb01ned two properties on your Tag Helper, IncludeMachine and IncludeOS, which you\u2019ll use to control which data is written to the page. These are decorated with a corresponding [HtmlAttributeName], which enables setting the properties from the Razor template. In Visual Studio you\u2019ll even get IntelliSense and type-checking for these values, as shown in \ufb01gure 32.2.\u200c<\/p>\n
![\"alt](\"\/images\/aspnetcoreinaction\/3202.jpg\")
<\/p>\n
Figure 32.2 In Visual Studio, Tag Helpers are shown in a purple font, and you get IntelliSense for properties decorated with [HtmlAttributeName].<\/p>\n
Finally, we come to the Process() method. The Razor engine calls this method to execute the Tag Helper when it identi\ufb01es the target element in a view template. The Process() method de\ufb01nes the type of tag to render (<div><\/code>), whether it should render a start and end tag (or a self-closing tag\u2014it depends on the type of tag you\u2019re rendering), and the HTML content of the <div><\/code>. You set the HTML content to be rendered inside the tag by calling Content.SetHtmlContent() on the provided instance of TagHelperOutput.<\/p>\nWARNING<\/b> Always HTML-encode your output before writing to your tag with SetHtmlContent(). Alternatively, pass unencoded input to SetContent(), and the output will be automatically HTML-encoded for you.<\/p>\n
Before you can use your new Tag Helper in a Razor template, you need to register it. You can do this in the _ViewImports.cshtml \ufb01le, using the @addTagHelper directive and specifying the fully quali\ufb01ed name of the Tag Helper and the assembly, as in this example:<\/p>\n
@addTagHelper CustomTagHelpers.SystemInfoTagHelper, CustomTagHelpers<\/code><\/pre>\nAlternatively, you can add all the Tag Helpers from a given assembly by using the wildcard syntax, *, and specifying the assembly name:<\/p>\n
@addTagHelper *, CustomTagHelpers<\/code><\/pre>\nWith your custom Tag Helper created and registered, you\u2019re now free to use it in any of your Razor views, partial views, or layouts.<\/p>\n
TIP<\/b> If you\u2019re not seeing IntelliSense for your Tag Helper in Visual Studio, and the Tag Helper isn\u2019t rendered in the bold font used by Visual Studio, you probably haven\u2019t registered your Tag Helpers correctly in _ViewImports .cshtml using @addTagHelper.<\/p>\n
The SystemInfoTagHelper is an example of a Tag Helper that generates content, but you can also use Tag Helpers to control how existing elements are rendered. In the next section you\u2019ll create a simple Tag Helper that can control whether an element is rendered based on an HTML attribute.<\/p>\n
32.1.2 Creating a custom Tag Helper to conditionally hide elements\u200c<\/h3>\n
If you want to control whether an element is displayed in a Razor template based on some C# variable, you\u2019d typically wrap the element in a C# if statement:\u200c<\/p>\n
@{\nvar showContent = true;\n}\n@if(showContent)\n{\n<p>The content to show<\/p>\n}<\/code><\/pre>\nFalling back to C# constructs like this can be useful, as it allows you to generate any markup you like. Unfortunately, it can be mentally disruptive having to switch back and forth between C# and HTML, and it makes it harder to use HTML editors that don\u2019t understand Razor syntax.<\/p>\n
In this section you\u2019ll create a simple Tag Helper to avoid the cognitive dissonance problem. You can apply this Tag Helper to existing elements to achieve the same result as shown previously but without having to fall back to C#:<\/p>\n
@{\nvar showContent = true;\n}\n<p if="showContent" >\nThe content to show\n<\/p>\n<\/code><\/pre>\nWhen rendered at runtime, this Razor template would return the HTML<\/p>\n
<p>\nThe content to show\n<\/p><\/code><\/pre>\nInstead of creating a new element, as you did for SystemInfoTagHelper (<system-info><\/code>), you\u2019ll create a Tag Helper that you apply as an attribute to existing HTML elements. This Tag Helper does one thing: controls the visibility of the element it\u2019s attached to. If the value passed in the if attribute is true, the element and its content is rendered as normal. If the value passed is false, the Tag Helper removes the element and its content from the template. The following listing shows how you could achieve this.<\/p>\nListing 32.2 Creating an IfTagHelper to conditionally render elements<\/p>\n
[HtmlTargetElement(Attributes = "if")] \u2776\npublic class IfTagHelper : TagHelper\n{\n[HtmlAttributeName("if")] \u2777\npublic bool RenderContent { get; set; } = true;\npublic override void Process( \u2778\nTagHelperContext context, TagHelperOutput output) \u2778\n{\nif(RenderContent == false) \u2779\n{\noutput.TagName = null; \u277a\noutput.SuppressOutput(); \u277b\n}\n}\npublic override int Order => int.MinValue; \u277c\n}<\/code><\/pre>\n\u2776 Setting the Attributes property ensures that the Tag Helper is triggered by an if attribute.
\n\u2777 Binds the value of the if attribute to the RenderContent property
\n\u2778 The Razor engine calls Process() to execute the Tag Helper.
\n\u2779 If the RenderContent property evaluates to false, removes the element
\n\u277a Sets the element the Tag Helper resides on to null, removing it from the page
\n\u277b Doesn\u2019t render or evaluate the inner content of the element
\n\u277c Ensures that this Tag Helper runs before any others attached to the element<\/p>\n
Instead of a standalone <if><\/code> element, the Razor engine executes the IfTagHelper whenever it \ufb01nds an element with an if attribute. This can be applied to any HTML element: <p><\/code>, <div><\/code>, <input><\/code>, whatever you need. You should de\ufb01ne a Boolean property specifying whether you should render the content, which is bound to the value in the if attribute.\u200c\u200c\u200c\u200c<\/p>\nThe Process() function is much simpler here. If RenderContent is false, it sets the TagHelperOutput.TagName to null, which removes the element from the page. It also calls SuppressOutput(), which prevents any content inside the attributed element from being rendered. If RenderContent is true, you skip these steps, and the content is rendered as normal.<\/p>\n
One other point of note is the overridden Order property. This controls the order in which Tag Helpers run when multiple Tag Helpers are applied to an element. By setting Order to int.MinValue, you ensure that IfTagHelper always runs \ufb01rst, removing the element if required, before other Tag Helpers execute. There\u2019s generally no point running other Tag Helpers if the element is going to be removed from the page anyway.<\/p>\n
NOTE<\/b> Remember to register your custom Tag Helpers in _ViewImports .cshtml with the @addTagHelper directive.<\/p>\n
With a simple HTML attribute, you can now conditionally render elements in Razor templates without having to fall back to C#. This Tag Helper can show and hide content without needing to know what the content is. In the next section we\u2019ll create a Tag Helper that does need to know the content.<\/p>\n
32.1.3 Creating a Tag Helper to convert Markdown to HTML\u200c<\/h3>\n
The two Tag Helpers shown so far are agnostic to the content written inside the Tag Helper, but it can also be useful to create Tag Helpers that inspect, retrieve, and modify this<\/p>\n
content. In this section you\u2019ll see an example of one such Tag Helper that converts Markdown content written inside it to HTML.<\/p>\n
DEFINITION<\/b> Markdown is a commonly used text-based markup language that is easy to read but can also be converted to HTML. It is the common format used by README \ufb01les on GitHub, and I use it to write blog posts, for example. For an introduction to Markdown, see the GitHub guide at http:\/\/mng.bz\/o1rp<\/a>.<\/p>\nWe\u2019ll use the popular Markdig library (https:\/\/github.com\/xoofx\/markdig<\/a>) to create the Markdown Tag Helper. This library converts a string containing Markdown to an HTML string. You can install Markdig using Visual Studio by running dotnet add package Markdig or by adding a <PackageReference><\/code> to your .csproj \ufb01le:<\/p>\n<PackageReference Include="Markdig" Version="0.30.4" \/><\/code><\/pre>\nThe Markdown Tag Helper that we\u2019ll create shortly can be used by adding elements to your Razor Page, as shown in the following listing.<\/p>\nListing 32.3 Using a Markdown Tag Helper in a Razor Page<\/p>\n
@page\n@model IndexModel\n@{\nvar showContent = true;\n}\n<markdown> \u2776\n## This is a markdown title \u2777\nThis is a markdown list: \u2778\n* Item 1 \u2778\n* Item 2 \u2778\n<div if="showContent"> \u2779\nContent is shown when showContent is true \u2779\n<\/div> \u2779\n<\/markdown>\n<\/code><\/pre>\n\u2776 Adds the Markdown Tag Helper using the <markdown><\/code> element
\n\u2777 Creates titles in Markdown using # to denote h1, ## to denote h2, and so on
\n\u2778 Markdown converts simple lists to HTML <ul><\/code> elements.
\n\u2779 Razor content can be nested inside other Tag Helpers.<\/p>\nThe Markdown Tag Helper renders content with these steps:<\/p>\n
\n- \n
Render any Razor content inside the Tag Helper. This includes executing any nested Tag Helpers and C# code inside the Tag Helper. Listing 32.3 uses the IfTagHelper, for example.<\/p>\n<\/li>\n
- \n
Convert the resulting string to HTML using the Markdig library.<\/p>\n<\/li>\n
- \n
Replace the content with the rendered HTML and remove the Tag Helper <markdown><\/code> element.<\/p>\n<\/li>\n<\/ol>\nThe following listing shows a simple approach to implementing a Markdown Tag Helper using Markdig. Markdig supports many additional extensions and features that you could enable, but the overall pattern of the Tag Helper would be the same.<\/p>\n
Listing 32.4 Implementing a Markdown Tag Helper using Markdig<\/p>\n
public class MarkdownTagHelper: TagHelper \u2776\n{\npublic override async Task ProcessAsync(\nTagHelperContext context, TagHelperOutput output)\n{\nTagHelperContent markdownRazorContent = await \u2777\noutput.GetChildContentAsync(); \u2777\nstring markdown = \u2778\nmarkdownRazorContent.GetContent(); \u2778\nstring html = Markdig.Markdown.ToHtml(markdown); \u2779\noutput.Content.SetHtmlContent(html); \u277a\noutput.TagName = null; \u277b\n}\n}\n<\/code><\/pre>\n\u2776 The Markdown Tag Helper will use the <markdown><\/code> element.
\n\u2777 Retrieves the contents of the <markdown><\/code> element
\n\u2778 Renders the Razor contents to a string
\n\u2779 Converts the Markdown string to HTML using Markdig
\n\u277a Writes the HTML content to the output
\n\u277b Removes the <markdown><\/code> element from the content<\/p>\nWhen rendered to HTML, the Markdown content in listing 32.3 becomes<\/p>\n
<h2>This is a markdown title<\/h2>\n<p>This is a markdown list:<\/p>\n<ul>\n<li>Item 1<\/li>\n<li>Item 2<\/li>\n<\/ul>\n<div>\nContent is shown when showContent is true\n<\/div><\/code><\/pre>\nNOTE<\/b> In listing 32.4 we implemented ProcessAsync() instead of Process() because we called the async method GetChildContentAsync(). You must call async methods only from other async methods; otherwise, you can get problems such as thread starvation. For more details, see Microsoft\u2019s \u201cASP.NET Core Best Practices\u201d at http:\/\/mng.bz\/KM7X<\/a>.\u200c<\/p>\nThe Tag Helpers in this section represent a small sample of possible avenues you could explore, but they cover the two broad categories: Tag Helpers for rendering new content and Tag Helpers for controlling the rendering of other elements.<\/p>\n
TIP<\/b> For further details and examples, see Microsoft\u2019s \u201cAuthor Tag Helpers in ASP.NET Core\u201d documentation at http:\/\/mng.bz\/Idb0<\/a>.<\/p>\nTag Helpers can be useful for providing small pieces of isolated, reusable functionality like this, but they\u2019re not designed to provide larger, application-speci\ufb01c sections of an app or to make calls to business-logic services. Instead, you should use view components, as you\u2019ll see in the next section.\u200c<\/p>\n
32.2 View components: Adding logic to partial views\u200c<\/h2>\n
In this section you\u2019ll learn about view components, which operate independently of the main Razor Page and can be used to encapsulate complex business logic. You can use view components to keep your main Razor Page focused on a single task\u2014rendering the main content\u2014instead of also being responsible for other sections of the page.<\/p>\n
If you think about a typical website, you\u2019ll notice that it may have multiple independent dynamic sections in addition to the main content. Consider Stack Over\ufb02ow, shown in \ufb01gure 32.3. As well as the main body of the page, which shows questions and answers, there\u2019s a section showing the current logged-in user, a panel for blog posts and related items, and a section for job suggestions.<\/p>\n
![\"alt](\"\/images\/aspnetcoreinaction\/3203.jpg\")
<\/p>\n
Figure 32.3 The Stack Over\ufb02ow website has multiple sections that are independent of the main content but contain business logic and complex rendering logic.<\/p>\n
Each of these sections could be rendered as a view component in ASP.NET Core.<\/p>\n
Each of these sections is e\ufb00ectively independent of the main content. Each section contains business logic (deciding which posts or ads to show), database access (loading the details of the posts), and rendering logic for how to display the data.<\/p>\n
In chapter 7 you saw that you can use layouts and partial views to split the rendering of a view template into similar sections, but partial views aren\u2019t a good \ufb01t for this example. Partial views let you encapsulate view rendering logic but not business logic that\u2019s independent of the main page content. Instead, view components provide this functionality, encapsulating both the business logic and rendering logic for displaying a small section of the page. You can use DI to provide access to a database context, and you can test view components independently of the view they generate, much like MVC and API controllers. Think of them as being a bit like mini MVC controllers or mini Razor Pages, but you invoke them directly from a Razor view instead of in response to an HTTP request.<\/p>\n
TIP<\/b> View components are comparable to child actions from the legacy .NET Framework version of ASP.NET, in that they provide similar functionality. Child actions don\u2019t exist in ASP.NET Core.<\/p>\n\nView components vs. Razor Components and Blazor<\/p>\n
In this book I focus on server-side rendered applications using Razor Pages and API applications using minimal APIs and web API controllers. .NET 7 also has a di\ufb00erent approach to building ASP.NET Core applications: Blazor. I don\u2019t cover Blazor in this book, so I recommend reading Blazor in Action, by Chris Sainty (Manning, 2021).\u200c<\/p>\n
Blazor has two programming models, client-side and server-side, but both approaches use Blazor components (confusingly, o\ufb03cially called Razor components). Blazor components have a lot of parallels with view components, but they live in a fundamentally di\ufb00erent world. Blazor components can interact easily, but you can\u2019t use them with Tag Helpers or view components, and it\u2019s hard to combine them with Razor Page form posts.<\/p>\n
Nevertheless, if you need an island of rich client-side interactivity in a single Razor Page, you can embed a Blazor component in a Razor Page, as shown in the \u201cRender components from a page or view\u201d section of the \u201cPrerender and integrate ASP.NET Core Razor components\u201d documentation at http:\/\/mng.bz\/PPen<\/a>. You could also use Blazor components as a way to replace Asynchronous JavaScript and XML (AJAX) calls in your Razor Pages, as I show in my blog entry \u201cReplacing AJAX calls in Razor Pages with Razor Components and Blazor\u201d at http:\/\/mng.bz\/9MJj<\/a>.<\/p>\nIf you don\u2019t need the client-side interactivity of Blazor, view components are still the best option for isolated sections in Razor Pages. They interoperate cleanly with your Razor Pages; have no additional operational overhead; and use familiar concepts like layouts, partial views, and Tag Helpers. For more details on why you should continue to use view components, see my \u201cDon\u2019t replace your View Components with Razor Components\u201d blog entry at http:\/\/mng.bz\/1rKq<\/a>.<\/p>\n<\/blockquote>\nIn this section you\u2019ll see how to create a custom view component for the recipe app you built in previous chapters, as shown in \ufb01gure 32.4. If the current user is logged in, the view component displays a panel with a list of links to the user\u2019s recently created recipes. For unauthenticated users, the view component displays links to the login and register actions.<\/p>\n
![\"alt](\"\/images\/aspnetcoreinaction\/3204.jpg\")
<\/p>\n
Figure 32.4 The view component displays di\ufb00erent content based on the currently logged-in user. It includes both business logic (determining which recipes to load from the database) and rendering logic (specifying how to display the data).<\/p>\n
This component is a great candidate for a view component, as it contains database access and business logic (choosing which recipes to display) as well as rendering logic (deciding how the panel should be displayed).<\/p>\n
TIP<\/b> Use partial views when you want to encapsulate the rendering of a speci\ufb01c view model or part of a view model. Consider using a view component when you have rendering logic that requires business logic or database access or when the section is logically distinct from the main page content.<\/p>\n
You invoke view components directly from Razor views and layouts using a Tag Helper-style syntax with a vc: pre\ufb01x:<\/p>\n
<vc:my-recipes number-of-recipes="3">\n<\/vc:my-recipes><\/code><\/pre>\nCustom view components typically derive from the ViewComponent base class and implement an InvokeAsync() method, as shown in listing 32.5. Deriving from this base class allows access to useful helper methods in much the same way that deriving from the ControllerBase class does for API controllers. Unlike with API controllers, the parameters passed to InvokeAsync don\u2019t come from model binding. Instead, you pass the parameters to the view component using properties on the Tag Helper element in your Razor view.\u200c\u200c<\/p>\n
Listing 32.5 A custom view component to display the current user\u2019s recipes<\/p>\n
public class MyRecipesViewComponent : ViewComponent \u2776\n{\nprivate readonly RecipeService _recipeService; \u2777\nprivate readonly UserManager<ApplicationUser> _userManager; \u2777\npublic MyRecipesViewComponent(RecipeService recipeService, \u2777\nUserManager<ApplicationUser> userManager) \u2777\n{ \u2777\n_recipeService = recipeService; \u2777\n_userManager = userManager; \u2777\n} \u2777\npublic async Task<IViewComponentResult> InvokeAsync( \u2778\nint numberOfRecipes) \u2779\n{\nif(!User.Identity.IsAuthenticated)\n{\nreturn View("Unauthenticated"); \u277a\n}\nvar userId = _userManager.GetUserId(HttpContext.User); \u277b\nvar recipes = await _recipeService.GetRecipesForUser( \u277b\nuserId, numberOfRecipes);\nreturn View(recipes); \u277c\n}\n}<\/code><\/pre>\n\u2776 Deriving from the ViewComponent base class provides useful methods like
\nView().
\n\u2777 You can use DI in a view component.
\n\u2778 InvokeAsync renders the view component. It should return a
\nTask<IViewComponentResult><\/code>.
\n\u2779 You can pass parameters to the component from the view.
\n\u277a Calling View() will render a partial view with the provided name.
\n\u277b You can use async external services, allowing you to encapsulate logic in your
\nbusiness domain.
\n\u277c You can pass a view model to the partial view. Default.cshtml is used by
\ndefault.<\/p>\nThis custom view component handles all the logic you need to render a list of recipes when the user is logged in or a di\ufb00erent view if the user isn\u2019t authenticated. The name of the view component is derived from the class name, like Tag Helpers. Alternatively, you can apply the [ViewComponent] attribute to the class and set a di\ufb00erent name entirely.<\/p>\n
The InvokeAsync method must return a Task<IViewComponentResult><\/code>. This is similar to the way you can return IActionResult from an action method or a page handler, but it\u2019s more restrictive; view components must render some sort of content, so you can\u2019t return status codes or redirects. You\u2019ll typically use the View() helper method to render a partial view template (as in the previous listing), though you can also return a string directly using the Content() helper method, which will HTML-encode the content and render it to the page directly.\u200c\u200c<\/p>\nYou can pass any number of parameters to the InvokeAsync method. The name of the parameters (in this case, numberOfRecipes) is converted to kebab-case and exposed as a property in the view component\u2019s Tag Helper (<number-of-recipes><\/code>). You can provide these parameters when you invoke the view component from a view, and you\u2019ll get IntelliSense support, as shown in \ufb01gure 32.5.<\/p>\n![\"alt](\"\/images\/aspnetcoreinaction\/3205.jpg\")
<\/p>\n
Figure 32.5 Visual Studio provides IntelliSense support for the method parameters of a view component\u2019s InvokeAsync method. The parameter name, in this case numberOfRecipes, is converted to kebab-case for use as an attribute in the Tag Helper.<\/p>\n
View components have access to the current request and HttpContext. In listing 32.5 you can see that we\u2019re checking whether the current request was from an authenticated user. You can also see that we\u2019ve used some conditional logic. If the user isn\u2019t authenticated, we render the \u201cUnauthenticated\u201d Razor template; if they\u2019re authenticated, we render the default Razor template and pass in the view models loaded from the database.<\/p>\n
NOTE<\/b> If you don\u2019t specify a speci\ufb01c Razor view template to use in the View() function, view components use the template name Default.cshtml.<\/p>\n
The partial views for view components work similarly to other Razor partial views that you learned about in chapter 7, but they\u2019re stored separately from them. You must create partial views for view components at one of these locations:<\/p>\n
\u2022 Views\/Shared\/Components\/ComponentName\/Templ ateName<\/p>\n
\u2022 Pages\/Shared\/Components\/ComponentName\/Templ ateName<\/p>\n
Both locations work, so for Razor Pages apps I typically use the Pages\/ folder. For the view component in listing 32.5, for example, you\u2019d create your view templates at<\/p>\n
\u2022 Pages\/Shared\/Components\/MyRecipes\/Def ault.cshtml
\n\u2022 Pages\/Shared\/Components\/MyRecipes\/Una uthenticated.cshtml<\/p>\n
This was a quick introduction to view components, but it should get you a long way. View components are a simple way to embed pockets of isolated, complex logic in your Razor layouts. Having said that, be mindful of these caveats:<\/p>\n
\u2022 View component classes must be public, non- nested, and nonabstract classes.<\/p>\n
\u2022 Although they\u2019re similar to MVC controllers, you can\u2019t use \ufb01lters with view components.<\/p>\n
\u2022 You can use layouts in your view components\u2019 views to extract rendering logic common to a speci\ufb01c view component. This layout may contain @sections, as you saw in chapter 7, but these sections are independent of the main Razor view\u2019s layout.<\/p>\n
\u2022 View components are isolated from the Razor Page they\u2019re rendered in, so you can\u2019t, for example, de\ufb01ne a @section in a Razor Page layout and then add that content from a view component; the contexts are completely separate.<\/p>\n
\u2022 When using the <vc:my-recipes><\/code> Tag Helper syntax to invoke your view component, you must import it as a custom Tag Helper, as you saw in section 32.1.<\/p>\n\u2022 Instead of using the Tag Helper syntax, you may invoke the view component from a view directly by using IViewComponentHelper Component, though I don\u2019t recommend using this syntax, as in this example:<\/p>\n
@await Component.InvokeAsync("MyRecipes", new { numberOfRecipes = 3 })<\/code><\/pre>\nWe\u2019ve covered Tag Helpers and view components, which are both features of the Razor engine in ASP.NET Core. In the next section you\u2019ll learn about a di\ufb00erent but related topic: how to create a custom DataAnnotations attribute. If you\u2019ve used older versions of ASP.NET, this will be familiar, but ASP.NET Core has a couple of tricks up its sleeve to help you out.\u200c<\/p>\n
32.3 Building a custom validation attribute\u200c<\/h2>\n
In this section you\u2019ll learn how to create a custom DataAnnotations validation attribute that speci\ufb01es speci\ufb01c values a string property may take. You\u2019ll then learn how you can expand the functionality to be more generic by delegating to a separate service that is con\ufb01gured in your DI controller. This will allow you to create custom domain-speci\ufb01c validations for your apps.\u200c<\/p>\n
We looked at model binding in chapter 7, where you saw how to use the built-in DataAnnotations attributes in your binding models to validate user input. These provide several built-in validations, such as<\/p>\n
\u2022 [Required]\u2014The property isn\u2019t optional and must be provided.<\/p>\n
\u2022 [StringLength(min, max)]\u2014The length of the string value must be between min and max characters.<\/p>\n
\u2022 [EmailAddress]\u2014The value must have a valid email address format.<\/p>\n
But what if these attributes don\u2019t meet your requirements? Consider the following listing, which shows a binding model from a currency converter application. The model contains three properties: the currency to convert from, the currency to convert to, and the quantity.<\/p>\n
Listing 32.6 Currency converter initial binding model<\/p>\n
public class CurrencyConverterModel\n{\n[Required] \u2776\n[StringLength(3, MinimumLength = 3)] \u2777\npublic string CurrencyFrom { get; set; }\n[Required] \u2776\n[StringLength(3, MinimumLength = 3)] \u2777\npublic string CurrencyTo { get; set; }\n[Required] \u2776\n[Range(1, 1000)] \u2778\npublic decimal Quantity { get; set; }\n}<\/code><\/pre>\n\u2776 All the properties are required.
\n\u2777 The strings must be exactly three characters.
\n\u2778 The quantity can be between 1 and 1000.<\/p>\n
There\u2019s some basic validation on this model, but during testing you identify a problem: users can enter any three- letter string for the CurrencyFrom and CurrencyTo properties. Users should be able to choose only a valid currency code, like "USD" or "GBP", but someone attacking your application could easily send "XXX" or "\u00a3$%".\u200c<\/p>\n
Assuming that you support a limited set of currencies\u2014say, GBP, USD, EUR, and CAD\u2014you could handle the validation in a few ways. One way would be to validate the CurrencyFrom and CurrencyTo values within the Razor Page handler method, after model binding and attribute validation has already occurred.<\/p>\n
Another way would be to use a [RegularExpresssion] attribute to look for the allowed strings. The approach I\u2019m going to take here is to create a custom ValidationAttribute. The goal is to have a custom validation attribute you can apply to the CurrencyFrom and CurrencyTo attributes, to restrict the range of valid values. This will look something like the following example.<\/p>\n
Listing 32.7 Applying custom validation attributes to the binding model<\/p>\n
public class CurrencyConverterModel\n{\n[Required]\n[StringLength(3, MinimumLength = 3)]\n[CurrencyCode("GBP", "USD", "CAD", "EUR")] \u2776\npublic string CurrencyFrom { get; set; }\n[Required]\n[StringLength(3, MinimumLength = 3)]\n[CurrencyCode("GBP", "USD", "CAD", "EUR")] \u2776\npublic string CurrencyTo { get; set; }\n[Required]\n[Range(1, 1000)]\npublic decimal Quantity { get; set; }\n}<\/code><\/pre>\n\u2776 CurrencyCodeAttribute validates that the property has one of the provided
\nvalues.<\/p>\n
Creating a custom validation attribute is simple; you can start with the ValidationAttribute base class, and you have to override only a single method. The next listing shows how you could implement CurrencyCodeAttribute to ensure that the currency codes provided match the expected values.<\/p>\n
Listing 32.8 Custom validation attribute for currency codes<\/p>\n
public class CurrencyCodeAttribute : ValidationAttribute \u2776\n{\nprivate readonly string[] _allowedCodes; \u2777\npublic CurrencyCodeAttribute(params string[] allowedCodes) \u2777\n{ \u2777\n_allowedCodes = allowedCodes; \u2777\n} \u2777\nprotected override ValidationResult IsValid( \u2778\nobject value, ValidationContext context) \u2778\n{\nif(value is not string code \u2779\n|| !_allowedCodes.Contains(code)) \u277a\n{ \u277a\nreturn new ValidationResult("Not a valid currency code"); \u277a\n}\nreturn ValidationResult.Success; \u277b\n}\n}<\/code><\/pre>\n\u2776 Derives from ValidationAttribute to ensure that your attribute is used during validation
\n\u2777 The attribute takes in an array of allowed currency codes.
\n\u2778 The IsValid method is passed the value to validate and a context object.
\n\u2779 Tries to cast the value to a string and store it in the code variable
\n\u277a If the value provided isn\u2019t a string, is null, or isn\u2019t an allowed code, returns an error . . .
\n\u277b . . .otherwise, returns a success result.<\/p>\n
As you know from chapter 16, Validation occurs in the \ufb01lter pipeline after model binding, before the action or Razor Page handler executes. The validation framework calls IsValid() for each instance of ValidationAttribute on the model property being validated. The framework passes in value (the value of the property being validated) and the ValidationContext to each attribute in turn. The context object contains details that you can use to validate the property.<\/p>\n
Of particular note is the ObjectInstance property. You can use this to access the top-level model being validated when you validate a subproperty. For example, if the CurrencyFrom property of the CurrencyConvertModel is being validated, you can access the top-level object from the ValidationAttribute as follows:<\/p>\n
var model = validationContext.ObjectInstance as CurrencyConverterModel;<\/code><\/pre>\nThis can be useful if the validity of a property depends on the value of another property of the model. For example, you might want a validation rule that says that GBP is a valid value for CurrencyTo except when CurrencyFrom is also GBP. ObjectInstance makes these sorts of comparison validations easy.<\/p>\n
NOTE<\/b> Although using ObjectInstance makes it easy to make model-level comparisons like these, it reduces the portability of your validation attribute. In this case, you would be able to use the attribute only in the application that de\ufb01nes CurrencyConverterModel.<\/p>\n
Within the IsValid() method, you can cast the value provided to the required data type (in this case, string) and check against the list of allowed codes. If the code isn\u2019t allowed, the attribute returns a ValidationResult with an error message indicating that there was a problem. If the code is allowed, ValidationResult.Success is returned, and the validation succeeds.<\/p>\n
Putting your attribute to the test in \ufb01gure 32.6 shows that when CurrencyTo is an invalid value (\u00a3$%), the validation for the property fails, and an error is added to the ModelState. You could do some tidying-up of this attribute to set a custom message, allow nulls, or display the name of the property that\u2019s invalid, but all the important features are there.<\/p>\n
![\"alt](\"\/images\/aspnetcoreinaction\/3206.jpg\")
<\/p>\n
Figure 32.6 The Watch window of Visual Studio showing the result of validation using the custom ValidationAttribute. The user has provided an invalid currencyTo value, \u00a3$%. Consequently, ModelState isn\u2019t valid and contains a single error with the message "Not a valid currency code".<\/p>\n
The main feature missing from this custom attribute is client- side validation. You\u2019ve seen that the attribute works well on the server side, but if the user entered an invalid value, they wouldn\u2019t be informed until after the invalid value had been sent to the server. That\u2019s safe, and it\u2019s as much as you need to do for security and data-consistency purposes, but client- side validation can improve the user experience by providing immediate feedback.<\/p>\n
You can implement client-side validation in several ways, but it\u2019s heavily dependent on the JavaScript libraries you use to provide the functionality. Currently, ASP.NET Core Razor templates rely on jQuery for client-side validation. See the \u201cCustom client-side validation\u201d section of Microsoft\u2019s \u201cModel validation in ASP.NET Core MVC and Razor Pages\u201d documentation for an example of creating a jQuery Validation adapter for your attributes: http:\/\/mng.bz\/Wd6g<\/a>.<\/p>\nTIP<\/b> Instead of using the o\ufb03cial jQuery-based validation libraries, you could use the open source aspnet-client- validation library (https:\/\/github.com\/haacked\/aspnet-client<\/a>- validation) as I describe on my blog at http:\/\/mng.bz\/AoXe<\/a>.<\/p>\nAnother improvement to your custom validation attribute would be to load the list of currencies from a DI service, such as an ICurrencyProvider. Unfortunately, you can\u2019t use constructor DI in your CurrencyCodeAttribute, as you can pass only constant values to the constructor of an Attribute in .NET. In chapter 22 we worked around this limitation for \ufb01lters by using [TypeFilter] or [ServiceFilter], but there\u2019s no such solution for ValidationAttribute.<\/p>\n
Instead, for validation attributes you must use the service locator pattern. As I discussed in chapter 9, this antipattern is best avoided where possible, but unfortunately it\u2019s necessary in this case. Instead of declaring an explicit dependency via a constructor, you must ask the DI container directly for an instance of the required service.<\/p>\n
Listing 32.9 shows how you could rewrite listing 32.8 to load the allowed currencies from an instance of ICurrencyProvider instead of hardcoding the allowed values in the attribute\u2019s constructor. The attribute calls the GetService() method on ValidationContext to resolve an instance of ICurrencyProvider from the DI container. Note that ICurrencyProvider is a hypothetical service that would need to be registered in your application\u2019s ConfigureServices() method in Startup.cs.\u200c<\/p>\nListing 32.9 Using the service-locator pattern to access services<\/p>\n
public class CurrencyCodeAttribute : ValidationAttribute\n{\nprotected override ValidationResult IsValid(\nobject value, ValidationContext context)\n{\nvar provider = context \u2776\n.GetRequiredService<ICurrencyProvider>(); \u2776\nvar allowedCodes = provider.GetCurrencies(); \u2777\nif(value is not string code \u2778\n|| !_allowedCodes.Contains(code)) \u2778\n{ \u2778\nreturn new ValidationResult("Not a valid currency code"); \u2778\n} \u2778\nreturn ValidationResult.Success; \u2778\n}\n}<\/code><\/pre>\n\u2776 Retrieves an instance of ICurrencyProvider directly from the DI container
\n\u2777 Fetches the currency codes using the provider
\n\u2778 Validates the property as before<\/p>\n
TIP<\/b> The generic GetRequiredService<T><\/code> method is an extension method available in the Microsoft.Extensions.DependencyInjection namespace.\u200c<\/p>\nThe default DataAnnotations validation system can be convenient due to its declarative nature, but this has tradeo\ufb00s, as shown by the dependency injection problem above. Luckily, you can replace the validation system your application uses, as shown in the following section.<\/p>\n
32.4 Replacing the validation framework with FluentValidation\u200c<\/h2>\n
In this section you\u2019ll learn how to replace the DataAnnotations-based validation framework that\u2019s used by default in Razor Pages and MVC Controllers. You\u2019ll see the arguments for why you might want to do this and learn how to use a third-party alternative: FluentValidation. This open- source project allows you to de\ufb01ne the validation requirements of your models separately from the models themselves. This separation can make some types of validation easier and ensures that each class in your application has a single responsibility.\u200c<\/p>\n
Validation is an important part of the model-binding process in ASP.NET Core. In chapter 7 you learned that minimal APIs don\u2019t have any validation built in, so you\u2019re free to choose whichever framework you like. I demonstrated using DataAnnotations, but you could easily choose a di\ufb00erent validation framework.<\/p>\n
In Razor Pages and MVC, however, the DataAnnotations validation framework is built into ASP.NET Core. You can apply DataAnnotations attributes to properties of your binding models to de\ufb01ne your requirements, and ASP.NET Core automatically validates them. In section 32.3 we even created a custom validation attribute.<\/p>\n
But ASP.NET Core is \ufb02exible. You can replace whole chunks of the Razor Pages and MVC frameworks if you like. The validation system is one such area that many people choose to replace.<\/p>\n