Complete mess of a documentation page

This documentation page is a complete mess. I came here to figure out how to setup the configuration to be able to group pages into folders and instead I get a bunch of thrown together information which seems like someone stripped comments from code and just placed them here. Terrible.

Edit by @Rick-Anderson
PV 3.6 K, CSAT 100%

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

ID: e66c32c8-ec27-1771-bb62-71d6aa55b1d6
Version Independent ID: 99dc76fb-8762-20a6-d7b1-df3ce6e6fc4d
Content: Razor Pages route and app conventions in ASP.NET Core
Content Source: aspnetcore/razor-pages/razor-pages-conventions.md
Product: aspnet-core
GitHub Login: @guardrex
Microsoft Alias: riande

Hello @dcarapic ... Thanks for commenting on the topic. Your "someone" is ME.

I did use API comments from the engineers in constructing the definitions of the interfaces involved. Perhaps, that's what you're referring to.

First, let me remark on your goal ...

how to setup the configuration to be able to group pages into folders

We need a little more information on that. Page discovery and route establishment is handled by the framework in the simplest case [i.e., when there are physical pages (files) that are placed into folders under the Pages folder of the app]. You don't need to take any additional configuration steps in that case. The framework will take care of page discovery and creating routes. It's described throughout the main Razor Pages topic ...

https://docs.microsoft.com/aspnet/core/razor-pages

... and there are sections on URL generation, Custom routes, and Configuration and settings that pertain to RP routing.

This topic on conventions is meant to go beyond the general scenarios that the built-in page/folder discovery, routing, model generation, and processing provide.

You might be implying that you need to do something more complex than OOB routing to physical pages on disk. If so, please clarify what you're trying to do. Either we might be able to help you here, or we'll suggest speaking directly to the Microsoft engineers about it. If it's more of a general support request, then we usually suggest a support forum, such as Stack Overflow, or a support chat, such as Gitter or Slack, for the fastest response ... especially on a weekend like this when you're trying to get a quick answer.

WRT the "complete mess" here ...

When I wrote this, it seemed to me that the subject of conventions would be most easily explained by example. I wouldn't describe the content as a "mess" simply because the conventions are grouped by scenario each with a brief explanation and an example (that's also in the sample app). However, I think there are some opportunities for improving how the conventions are explained in the text prior to the appearance of the examples. I still think are the best way to understand how these conventions work is via the examples and the sample app.

What you're seeing is literally the first version of the topic. It was written back in October (2017), and we haven't performed a 2nd pass on it. My experience is that when we hit a topic again several months after the topic is written that we do find opportunities to clarify the scenarios described.

Let's use your issue here to engage the topic for updates that will help clarify the scenarios. Let's see if we can get get further away from API comment-sounding language to more plain-language explanations on what each convention does and how it's used. I have to let you know tho ... this is a very small team with an extensive backlog of high priority work. It could take some time to get to this issue. As always, the community is welcome to help with these issues. I'll also mark this up-for-grabs in case anyone would like to help.

Dear Luke, Thank you for your reply. Possibly my problem is that I should read some other documentation prior to reading this page? If so then please let me know. In the mean-time I will try to explain why I made this comment as I was going through the help page. To put things into context I am .NET developer for a long time but with very little experience with .NET Core.

I started reading from the top.

Learn how to use page route and app model provider conventions to control page routing, discovery, and processing in Razor Pages apps.

While I do know what routing is, I do not know what is meant by 'discovery'? What does processing mean in this context? Maybe not important but it was a bit confusing.

When you need to configure custom page routes for individual pages ...

Yes, my intent is to rearange the files according to the Features file layout, no non-file views or something like that, just different file placements. This seems like something that would help but I am not sure how. Clicking on the AddPageRoute convention links drops me in the middle of this huge help page and I am just not sure if I should go back and start from the beginning of the page or just try to push through and figure things out. Just to be sure I go back and continue reading.

To specify a page route, add route segments, or add parameters to a route, use the page's @page directive. For more information, see Custom routes.

If I have a page which accepts 'int id' as parameter for OnGet then do I need set up something custom or not, probably not I guess? I guess some things are taken over from MVC? Would be nice if there was sentence mentioning this.

There are reserved words that can't be used as route segments or parameter names

OK .... I'll just continue and hopefully remember this when I reach this part several dozen paragraphs later on.

View or download sample code (how to download)

OK ... I guess there will sample code somewhere later?

Then comes the table which displays a bunch of IxxxxConvention interfaces, bunch of AddxxxConvention etc. Should I read something else first where the significance of these interfaces and methods are described or should I continue with hopes that everything will get clearer as I keep reading?

Razor Pages conventions are added and configured using ...
(then a code section)

I just did not understand this code example. Is this something like 'here is everything all together at one place'. Should I go back to this when I read through everything?

