Treat Blazor component Warnings as Errors: Found markup element with unexpected name

When developing Blazor applications, certain issues with component markup are flagged as warnings by default that can have a substantial impact if undetected.

One of these cases is warning code RZ10012, which is raised when a Blazor component cannot be found due to a missing using directive within the Razor file.

In my opinion, I believe RZ10012 should be treated as an error by default, as the impact of allowing the build to succeed with one or more of these warnings going unnoticed can cause significant problems in production.

In this post, I’ll provide an example of the warning for clarity and show how you can treat this particular warning as an error in your Blazor project.

Example of Warning

Let’s say we have developed a basic Button component that accepts Text and OnClick parameters and said component has been placed within a ‘Components’ folder at the root of the standard Blazor WebAssembly project template.

Given a project name of ‘BlazorSample’, this would result in a namespace of BlazorSample.Components for the Button component.

We can replace the HTML button element within the Counter page with the Button component, as shown in the following markup/code.

@page "/counter"
 
@using BlazorSample.Components
 
<PageTitle>Counter</PageTitle>
 
<h1>Counter</h1>
 
<p role="status">Current count: @currentCount</p>
 
<Button Text="Click me" OnClick=IncrementCount />
 
@code {
    private int currentCount = 0;
 
    private void IncrementCount()
    {
        currentCount++;
    }
}

In the above example, a using directive for BlazorSample.Components has been included. As a result, the project builds successfully without any errors or warnings, and the Button component renders correctly on the Counter page.

If, however, we remove the using directive, the following warning will be raised.

Found markup element with unexpected name ‘Button’. If this is intended to be a component, add a @using directive for its namespace.

If we proceed to build the project/solution again without the using directive in place, we’ll find that the build still succeeds. This is concerning because it allows the application to pass through build pipelines and enter test or other environments without detection.

Note that with good automated test coverage, the issue should be caught; however, the idea here is to catch the issue as soon as possible, so that no time is wasted and risk is minimised.

Next, let’s move on to the possible solutions.

Solutions

There are two primary solutions that we’ll explore in the following subsections.

Treat all Warnings as Errors

The solution that I think is worth considering first is to treat all warnings as errors.

This is often considered a best practice and can help to reduce bugs and eliminate noise, providing a clean project build output each time the build is run.

To do this, we can add the TreatWarningsAsErrors element to the .csproj file of the Blazor Web project and set a value of true for it, as shown below.

<Project Sdk="Microsoft.NET.Sdk.BlazorWebAssembly">
    <PropertyGroup>
	<TargetFramework>net9.0</TargetFramework>
	<Nullable>enable</Nullable>
	<ImplicitUsings>enable</ImplicitUsings>
	<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
    </PropertyGroup>
    <ItemGroup>
	<PackageReference Include="Microsoft.AspNetCore.Components.WebAssembly" Version="9.0.7" />
	<PackageReference Include="Microsoft.AspNetCore.Components.WebAssembly.DevServer" Version="9.0.7" PrivateAssets="all" />
	<PackageReference Include="Microsoft.Authentication.WebAssembly.Msal" Version="9.0.7" />
    </ItemGroup>
</Project>

Now, when we try to build the project, we’ll see that the build fails due to the presence of the warning.

Notice in the screenshot above that the issue still appears as a Warning (as opposed to an Error) within the Error List, but with the updated project configuration in place, the warning causes the build to fail.

Treat specific Warnings as Errors

The second, less restrictive, approach we can take is to treat the specific warning code that we are interested in as an error.

To do this, we can add the WarningsAsErrors element and specify a semi-colon-delimited list of warning codes that we want to treat as errors, as shown below.

<Project Sdk="Microsoft.NET.Sdk.BlazorWebAssembly">
    <PropertyGroup>
	<TargetFramework>net9.0</TargetFramework>
	<Nullable>enable</Nullable>
	<ImplicitUsings>enable</ImplicitUsings>
	<WarningsAsErrors>RZ10012</WarningsAsErrors>
    </PropertyGroup>
    <ItemGroup>
	<PackageReference Include="Microsoft.AspNetCore.Components.WebAssembly" Version="9.0.7" />
	<PackageReference Include="Microsoft.AspNetCore.Components.WebAssembly.DevServer" Version="9.0.7" PrivateAssets="all" />
	<PackageReference Include="Microsoft.Authentication.WebAssembly.Msal" Version="9.0.7" />
    </ItemGroup>
</Project>

With the above change in place, the build will fail again due to the warning, as demonstrated previously.

Summary

In this post, I covered how to handle the warning that is raised when a Blazor component cannot be found due to a missing using directive within the Razor file.

I provided an example of the message that is displayed when the warning is triggered, and then proceeded to consider two possible solutions to catch the issue as part of the regular build process.

Now, it’s up to you to choose the approach you’re most comfortable with and that best suits your needs.