The Model Binding doc page doesn't directly explain that the name attribute is required in the .cshtml file for binding to the backend to work

[Tyler-H]

Description

Background:

For context, I'm coming from an ASP.NET Web Forms world where there is direct access via the runat="server" attribute key-value pair for linking frontend elements to backend functionality, and I'm trying to learn what the closest equivalent is in the ASP.NET Core (Razor Pages) paradigm. I know that it's been ~25 years since the Web Forms paradigm landed, and ASP.NET and the web are both different today, so there's no 1:1 equivalent to Web Forms, which is fine, but obviously there must be some equivalent... people still need to take input from a form and "do stuff" upon form submission in a web environment, after all.

To that point, I've struggled to find any clear statement in the documentation for how to do that. It took me a day or two of googling and searching through Microsoft Learn pages, Stack Overflow Q&A, blog posts, and various YouTube video tutorials before I found a resource that explained what was needed (but of course didn't point to any documentation explaining it authoritatively). Here's what I have found, and what I think should be clarified for it, for folks like me coming today from an ASP.NET Web Forms-esque paradigm:

Problem:

On https://learn.microsoft.com/en-us/aspnet/core/mvc/models/model-binding?view=aspnetcore-9.0#sources it mentions model binding sources and goes into great detail about the [BindProperty] term in .cs files for binding a given property of a model. It doesn't directly mention anywhere on the page that I can see, however, that the name attribute is what's looked for and what has to match the property value under the .cs file's [BindProperty] declaration.

One can intuit it by assuming they are getting data via a form submission and thus need to look at the [FromForm] link (even if they never have [FromForm] declared anywhere, to their knowledge) and see there are two properties listed on that page: BindingSource and Name, and guess that Name is the attribute that is required on the frontend page's element to "link" the frontend to the backend.

For example, for a form with this code on an Index.cshtml.cs file:

public class IndexModel : PageModel {
    [BindProperty]
    public string Name { get; set; }

    ...
}

This Index.cshtml frontend code will not work to make the #name input value accessible to the Index.cshtml.cs file for further server-side processing:

<input id="name" type="text" />

It will result in a null value being passed whenever the Name public string is referenced in the .cshtml.cs backend code.

But this Index.cshtml code below, with the name attribute included, in the .cshtml frontend will work:

<input id="name" type="text" name="name" />

In this modified code, the actual value that was inputted into the form's input element will be accessible whenever the backend tries to pass the value of the Name public string to some other variable or method.

Proposed solution:

To make this more clear to learners/developers, I propose in the Sources section of the documentation page, the opening line of that section be changed from:

By default, model binding gets data in the form of key-value pairs from the following sources in an HTTP request:

to something like (emphasis mine):

By default, model binding gets data in the form of key-value pairs from the name attribute of a matching element from the following sources in an HTTP request:

However, I'm new to model binding and making frontend and backend communicate with each other in ASP.NET Core, so I don't know if that language is accurate for all cases or just my own (or if I've missed something big and somehow just made my code work by sheer dumb luck). If there is another page somewhere that does cover that name is required on the frontend to match up with [BindProperty] objects on the backend, please let me know what that page is as I was unable to find it.

Page URL

https://learn.microsoft.com/en-us/aspnet/core/mvc/models/model-binding?view=aspnetcore-9.0

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/mvc/models/model-binding.md

Document ID

9c4af557-8d06-4c6c-ad2a-0dd234547563

Article author

@tdykstra

Metadata

• ID: e24f48f8-6c4d-ecda-6ce6-a7826d396e99
• Service: aspnet-core
• Sub-service: mvc

Related Issues