Dotnet-api-docs: The default API version for MS Docs should be .NET Core, not .NET Framework

[carlossanlop]

When a .NET API webpage is visited in MS Docs, any link that does not indicate a version moniker in the URL automatically redirects to .NET Framework 4.8.

Shouldn't we make .NET Core (latest version in production) the default link for redirection? We are actively working on .NET Core, not on Framework, so it doesn't make sense to redirect to the legacy version.

@mairaw @rpetrusha @danmosemsft @karelz What do you think?

Example:

This link
https://docs.microsoft.com/en-us/dotnet/api/system.io

Gets automatically redirected to
https://docs.microsoft.com/en-us/dotnet/api/system.io?view=netframework-4.8

Instead of
https://docs.microsoft.com/en-us/dotnet/api/system.io?view=netcore-2.2

[mairaw]

Sorry I missed this issue earlier. The plan is to make .NET Core the default, when we ship 3.0.

[danmoseley]

Sounds great to me

[mairaw]

I'm moving this to the backlog for now. I've discussed this with several .NET PMs after the release was done to see if we were ready to do this, but we're not. Here's why:

• Right now the F1 integration from VS is broken. So if a customer is using .NET Framework APIs, he'd still land on .NET Core 3.0 version.
  My next task is to investigate whether VS is sending the moniker value in the F1 query or not.

[carlossanlop]

@mairaw do you have an update on this?

[mairaw]

@terrajobst opened two bugs related to this:

• https://github.com/dotnet/docfx/issues/5183 which was moved to an internal bug
• https://github.com/dotnet/project-system/issues/5574

So right now, nothing has changed.

[carlossanlop]

cc @BillWagner for awareness. As of April, we still link to .NET Framework as the default.

What if we offer the user the option to set their preferred default in their browser? Not sure what the policy is for cookies in dotnet-api-docs, but using one would be a potential option to make a .NET versions persistent in the current browser.

[danmoseley]

cc @richlander

[mairaw]

Adding @mimisasouvanh given the engineering request. It might be complicated since there would be multiple preferred, one for each product family.

[mimisasouvanh]

log-suggestion @mimisasouvanh

[mimisasouvanh]

Here is the internal tracking item.

[BillWagner]

I'll update the default moniker to 3.1 today. I'd raised the thread internally, got some agreement, and no arguments against. (I'll interpret silence as agreement).

[danmoseley]

@mimisasouvanh is there also a bug for making the dropdown selection persistent? After @BillWagner changes the default I assume that all the developers developing against .NET Framework will have to now reset their dropdown every time they go to the page.

[mairaw]

Yes, they will have to reset their dropdown after the change every time they go to the page.

[BillWagner]

@carlossanlop The change is live. .NET Core 3.1 is now the default. 🥂 🥃

I think you can close this.

[danmoseley]

Yes, they will have to reset their dropdown after the change every time they go to the page.

That seems a pity, and it's a problem that will get over time as we add more new API to .NET Core. Could we consider setting something in the cookie?

[carlossanlop]

@danmosemsft I agree that it might be even better to let the browser remember the last .NET version the user selected. But at the same time I think it's great that we now suggest .NET Core as the main option, wouldn't you agree?

[danmoseley]

@carlossanlop yes, sorry I wasn't clear: I agree and I'm glad the change is made -- I'm just pointing out that the persistence issue probably should still be fixed (especially if F1 isn't pushing the keyword) as folks will be developing for .NET Framework or .NET Standard for a long time.

[mimisasouvanh]

@danmosemsft Can you take a snapshot of the dropdown change you are suggesting?

[gewarren]

@mimisasouvanh I think Dan is saying that currently, when you browse to https://docs.microsoft.com/en-us/dotnet/api/, enter a search string, and click a result, the page you're taken to shows the default moniker version (currently .NET Core 3.1). He's requesting that instead of showing you the default moniker version, it shows you the version you last looked at, even if you closed the browser in between or navigated away from the API docs.

One caveat would be if you search for an API that's not available in the moniker version you last had set, then we should switch to the default moniker version, or, if that API isn't available in the default moniker, the most recent version that API is available in.

[danmoseley]

That's right. Consider a developer targeting .NET Framework - every time they navigate to the API docs, they have to adjust the dropdown. Basically the problem that .NET Core developers used to have, is now reversed. Making the setting sticky in a cookie solves the problem.

[BillWagner]

@danmosemsft @mimisasouvanh Can we move the discussion of a "sticky" default moniker to a new issue and close this as resolved? /cc @carlossanlop

[mairaw]

@BillWagner @gewarren can we make sure that .NET 5 has more weight than .NET Platform Extensions? If both are available, .NET 5 should be the one selected.

But this is not what's happening if I go to https://docs.microsoft.com/en-us/dotnet/api/system.io.fileformatexception

The order on OPS should be higher for .NET 5:

[gewarren]

@mairaw I made the following changes:

[mairaw]

Thanks @gewarren. I think with that, we can close this issue.