search

dotnet / AspNetCore.Docs

Documentation for ASP.NET Core
https://docs.microsoft.com/aspnet/core
Creative Commons Attribution 4.0 International
12.44k stars 25.33k forks source link

"Publish an ASP.NET Core app to IIS" is missing configuration information #31923

Open SetTrend opened 4 months ago

SetTrend commented 4 months ago

Description

The tutorial on below mentioned page implies that there is no configuration necessary in the web.config configuration file in order to run an ASP.NET Core app in IIS.

Moreover, the following pages also don't give any information on the mandatory configuration settings required to run an ASP.NET Core app in IIS:

AFAIK, setting some configuration keys is mandatory to successfully run an ASP.NET Core app in IIS. But these are not documented yet.

Please add the missing information, including explanation of the necessary keys and their values, to any of these pages.

Page URL

https://learn.microsoft.com/en-us/aspnet/core/tutorials/publish-to-iis?view=aspnetcore-8.0&tabs=visual-studio#additional-resources

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/tutorials/publish-to-iis.md

Document ID

51273790-5178-875b-010e-15d7725da535

Article author

@Rick-Anderson

guardrex commented 4 months ago

@SetTrend ... All of the configuration is explained within this node of articles. There's no configuration required following this tutorial given that the SDK provides the app with a web.config file on publish that includes the minimal configuration. That file is sufficient to get the app running on IIS. Detailed info in the in following article ...

https://learn.microsoft.com/aspnet/core/host-and-deploy/iis/web-config

SetTrend commented 4 months ago

I see. Yet, I see following issues here:

When I'm searching for something similar to "Host ASP.NET Core on Windows with IIS", I'll get forwarded to any of these three pages. And this is what I get:

  1. https://learn.microsoft.com/en-us/aspnet/core/host-and-deploy/iis/

    This page neither provides information nor links to mandatory web.config entries. So, it doesn't become clear that there are any mandatory settings necessary and what these settings are.

  2. https://learn.microsoft.com/en-us/aspnet/core/tutorials/publish-to-iis

    This page neither provides information nor links to mandatory web.config entries. So, it doesn't become clear that there are any mandatory settings necessary and what these settings are.

    The mandatory web.config file content seems an important piece of information, regardless of the sample project coincidentally and silently providing that mandatory piece of information.

    So, I suppose it should at least be mentioned on that page that the sample project comes with mandatory web.config settings that need to be provided if the sample project isn't used, plus a hyperlink pointing to the corresponding web.config documentation file.

  3. https://learn.microsoft.com/en-us/aspnet/core/host-and-deploy/iis/advanced

    This page comes with link to "web.config file" deep down as a minor, initially hidden item in the See Also section.

    The mandatory web.config file content neither is "advanced" nor is it an unimportant piece of information for it to be hidden, burried deep down somewhere in the See Also, But Only If You Are Really, Really Keen To Know This Detail section.

guardrex commented 4 months ago
  1. By convention, we usually limit cross-linking to other articles on a subject in the same node. Readers are expected to see that the node contains other topics related to the subject. Having long lists of inter-node cross-links in every article of the node will fill the Additional resources sections with links to articles that are discoverable by inspecting the ToC around the current article. It's just not something that we generally do, admittedly at the risk of a reader not discovering the content until they read down the ToC (table of contents) in that node further. In this case, the plan was for devs to go to the IIS Overview article and see the web.config article in that node of articles.
  2. Also by convention, we don't cross-link much in tutorials, which are meant to focus on the dev having a successful experience with a base case scenario. This tutorial links early to the IIS Overview, and it's generally felt that readers will see the other articles in that node after they follow the link, including the one on web.config. It didn't happen is this case, but that's the plan thus far.
  3. That's normal. When the article doesn't require a link for its subject matter, the cross-link goes into the Additional resources (or similar) section at the bottom.

This article (tutorial) is managed by Rick, and he'll decide the best course of action. There's nothing at all wrong with mentioning web.config with a cross-link, and he may decide to do that. Alternatively, he may decide to stick with what's here based on our conventional approaches for article discovery. He'll be along in a bit to assist ... being a western 🐱, he's probably still dreaming in C# 🛌😴 right now 😆. Stand-by ...............