[Bug] xref is not included for v2.78.4

[gimlichael]

Describe the bug
Prior to v2.78.4, references to other documentation sites in build.xref was rendered perfectly. With the latest release, these are not included, e.g.:

  "build": {
    "xref": [
      "https://docs.cuemon.net/xrefmap.yml",
      "https://docs.savvyio.net/xrefmap.yml"
    ]
  }

To Reproduce
Include one or more xref references that your know your project depends on.
Compile with v2.78.3 - OK
Compile with v2.78.4 - NOK

Expected behavior
I would expect previous behavior, .e.g., members found in xref will be rendered.

Context (please complete the following information):

• Docfx version: 2.78.4

Additional context

Rendered with v2.78.3:

• https://docs.savvyio.net/api/dotnet/Savvyio.Messaging.MessageOptions.html
• https://github.com/codebeltnet/savvyio/blob/main/.docfx/Dockerfile.docfx
• https://github.com/codebeltnet/savvyio/blob/main/.docfx/docfx.json

Rendered with v2.78.4:

• https://versioning.codebelt.net/api/Codebelt.Extensions.Asp.Versioning.RestfulApiVersioningOptions.html
• https://github.com/codebeltnet/asp-versioning/blob/main/.docfx/docfx.json
• https://github.com/codebeltnet/asp-versioning/blob/main/.docfx/Dockerfile.docfx

Take note of IValidatableParameterObject and IParameterObject.

[filzrev]

Is it able to try re-generate xrefmap.yml files?

It seems these files are created by v2.67.5 or older version. (lower case char is sorted before capital case)

On v2.70.0 or later version of docfx enable InvariantGlobalization mode.
So string are compared with Ordinal order.

And it failed BinarySearch on following code.
https://github.com/dotnet/docfx/blob/34a32eafd98b9d44d009e9a05c34e86060e26470/src/Docfx.Build/XRefMaps/BasicXRefMapReader.cs#L36C32-L36C33

[gimlichael]

I am not sure i follow you, @filzrev. If i use v2.78.3 - it works as expected. If i use v2.78.4 it does not work. I can see xrefmap.yml for Cuemon was created on November 12th.

When both host and docker runs v2.78.4 - NOK.
When host remains on v2.78.4 and docker is downgraded to v2.78.3 - OK.

I have not compared all your changes between these commits, but I assume something has changed given the concrete result.

[filzrev]

As far as I've confirmed from v2.78.4 Release Note.
Xref related code seems not changed.

And when testing provided xref with <xref:concept-md>.
Following warning occurred on both docfx v2.78.3/v2.78.4

index.md: warning UidNotFound: 1 invalid cross reference(s) "xref:concept-md".

This warning seems to be caused by BinarySearch failure that relating InvariantCulture mode.

On xrefmap https://docs.cuemon.net/xrefmap.yml .
uid(concept-md) should be sorted on after Cuemon* uids (It's confirmed by locally build cuemon with docfx)
But published xref is not sorted as expected.

So I'm suspecting published xref is not updated.

---

If it able to provide minimum reproduceable code.
I'll try to debug issues.

[gimlichael]

@filzrev i think i get what you are writing - however, keep in mind, that xrefmap.yml is created on each new build. Only difference i see is how its generated from the underlying OS. The one you refer to (which was build using this image: https://github.com/codebeltnet/docfx), was build using v2.78.4 and not the old version you suggest.

Here is my workflow:

• host is invoking docfx metadata docfx.json
• files are copied to a container which invokes docfx build
• result is copied to official nginx container

Again, the only noticeable difference (but, imo unrelated) is the ordering of the generated xrefmap.yml which differs from OS to OS.
I have attached the host generated yml file as well as the container generated yml file.

xrefmap-alpine.yml

xrefmap-windows.yml

The two examples i started out with in this issue both reference http://docs.cuemon.net/xrefmap.yml - only difference is, that it works for that build with v2.78.3 - it does not work with the one build from v2.78.4.

That is why my assumption is, that something did in fact happen between these two builds.

I hope it make sense - thank you for looking into this.

[filzrev]

It seems xrefmap file that generated by Alpine image is sorted in an unexpected order.
(Invariant Globalization Mode is not works as expected)

I've reported observed issue to dotnet-docker repository issue.
dotnet/dotnet-docker#6838

As a temporary workaround.
it's expected to be fixed by add following setting to Dockerfile for docfx?

ENV DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=true

only difference is, that it works for that build with v2.78.3 - it does not work with the one build from v2.78.4.

It seems v2.78.3 docker image is based on .NET 8 SDK image.
So sort order issue is not happens. (Sort order issue is occurred when using Alpine .NET SDK 9 or later image)
https://github.com/codebeltnet/docfx/blob/b30a379ba5c29bed6115fe6b571259775f788c57/Dockerfile

[gimlichael]

@filzrev - eureka! I tried the proposed workaround. Now it works as expected.

Curious; so i see this error because of using Alpine with .NET 10 instead of .NET 8?

I am still slightly surprised, that the xref renderer is relying on sort order in order to work .. but I am sure you guys had your reasons.

Thank you so much for your kind help resolving this matter - keep up the good work.

Should I close this issue as I assume #10907 covers the "bug"?

[filzrev]

Should I close this issue as I assume #10907 covers the "bug"?

Please close this issue if it's resolved by temporary workaround.

It seems to be caused by .NET 9 behaviors changes (or it might be regression).
I've created issue at dotnet/runtime repository (https://github.com/dotnet/runtime/issues/121899)

[gimlichael]

Closed with thanks as proposed workaround works like a bliss.