[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 tohttps://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