Model conventions
Add a delegate for IPageConvention to add model conventions that apply to Razor Pages.

This looks like a comment from source-code. I did not understand the significance of this sentence when I was reading it. It stands by itself and did not provide any helpfull information to me.

Use Conventions to create and add an IPageRouteModelConvention to the collection of IPageConvention instances that are applied during page route model construction.

This looks like a comment from the source-code or something. At first I though that Conventions is meant as a concept and then I realized it is a property on PageConventionCollection. Then there is a code sample which does not mention this Conventions proerpty at all. Also I do not know what does {globalTemplate?} route template do. The entire example is kind of hanging in the air for me. But I continue on ....

Note: The Order property for the AttributeRouteModel is set to -1. This ensures that  .... also that it would have priority over automatically generated Razor Pages routes

OK ... I guess this is relevant in some scenarios. I know that there are some automatic Razor Pages routes otherwise the thing would not work. Where are those automatic routes described? This seems like an answer from a StackOverflow question where I do not see the question and only the answer. Again not very helpfull.

Razor Pages options, such as adding Conventions, are added when MVC is added to the service collection in Startup.ConfigureServices. For an example, see the sample app.

This sentence is so weird to me. 'adding Conventions' is a 'Razer Page option' and somebody (me?) should/is adding them to service collection? Looks like google translate gone bad. See sample app ... Do I need to do that? I do not know at this point. Is there perhaps enough information here in this help page so that I do not have to go through source code?

At this point I'm kind of exasparated so I keep scrolling down and hoping that something will help me here ...

Page route action conventions

Hmm ... from the name of the section I guess you can change the names of the OnGet etc. methods on the page? Interesting but I do not need that. Then I read the paragraph and the sample code and I have no idea what is this thing doing. Why would I use this? What problem does it solve?

Page model action conventions

Hmm ... its not a route convention its a model convention. Then an example of a filter attribute with a helpfull statement 'Using conventions, the sample demonstrates how to apply the attribute to all of the pages in a folder and to a single page.' Funny, there is no convention mentioned anywhere in this sample.

Here I figured out that I've reached only the half of the page and that I'm totally lost so I gave up.

