Hyperlinks to inherited types point to older MSDN documents

[dkemlage]

Hello Eric,

We are noticing that some of our custom classes that depend on inherited Microsoft types (ex: System.Net.Http.HttpRequestMessage) hyperlink out to older MSDN documentation sources that are no longer being maintained by Microsoft.

Here is the configuration of our build machine:

• Windows 10 version 1709 (OS Build 16299.1087)
• Visual Studio Enterprise 2017 version 15.9.12
• SHFB 2019.4.14.0

Here are the steps to reproduce the issue:

ONE: Use Visual Studio 2017 to create a WPF App (.NET Framework). Choose the Target Framework as .NET Framework 4.6.1. Call the name of the solution TestApp.sln.

TWO: Replace the code in the MainWindow.xaml.cs file with the following:

using System.Windows;

namespace TestApp
{
    /// <summary>
    /// Interaction logic for MainWindow.xaml
    /// </summary>
    public partial class MainWindow : Window
    {
        /// <summary>
        /// This is the Main Window.
        /// </summary>
        public MainWindow()
        {
            InitializeComponent();
        }
    }

    /// <summary>
    /// This is the Test Http Request Message.
    /// </summary>
    public class TestHttpRequestMessage : System.Net.Http.HttpRequestMessage
    {
    }
}

THREE: In the Project Properties > Build tab, check on the XML documentation file check box. Then build the project to create the TestApp.exe and TestApp.xml files. Here is a screen shot with the relevant parts of the Visual Studio project:

FOUR: Create a Visual Studio 2017 SandCastle documentation project. Reference the TestApp.exe and TestApp.xml files. Set the Framework version to .NET Framework 4.6.1. Then build the SandCastle documentation project.

FIVE: Examine the resulting .chm file for the TestHttpRequestMessage Class. In the Inheritance Hierarchy section of the document, click on the System.Net.Http.HttpRequestMessage link.

You will find that the hyperlink goes to the following MSDN Url:
https://docs.microsoft.com/en-us/previous-versions/visualstudio/hh159020(v=vs.118)

Microsoft states that the content for this set of MSDN docs is not longer being updated regularly.

Most likely, the hyperlink that is generated by SandCastle should probably be going to the following Url:
https://docs.microsoft.com/en-us/dotnet/api/system.net.http.httprequestmessage?view=netframework-4.6.1

NOTE: What is interesting to note is that clicking on the "System.Obect" type in the Inheritance Hierarchy section for the same page generated in the .chm file takes you to a much updated MSDN document URL (albeit it is a .NET Framework 4.8 rather than 4.6.1 but at least is is not outdated):
https://docs.microsoft.com/en-us/dotnet/api/system.object?redirectedfrom=MSDN&view=netframework-4.8

Do you have a suggestion on how to have SandCastle point to the correct version of the .NET Framework 4.6.1 of the MSDN documentation for the inherited Microsoft Type: System.Net.Http.HttpRequestMessage? Or do you think that might be a bug that could get resolved in another version of the SHFB?

Thanks,
Don Kemlage
[email protected]

[EWSoftware]

The MTPS content service is used to obtain the IDs in the URLs generated for the links. I thought perhaps it might be an outdated cached ID but I deleted my cache file and let it look all the IDs up again and it came back with the same one. The URLS are getting redirected to the docs.microsoft.com site so perhaps Microsoft isn't redirecting everything correctly.

It's possible links to the newer docs.microsoft.com pages could be generated instead since they all seem to be named after the member. It would be a matter of figuring out what the rules are for converting a member ID to a corresponding valid URL taking into account nested classes, generic modifiers, etc.

[Delpire]

I wonder if this is related to an issue we are seeing. We all of the sudden have seen many of our builds start to fail. We are seeing the following:

MSDN web service failed. No further look ups will be performed for this build.
Reason: The underlying connection was closed: An unexpected error occurred on a receive.
warning : Unable to read data from the transport connection: An existing connection was forcibly closed by the remote host.
warning : An existing connection was forcibly closed by the remote host

I saw the documentation on your site about this build warning, but we do not seem to be behind any kind of proxy.

Nothing has changed as far as the version of SHFB we are using, or our shfbproj files. Even our binary/xml files have remained the same.

[EWSoftware]

@Delpire No, this is unrelated. The MTPS content service goes down every now and then. I cleared my cache and tried a build and it is currently down. Not much we can do except wait for it to come back up. If you've got a cache, it will use that so unless there are new IDs it needs to look up, there won't be any non-clickable links in the output.

[Delpire]

@EWSoftware thank you for the fast reply! We starting seeing these build failures last week (Thursday/Friday or so). Hopefully it comes back up soon. :)

EDIT: Also, are we worried that the MTPS will go down forever at some point?
MicrosoftDocs/feedback#393

[EWSoftware]

I wouldn't be surprised if it did go away without warning. I have an item on my To Do list to investigate other ways of generating the IDs that go to the newer site.

[EWSoftware]

I've replaced the MTPS content service with the new cross reference service for Docs.Microsoft.com that generates links to the new site. I'll probably publish an update to SHFB containing the new resolver in a week or so.