How to Use Vue 3 with ASP.NET Razor

TLDR

• It is recommended to use the Vue 3 Options API in lightweight or non-build-tool environments.
• By using custom TagHelpers, ASP.NET Core DataAnnotations can be automatically converted into VeeValidate validation rules.
• When integrating, pay attention to v-cloak style settings to prevent raw templates from appearing during page load.
• Use Axios Interceptors to handle RequestVerificationToken to satisfy ASP.NET Core's anti-forgery validation requirements.
• Based on testing, this architecture has compatibility issues with asp-page-handler and DisplayName rendering; it is recommended to evaluate the long-term maintenance costs.

Use Cases for Vue 3 and Options API

In ASP.NET Razor Pages projects where complex frontend build tools are not introduced, it is recommended to adopt the Vue 3 Options API. According to official recommendations, the Options API remains a stable choice for low-to-medium complexity scenarios (such as Progressive Enhancement) and has no plans for deprecation.

Integration Architecture and Core Implementation

1. Basic Environment Setup

Include Vue 3 and VeeValidate-related packages in _Layout.cshtml. Special attention should be paid to the v-cloak CSS setting to hide uncompiled Vue templates:

[v-cloak] {
    display: none;
}

2. Handling ASP.NET Anti-Forgery Validation

To ensure Axios AJAX requests pass the ASP.NET Core ValidateAntiForgeryToken check, configure an interceptor in site.js:

axios.interceptors.request.use(
    config => {
        let token = document.querySelector('input[name="__RequestVerificationToken"]');
        if (token !== null) {
            config.headers = {
                RequestVerificationToken: token.value
            }
        }
        return config;
    }
);

3. Automated Validation Rule Conversion (TagHelper)

When does this issue arise? When you want to map backend C# DataAnnotations (such as [Required], [EmailAddress]) directly to frontend VeeValidate validation rules.

By using a custom VeeValidateInputTagHelper, you can intercept the asp-for attribute and convert validation attributes into a rules string:

private string? GetRules() {
    List<string> items = new List<string>();
    // Example: Convert DataAnnotations to VeeValidate rules
    foreach (var validationAttribute in For.Metadata.ValidatorMetadata) {
        switch (validationAttribute) {
            case RequiredAttribute _:
                items.Add("required");
                break;
            case EmailAddressAttribute _:
                items.Add("email");
                break;
            // Other rule conversions...
        }
    }
    return items.Any() ? $"{string.Join("|", items)}" : null;
}

Known Issues and Limitations

WARNING

Testing in 2024 revealed the following technical limitations in this architecture:

• The <v-form> generated by VeeValidateFormTagHelper causes asp-page-handler to malfunction.
• Error messages cannot correctly parse field names set by Attributes such as DisplayName.

Due to the aforementioned issues, if the project has a high dependency on form processing, it is recommended to carefully evaluate this integration method or consider switching to ASP.NET Core Blazor to avoid maintenance burdens caused by frontend framework updates.

Change Log

• 2023-01-30 Initial document creation.
• 2024-04-07 Added unresolved issues to the article structure.