[Announcement]📢Microsoft Learn xref service to be retired on March 8, 2024

[yufeih]

Microsoft Learn will retire the Learn xref service on March 8, 2024.

Both of these 2 APIs for querying .NET xrefs published to Learn will be retired after the target date:

• https://learn.microsoft.com/api/xref/query?uid={uid}
• https://xref.docs.microsoft.com/query?uid={uid}

Actions Required: if you are using the above URLs to resolve xref reference to learn, change your docfx.json to use this xrefmap file:

{
  "build": {
    "xref": [
      "https://github.com/dotnet/docfx/raw/main/.xrefmap.json"
    ]
  }
}

We understand that this may cause inconvenience to some of our users, and we apologize for any disruption this may cause.

[filzrev]

Uploaded .xrefmap.json file size is about 131MB.
And it's downloaded when running docfx build command every times.

I though it's better to used pre-download xrefmap files.

Steps to use

1. Download xrefmap as XRefArchive (Zip Archived YAML file) with following command

docfx download xrefmap.zip --xref https://github.com/dotnet/docfx/raw/main/.xrefmap.json

2. Set docfx.json to use local zip fie.

"xref": [ "xrefmap.zip"]

---

In addition. When downloading xrefmap from https://github.com/dotnet/docfx/raw/main/.xrefmap.json
It's redirected to https://media.githubusercontent.com/media/dotnet/docfx/main/.xrefmap.json
(It's managed by git LFS.)

And HTTP compression seems not supported when downloading .xrefmap.json file.

[filzrev]

docfx download xrefmap.zip --xref https://github.com/dotnet/docfx/raw/main/.xrefmap.json

docfx download command that is commented above is not works as I've expected.
Because docfx repositories .xrefmap.json file use baseUrl: https://learn.microsoft.com/dotnet/api/.
And href value is set as relative URL from baseUrl.

But docfx download command rewrite baseUrl to https://github.com/dotnet/docfx/raw/main/
And href values are converted to absolute URL.

[glopesdev]

@yufeih We have been testing migrating away from using xrefmap.json for all .NET API types and found that certain cross-references which used to resolve with xrefService are not resolved unless the xrefmap.json is included. Specifically references to overloaded methods or generic types seem to be affected, e.g.:

• xref:System.String.Format*
• xref:System.Tuple`2

It would be nice if the built-in resolution mechanism was able to handle these so we could move away from xrefmap.json altogether.

[yufeih]

It would be nice if the built-in resolution mechanism

It might be possible for BCL types by changing the xref markdown extension to create an in memory compilation and resolve using the Learn URL resolver used in metadata command

[Thraka]

@yufeih Is there a spec on what the URL service expects incoming and what it returns to docfx? It would be nice if someone wanted to stand up their own server with their own xref files.

[Thraka]

@yufeih How often is the xref map updated? Where do you source the file from?

[dotMorten]

131mb? I'm seeing 323mb. This is a horrible solution over using the xref-service.

[filzrev]

131mb? I'm seeing 323mb.

I thought 131MB xrefmap is downloaded from this repository (Last updated about 6 month ago).
And 323MB xrefmap.json file is downloaded from learn.microsoft.com (that commented at #9821)

[gewarren]

@yufeih We have been testing migrating away from using xrefmap.json for all .NET API types and found that certain cross-references which used to resolve with xrefService are not resolved unless the xrefmap.json is included. Specifically references to overloaded methods or generic types seem to be affected, e.g.:

• xref:System.String.Format*
• xref:System.Tuple`2

It would be nice if the built-in resolution mechanism was able to handle these so we could move away from xrefmap.json altogether.

Have you tried formatting them like this?

• xref:System.String.Format%2A
• xref:System.Tuple%602

[Zastai]

I'm curious - SHFB is using code to generate the links (https://github.com/EWSoftware/SHFB/blob/master/SHFB/Source/BuildAssembler/BuildComponents/MicrosoftLearnMemberIdUrlResolver.cs); why can't docfx do the same?

Even if it does not handle 100% of cases, you would at least be able to process the complete xrefmap, stripping out all cases that are correctly handled by the code, and using the code for all cases not present in the filtered xrefmap.

docfx could then host a 'xrefmap' branch in this repository containing only such a filtered xrefmap file, with a daily/weekly action that updates it.
(In fact, that would already be desirable if it only needs a subset of the available information for its processing, as it would likely significantly reduce the size already.)

[Herrmel]

These xrefmaps also seem to be missing asp.net references (e.g. ComponentBase for Blazor) and other libraries hosted in microsoft learn (e.g. Powershell.Sdk). These also used to work with the old xrefservice. Are there xrefmaps for those other parts available somewhere?

[yufeih]

@Zastai

I'm curious - SHFB is using code to generate the links (https://github.com/EWSoftware/SHFB/blob/master/SHFB/Source/BuildAssembler/BuildComponents/MicrosoftLearnMemberIdUrlResolver.cs); why can't docfx do the same?

This should only impact referencing C# symbols in markdown files using the <xref> syntax, where we lack the compilation context to resolve the reference. Xrefmap is not required to resolve cref tags in C# XML comment.

[mikernet]

Do you know why WinUI 3 / WinAppSDK references are not getting resolved? Is this something MS needs to fix or is there something I can do to get these to resolve?

Even Windows Community Toolkit references resolve, for some reason it's just WinAppSdk specifically that has issues.

[Thraka]

@mikernet Only APIs in the xrefmap files will be resolved. AFAIK the WinUI/SDK is published independently of the normal .NET API, which is probably the reason why it's not included in the xrefmap file. You would need the xrefmap flie for the WinUI/SDK (wherever that is), or someone needs to pack it into the the xrefmap in this repository.

[mikernet]

@Thraka Yes, exactly. But even community toolkit APIs have made it into that xref map file, so WinAppSDK APIs bloody well should have as well 😅

[mikernet]

Oh sorry, I thought this was a different thread. What I said still holds true, but yeah not a docfx issue. I was hoping someone knew where said xref map was available, but after I posted the last comment I see that even in community toolkit docs the WinAppSDK references don't resolve, so it seems that they just haven't published xrefs.

[mikernet]

I opened this issue in microsoft-ui-xaml repo regarding this, for reference: microsoft/microsoft-ui-xaml#10132