Let me let you know about one general thing that I just discovered about this topic: Looking internally at the page's scores by readers, there isn't much to go on. There are only a couple of negative reviews. However, it also seems that this topic isn't read very often. It looks like doc readers briefly check this out, figure that it isn't what they need (or they just aren't interested in the subject), and leave. There are two very good remarks by readers that mirror what you identified in your post: The topic:

Relies too heavily on the examples/sample app.
The convention sections don't explain in plain language what the conventions are.

Therefore, this is a good issue to work, and we will get to it (eventually 🏃🏃🏃😅).

As I go thru here, I'll mark some of these with bold for work when I (or someone) gets to this topic for updates.

Possibly my problem is that I should read some other documentation prior to reading this page? If so then please let me know.

Not necessarily, since the main Razor Pages topic only generally addresses the OOB behaviors. We think that readers will read that page before accessing this page. For the more advanced setups tho that rely upon custom route and page model processing, this is the right place ... the only place really to learn more.

While I do know what routing is, I do not know what is meant by 'discovery'? What does processing mean in this context? Maybe not important but it was a bit confusing.

Elaborate on framework processing vis-a-vis the conventions

Sure ... I understand what you mean. The "discovery" is the discovery of the physical pages within the app. These conventions refer specifically to the "Page route action conventions." The most commonly used one here is the AddPageRoute, which is described by example at the top and is explained in detail later in the topic ...

options.Conventions.AddPageRoute("/Contact", "TheContactPage/{text?}");

... where "Contact" is a physical page in the Pages folder and the framework will discover it (and create a route to it) automatically but the developer actually wants that page to be reached at /TheContactPage with a route parameter.

The more advanced scenario is when one needs an action to occur for a specific folder or page route. With that action, the developer gets access to the PageRouteModel and then can do things like add a template (as the sample app does) and many other things with custom code. If you take a look at the sample app and check the IntelliSense on the model, you'll see that there's a lot of access to the internals in the framework. That's what I generally meant by "processing" ... it's the processing that the framework does behind-the-scenes in route construction, route matching to requests, route attribute processing, etc.

Yes, my intent is to rearange the files according to the Features file layout, no non-file views or something like that, just different file placements. This seems like something that would help but I am not sure how.

Clicking on the AddPageRoute convention links drops me in the middle of this huge help page and I am just not sure if I should go back and start from the beginning of the page or just try to push through and figure things out.

Get the link right for AddPageRoute

It seems to me now that when the introduction to the topic is addressed that a better link for this extension method will get the reader to the right spot. I'd like it to go to ...

https://docs.microsoft.com/aspnet/core/razor-pages/razor-pages-conventions#configure-a-page-route

... which leads to ...

If I have a page which accepts 'int id' as parameter for OnGet then do I need set up something custom or not, probably not I guess?

Try an AddPageRoute similar to the example and see if it pipes your id thru to the page ...

options.Conventions.AddPageRoute("/RealPageRoute", "CreatedVirtualPageRoute/{id?}");

[Don't take my use of the word "virtual" here too seriously. We're really just talking about creating another route to the page. "Virtual" is such an overloaded term these days ... it can mean so many different things.]

... where id will be received by the RealPageRoute page (which lives in the Pages folder) when a user tries to navigate to https://domain:com/CreatedVirtualPageRoute/99. If all goes well 🤞, 99 will be available in the RealPageRoute page in id ...

public void Get()
{
    if (RouteData.Values["id"] != null)
    {
        var a_string = $"Route data for 'id' was provided: {RouteData.Values["id"]}";
    }
}

It's there ... I mean the topic is trying to surface it, and the sample is trying to show it. I think the problem is in the introduction. There's perhaps not enough context for this scenario early (at the top) to get the reader down to this section. The section itself might be ok ... that doesn't look too shady.

I guess there will sample code somewhere later?

The idea ... we hope anyway ... is that the reader will just go ahead and open the sample. You can just open it in a browser window and click around as the topic explains things. Otherwise, these are real running samples. That provides an opportunity with IntelliSence to tour around in there and see what gets exposed ... properties ... methods ... etc. Make changes ... run it ... see what happens.

Should I read something else first where the significance of these interfaces and methods are described

Elaborate in the introduction on what the conventions do ... what are they in plain language? ... what do they do?

Yes, I agree with you. Let's add content to the introduction to address this.

This looks like a comment from source-code. I did not understand the significance of this sentence when I was reading it. It stands by itself and did not provide any helpfull information to me.

This looks like a comment from the source-code or something.

I do not know what does {globalTemplate?} route template do.

In addition to the intro, add plain-language explanations of the conventions at the start of each convention section.

Totally agree here. We did a fine job of providing the API-comment-speak, and I think it's ok to leave those passages. It will be helpful if we have something before that that makes it clearer in plain language what these conventions are doing.

Where are those automatic routes described?

If you're referring to what the framework is doing behind-the-scenes, the short answer (painful for me to write and painful for you to hear 🤕) is .......... they aren't. One would need to get to an advanced blog post or read the source to see how it works. I know that that's a very unsatisfying answer. We are limited by a couple of things ...

The basic doc set has to describe the general implementations. The main goals are ...
- What is the scenario?
- How do I implement the framework components to address the scenario?
- What are the gotchas when I'm doing this?
We're a small team with a rather LARGE framework to explain. Advanced scenarios and deep dives on the framework components will be the last things we can do.

Having said that, there is a light at the end of the tunnel. The engineers are really, truly settling on very long-term solutions to every general programming scenario. As time goes on, the docs teams will have more time to write about advanced scenarios and on deep dive subjects. This just naturally occurs because so many parts of the framework become more-and-more stable over time.

This isn't currently actionable I don't think, but I'll take a look at the notes on AttributeRouteModel and see what can be done.

Razor Pages options, such as adding Conventions, are added when MVC is added to the service collection in Startup.ConfigureServices.

Possibly remove this remark. Possibly elaborate on Conventions via the AddRazorPagesOptions in the introduction.

That one is just meant to be a passing remark re-iterating what is shown and explained in the introduction, where it shows how the developer adds the Conventions via the AddRazorPagesOptions. We might be able to just strike this remark. It isn't necessary here, and we might be able to better explain it in the introduction anyway.

Page route action conventions

from the name of the section I guess you can change the names of the OnGet etc. methods on the page

I think the effort to improve the introduction will help here. It's not so much about changing the names of the "handlers." That's down in ...

https://docs.microsoft.com/aspnet/core/razor-pages/razor-pages-conventions#replace-the-default-page-app-model-provider

... it's more like how to interact with the framework components that pertain to page route discovery and route processing.

Page model action conventions

its not a route convention its a model convention.

Yes, that's right. These are for dealing with the page model. It's a bit annoying to me that I wrote ☹️ ...

These conventions are useful when building and modifying page discovery and processing scenarios.

Strike this remark.

I'd like to strike that remark ... and punch myself for it. 👊👦

Then an example of a filter attribute with a helpful statement 'Using conventions, the sample demonstrates how to apply the attribute to all of the pages in a folder and to a single page.' Funny, there is no convention mentioned anywhere in this sample.

Ah ... but there is tho ... it's just a little further down ...

options.Conventions.AddFolderApplicationModelConvention("/OtherPages", model =>
{
    model.Filters.Add(new AddHeaderAttribute(
        "OtherPagesHeader", new string[] { "OtherPages Header Value" }));
});

The "model convention" is added through the same collection of "conventions" as everything else here.

THE BOOK!

Well, this turned out to be a book. 🙈 See if AddPageRoute was the thing you were looking for here and if it accomplishes your need to re-map request routes to physical pages.

Someone here in the future (me ... or one of the other authors if I'm not here) will use these notes to guide updates to the topic. Thanks for discussing it with me @dcarapic. This painful process is how a lot of topics become great over time ... the community lets us know when a topic isn't working.

If both of you spent all this time to improve the topic instead of trying to find reasonable arguments to each others pride, this could have been by far a truly explanatory article. BTW, if you or someone you know, have ever programmed (any language) back in 1996, then, you must be respectful that you are able to find even a little piece of code to help you out on numerous web sites. Also, back then, if you had tenths of multi-thousand pages books in front of you (the only source of information - sorry, no samples dudes, letters cost to print), you may be searching for days (and many nights) to get to the right path. And then, you expect that the writer/author was right and all this effort was not a waste of time. And, you have learned something, to read carefully, to digest the information and to focus. Those books back then, took thousands of hours to be written and prepared, nowadays, things are quick (and sometimes dirty), you don't have to please the reader now, you just expose the information, I don't approve it, but I can live with it. I hope you get me...

@mtsiakiris Sorry but I do not understand your point. In my opinion the documentation page is not good and this is what I wrote. The documentation writer asked to elaborate. I elaborated and then he gave some more feedback. This resulted in him adding the documentation 'update' to the backlog. Regarding your remark: 'both of you spent all this time to improve the topic...' - I am not the one who can improve the documentation (as I do not have the knowledge or permissions to modify the content) so I'm not sure what you meant by that. Regarding your remark: 'you don't have to please the reader now, you just expose the information' - your observation is correct, the state of .NET core documentation is (in my opinion) not good enough. However I think that an effort should be made to improve the situation, which is why I made my comment.

I'll move the priority up ... give us a little time tho. The docs team needs to get past the 2.2 release. We're all 🏃 running full speed right now on 2.2 issues.

or permissions to modify the content

Anyone can submit a PR to improve a doc. If anyone needs help beyond https://github.com/aspnet/Docs/blob/master/CONTRIBUTING.md, please ping any of us on the docs team.

Yes, that's what I was just writing down. Improving the documentation can be done by suggesting corrections, clarifications, additions, etc. and not by directly editing it, just a PR will trigger the process. I think that the majority of the comments, hides some irony from both sides witch is something that is not helping me. From the moment you took all this time for the elaborations, I still don't see any improvement on the article. I know you are on a rush, believe me. If anybody remembers the old times of "msdn online", this is now heaven (referring to @dcarapic) where I agree, that .net core is expanding really fast and docs must be kept updated (community helps a lot on that, great documentation exists out there). Just to make it clear, I am not criticizing any of the comments, this is not my intention.

Like @dcarapic, I'm trying to set up a project with feature folders. For my PhoneController's Index action, I would like to display the view /Features/Phone/Index.cshtml

How do I do that? I don't understand which of the conventions I need to add to achieve this, all the examples seem a lot more complicated than what I imagine must be the solution. I would expect it to be something like options.Conventions.AddFolderRouteModelConvention("/Features/Phone", model => { ... });, but what is the model supposed to be here?

@bjarte This topic, Razor Pages route and app conventions in ASP.NET Core, (and this issue) is about Razor Pages conventions, not MVC.

See if How controllers specify views helps.

Ah, sorry, I didn't realize it wasn't the same setup for Pages and MVC. The link you provided does not say anything about conventions, however, but I found some other resources that discuss this, for example https://github.com/OdeToCode/AddFeatureFolders

To answer my own question:

The simplest way I found to add feature folders to a project's conventions, is like this:

options.AddRazorOptions(options => { options.ViewLocationFormats.Add("/Features/{1}/{0}.cshtml"); options.ViewLocationFormats.Add("/Features/{1}/Views/{0}.cshtml"); options.ViewLocationFormats.Add("/Features/Shared/{0}.cshtml"); options.ViewLocationFormats.Add("/Features/Shared/Views/{0}.cshtml"); });

This is limited in that it only helps the application find the view files, not the controllers (which I had already set up with attribute routing anyway).

@bjarte I've only seen similar code for Areas, a scenario of MVC that I haven't had a requirement to use ... https://docs.microsoft.com/aspnet/core/mvc/controllers/areas

Thanks for contacting us. We don’t have the resources to invest in this area, so we are closing the issue. Should your request generate enough 👍 responses, we’ll reconsider.

dotnet / AspNetCore.Docs

Complete mess of a documentation page #8270

Document Details