Aspnetcore.docs: Review & update for Publishing to IIS

[guardrex]

@Rick-Anderson @spboyer @Tratcher @pranavkm @shirhatti @moozzyk @danroth27

If it's ok with you, I'd like to get started on a doc review and update for Publishing to IIS.

The obvious items are ...

• [x] Spelling, grammar, structure, and content review (esp. Common Errors section)
• [x] Update ref for publish-iis tooling to 1.1.0-preview4-final
• [x] Update imagery for WS2016 & add image alt text
• [x] Confirm & update guidance in Common Errors section
• [x] Review and incorporate relevant information from IISIntegration, Hosting, Home, and ANCM repo issues
• [x] I'd like to add a link to the ANCM reference doc where the new ANCM overview doc is mentioned and linked.

I take it from https://github.com/aspnet/Docs/pull/2179#issuecomment-261017193 that we'll leave publish-iis tooling content in place for now and not discuss Microsoft.NET.Sdk.Web handling of web.config at this time.

Is there anything else you'd like to see addressed?

[Rick-Anderson]

@GuardRex OK

[guardrex]

Common Errors section work today. I tested the following scenarios and modified the section accordingly ...

1. IIS installed but no module (self + port)
2. IIS+module installed but no runtime or w/o restarting (install module only) (self + port)
3. Installed hosting bundle without Internet connection (no VC++ redist installed) (self + port)
4. IIS and hosting bundle installed but server/IIS not restarted (self + port)
5. IIS and hosting bundle installed but no app (point site to empty folder)
6. Stopped site
7. Stopped AppPool
8. Bad permissions for a custom AppPool user identity (self + port)
9. dotnet.exe not on the PATH (self + port)
10. Bad app processPath (self + port)
11. Bad app arguments (self: gibberish entry + port: bad DLL name)
12. Publish IIS tooling fails to run (placeholders in web.config) (should match result in 10)
13. App missing .UseIISIntegration()
14. App .UseUrls() placed after .UseIISIntegration() to confirm updated middleware
15. Deploy self-contained x86 app (win10-x86) to AppPool without 32-Bit enabled (self: confirm it runs)
16. [Preview] Set x86 deploy with an x64 runtime (win10-x64) (self) [This also confirms the prior guidance for buildOptions > Platform in conflict with the publishing RID.]

A couple of important changes ...

1. The Application log messages have changed and may change over time. To deal with this and harden the doc against future language changes, I only show the stable ErrorCode from the Application log. This is likely the best approach anyway, since devs will probably focus on the error code and find it easiest to work with when identifying matching exceptions in the Common Errors section.
2. A bit of work was done for the 502.5 section:. When the hosting bundle is not installed or the server/IIS is not restarted, the result is a 502.5 + 0x80070002 + empty ANCM log. I added some language regarding deny rules, since that was a failure scenario for a customer. This is also the result when the Microsoft Visual C++ 2015 Redistributable is uninstalled at some point after the hosting bundle installs it.
3. .UseUrls() after .UseIISIntegration() is no longer an issue, so that was removed.

WIP ... There are potentially more updates to this section forthcoming based on my review of the IISIntegration, Hosting, ANCM, and Home repo issues.

@Rick-Anderson This was one that I think you added, perhaps based on working with a customer ...

CoreWebEngine or W3SVC server features disabled

Do you know if that one is still required? I'm not sure how to repro that here.

[Tratcher]

Including error log text can be very helpful via a search engines. Keep the latest version of the error text where possible.

[guardrex]

@Tratcher I have a prob with ...

Platform conflicts with RID

• Browser: HTTP Error 502.5 - Process Failure

• Application Log: Application 'MACHINE/WEBROOT/APPHOST/MY_APPLICATION' with physical root 'C:{PATH}' failed to start process with commandline '"C:{PATH}my_application.{exe|dll}" ', ErrorCode = '0x80004005 : ff.

• ASP.NET Core Module Log: Unhandled Exception: System.BadImageFormatException: Could not load file or assembly 'my_application.dll'. An attempt was made to load a program with an incorrect format.

  Troubleshooting:

* Confirm that you didn't set a platform in buildOptions of project.json that conflicts with the publishing RID. For example, do not specify a platform of x86 and publish with an RID of win10-x64 (dotnet publish -c Release -r win10-x64). The project will publish without warning or error but fail with the above logged exceptions on the server.

The three error/exception conditions listed are correct for both a self-contained and a portable app. The apps were configured with <PlatformTarget>x86</PlatformTarget> (.csproj) or "platform": "x86" (.json).

The Troubleshooting explanation that I have only addresses the self-contained case, where the RID is specified explicitly in the dotnet publish command (-r win10-x64). Changing the publish RID to win10-x86 clears the conflict with the platform and results in a :smile: app.

What causes this conflict for a portable app published via dotnet publish -c Release -f netcoreapp1.1?

[guardrex]

@Tratcher I made updates to cover deltas on a missing VC++.

I ran into one scenario that I couldn't cleanly test tho: If the VC++ redist is uninstalled, I believe that prior testing with my portable test app threw a 502.5 + 0x80070002 + empty ANCM log. In this round of testing when I went to uninstall VC++ (and restart), my portable test app would still run without it.

Therefore, I didn't quite know what to say about needing to restart the server or restarting IIS in the last sentence of ...

You may have deployed a portable application and the Microsoft Visual C++ 2015 Redistributable (x64) is not installed on the server. You may obtain an installer from the Microsoft Download Center. Either restart the server or restart IIS by executing net stop was /y followed by net start w3svc from the command line after running the installer.

My main ? is: If the VC++ is required by an app, would simply restarting IIS after installing VC++ redist be enough? ... or should I make that say that you must restart the server?

My 2nd ? is: What is the VC++ redist used for in the grand scheme of things?

[guardrex]

@Rick-Anderson Almost there. I'm ~90% on it.

There's one more thing for me to address (in addition to a final grammar/style edit): We vastly improved the Common Errors lead-in paragraph last time. I want to take a fresh look at it.

For one thing, it could use a note on setting ASPNETCORE_ENVIRONMENT to Development via an ANCM config in web.config (temporarily) as @Tratcher has instructed a number of times to allow devs to see their developer exception page and thus find out why their app is failing. That's a :fire: :fire: :fire: hot tip!

Another thing is that I still see a number of incoherence issues on updates of apps where a simple ...

1. Kill bin/obj
2. Clear package caches
3. Confirm prior deployment is completely cleared prior to deployment of upgraded app

... gets the dev back up and running. Let me float some language. If you cats don't like it, I'll just strike it.

Tuesday! I should have the PR ready tomorrow by noon.

[Rick-Anderson]

Sounds good, no hurry No need to refer to [@]Tratcher with his alias - don't want to bother him more than necessary.

[Tratcher]

@GuardRex Restarting IIS was so that it would pick up the new PATH variable pointing to dotnet.exe (first time installs only). I often tell people to restart the server because it's easier.

I'm not aware of any restart requirements for VC++.