After Visual Studio update - docfx does not work anymore :-(

[c-ohle]

Operating System: Windows 11 Pro

DocFX Version Used: docfx 2.59.1.0

Template used: statictoc

Steps to Reproduce:

Latest VS update (today) Microsoft Visual Studio Community 2022 (64-bit) - Version 17.2.6

docfx:

Build succeeded with warning.
[22-07-13 12:35:02.625]Warning:MetadataCommand.ExtractMetadataWorkspace failed with: [Failure] Msbuild failed when processing the file 'C:\Users\cohle\Desktop\RationalNumerics\System.Numerics.Rational\System.Numerics.Rational.csproj' with message: Methode nicht gefunden: "System.ReadOnlySpan1<Char> Microsoft.IO.Path.GetFileName(System.ReadOnlySpan1)".
[22-07-13 12:35:02.628]Warning:[MetadataCommand.ExtractMetadata]Project 'C:\Users\cohle\Desktop\RationalNumerics\System.Numerics.Rational\System.Numerics.Rational.csproj' does not contain any documents.
[22-07-13 12:35:02.629]Warning:[MetadataCommand.ExtractMetadata]No metadata is generated for System.Numerics.Rational.
3 Warning(s)
0 Error(s)

For project - URL: https://github.com/c-ohle/RationalNumerics

Any quick workaround?

[KalleOlaviNiemitalo]

I guess DocFX is shipped with older assemblies that are then not compatible with what MSBuild requires nowadays.

A workaround would be to first run MSBuild to compile the sources to DLL and XML files, and then configure DocFX to read the DLL files rather than csproj files. That way, MSBuild and DocFX are in separate processes, and each can use its own assembly versions without conflict.

[c-ohle]

Hi, thanks for the quick response.
But how to configure DocFX to read the dll files and not the csproj files?
(I think many others will need this information as well)

[paulushub]

@c-ohle I do not know if I understand the problem. I created a DocFx project in the project directory, changed the JSON file as follows. I built it with DocFx 2.59.1.0 and DocFx 2.59.3.0 without any problem:

{
  "metadata": [
    {
      "src": [
        {
          "files": [
            "System.Numerics.Rational.csproj"
          ],
        "src": "../System.Numerics.Rational/"
        }
      ],
      "dest": "api",
      "disableGitFeatures": false,
      "disableDefaultFilter": false
    }
  ],
  "build": {
    "content": [
      {
        "files": [
          "api/**.yml",
          "api/index.md"
        ]
      },
      {
        "files": [
          "articles/**.md",
          "articles/**/toc.yml",
          "toc.yml",
          "*.md"
        ]
      }
    ],
    "resource": [
      {
        "files": [
          "images/**"
        ]
      }
    ],
    "overwrite": [
      {
        "files": [
          "apidoc/**.md"
        ],
        "exclude": [
          "obj/**",
          "_site/**"
        ]
      }
    ],
    "dest": "_site",
    "globalMetadataFiles": [],
    "fileMetadataFiles": [],
    "template": [
      "default"
    ],
    "postProcessors": [],
    "markdownEngineName": "markdig",
    "noLangKeyword": false,
    "keepFileLink": false,
    "cleanupCacheHistory": false,
    "disableGitFeatures": false
  }
}

The output log (edited the directories, for privacy):

[22-07-13 10:50:29.507]Info:[MetadataCommand.ExtractMetadata]Using msbuild K:\..\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin as inner compiler.
[22-07-13 10:50:29.961]Info:[MetadataCommand.ExtractMetadata]Loading projects...
[22-07-13 10:50:34.389]Info:[MetadataCommand.ExtractMetadata]'K:/../RationalNumerics/System.Numerics.Rational/System.Numerics.Rational.csproj' keep up-to-date since '2022/07/13 22:45:11', cached result from 'K:/../RationalNumerics/docfx/api' is used.
[22-07-13 10:50:34.395]Info:[MetadataCommand]Completed Scope:MetadataCommand in 4959.0067 milliseconds.
[22-07-13 10:50:34.516]Info:[BuildCommand]6 plug-in(s) loaded.
[22-07-13 10:50:34.543]Info:[BuildCommand]No files are found with glob pattern apidoc/**.md, excluding obj/**,_site/**, under directory "K:\..\RationalNumerics\docfx"
[22-07-13 10:50:34.544]Info:[BuildCommand]No files are found with glob pattern images/**, excluding <none>, under directory "K:\..\RationalNumerics\docfx"
[22-07-13 10:50:34.565]Info:[BuildCommand]Markdown engine is markdig
[22-07-13 10:50:34.840]Info:[BuildCommand.BuildCore.Build Document]Max parallelism is 4.
[22-07-13 10:50:35.397]Info:[BuildCommand.BuildCore.Build Document.CompilePhaseHandlerWithIncremental.ConceptualDocumentProcessor]Building 0 file(s) in ConceptualDocumentProcessor(BuildConceptualDocument=>CountWord=>ValidateConceptualDocumentMetadata)...
[22-07-13 10:50:35.397]Info:[BuildCommand.BuildCore.Build Document.CompilePhaseHandlerWithIncremental.TocDocumentProcessor]Building 3 file(s) in TocDocumentProcessor(BuildTocDocument)...
[22-07-13 10:50:35.397]Info:[BuildCommand.BuildCore.Build Document.CompilePhaseHandlerWithIncremental.ManagedReferenceDocumentProcessor]Building 0 file(s) in ManagedReferenceDocumentProcessor(BuildManagedReferenceDocument=>ValidateManagedReferenceDocumentMetadata=>ApplyOverwriteDocumentForMref=>FillReferenceInformation)...
[22-07-13 10:50:35.680]Info:[BuildCommand.BuildCore.Build Document.LinkPhaseHandlerWithIncremental.UpdateContext]0 external references found in 1 xref maps.
[22-07-13 10:50:35.771]Info:[BuildCommand.BuildCore.Build Document.LinkPhaseHandlerWithIncremental.Apply Templates]Applying templates to 3 model(s)...
[22-07-13 10:50:36.123]Info:[BuildCommand.BuildCore.Build Document]XRef map exported.
[22-07-13 10:50:36.277]Info:[BuildCommand.Postprocess]Manifest file saved to manifest.json.
[22-07-13 10:50:36.321]Info:[BuildCommand]Completed building documents in 1801.211 milliseconds.
Serving "K:\..\RationalNumerics\docfx\_site" on http://localhost:8080

[c-ohle]

@paulushub, thanks a lot for your efforts. Is it maybe because have the docfx folder beside - not inside the project?
But before this was no problem. Should I send the folder as zip?

[paulushub]

Should I send the folder as zip?

OK, lets see it.

[c-ohle]

RationalNumericsDoc.zip

[paulushub]

@c-ohle It seems to work fine on my system.
Please delete the RationalNumericsDoc\obj\.cache folder and try it again.

[c-ohle]

I deleted the cache more than once. Sure that you have the latest VS update?

[c-ohle]

Morning, it seems to be a Microsoft issue. I debugged docfx (unchanged). As you can see, it crashes in Microsoft.Build and has nothing to do with docfx or wrong pathes. Maybe it would help to upgrade the packages, but I know, the dependencies, new conflicts etc.
Maybe it's because I also have the latest VS2022 preview installed for .NET7 development. But before this was never a problem together with docfx, it started after the last official VS2022 community update.
I'll do some more debugging, if I find a solution I will let you know.

[paulushub]

I deleted the cache more than once.

That was the only problem I had. VS is updated, here is the copy and paste from the About Dialog:

Microsoft Visual Studio Community 2022 (64-bit) - Current
Version 17.2.6

Have you made changes to your project? I am only using the codes in the Github repository.

[c-ohle]

hi, no changes, full-build and debug

[c-ohle]

Before there was only one function GetFileName(string path)
now they added GetFileName(ReadOnlySpan<char> path)
Probably the old Nuget versions of MS.Build don't like Span's

[GeertvanHorrik]

Having the same issues with other tooling (not docfx). I suspect that it is something that changed in MSBuild (I do have preview installed, but it also happens to the stable versions).

Maybe the SDK version that shipped last Patch Tuesday?

[paulushub]

Maybe the SDK version that shipped last Patch Tuesday?

@GeertvanHorrik Thanks, we are getting somewhere now. I was wondering why I could not reproduce the error.

[paulushub]

But how to configure DocFX to read the dll files and not the csproj files?

@c-ohle The configuration is similar to the *.csproj, you may have to be more specific about the location. Any of the following worked for me:

"metadata": [
{
  "src": [
    {
      "files": [
        "System.Numerics.Rational.dll"
      ],
      "src": "../RationalNumerics/System.Numerics.Rational/bin/Debug/net6.0"
    }
  ],
  "dest": "api",
  "disableGitFeatures": false,
  "disableDefaultFilter": false
}
],

or

"metadata": [
{
  "src": [
    {
      "files": [
        "*.dll"
      ],
      "src": "../RationalNumerics/System.Numerics.Rational/bin/Debug/net6.0"
    }
  ],
  "dest": "api",
  "disableGitFeatures": false,
  "disableDefaultFilter": false
}
],

[c-ohle]

If that was all it would be great. Good work. I will try...
(I have already reactivated an old laptop so that I can use over network...)

[c-ohle]

Great, it works, (After delete the cache of course :-) )

[francoistanguay]

FYI, we have the same exception, that started appearing with 17.3 Preview 3 in Uno, possibly in our Source Generators, for users that had LangVersion forced at 8.0 in their project: unoplatform/uno#9297

[c-ohle]

@francoistanguay, yes that is exactly the same. I have already reported this in the appropriate dev channel.

I'm working on 3D modeling algorithms based on rational arithmetic to avoid epsilon and robustness problems.
This was primarily intended for CAD needs, 3D printing, etc., but is now fast enough for real-time in animation.
Could you use this for Uno? Examples: here, here, here

[tig]

FWIW, while this work around works, it runs MUCH slower.

I don't think this issue should be closed until VS fixes the underlying issue that broke it!

Here's the root issue: dotnet/msbuild#7832

[airbreather]

I don't think this issue should be closed until VS fixes the underlying issue that broke it!

The workaround of using the .dll files instead of the .csproj files gives a worse user experience for me than just holding our build server's version of Visual Studio Build Tools back at 17.2, which is obviously not a viable long-term solution, so I also would appreciate keeping an issue open for this.

For example, using .csproj files, it correctly identifies structs as structs (after finding a better workaround for #8120, anyway), but when using the .dll files, it seems to call them classes that just so happen to inherit from ValueType. I haven't gone further than that to see if there's anything else that the .dll version gets "wrong" that the .csproj version gets "right".

[vers-one]

when using the .dll files, it seems to call them classes that just so happen to inherit from ValueType. I haven't gone further than that to see if there's anything else that the .dll version gets "wrong" that the .csproj version gets "right".

Another example is the enumerations which are shown as sealed classes derived from System.Enum.

[c-ohle]

Hi, no bug as it is a new NET 7 feature. Maybe it's related to this issue, but in any case, it would be nice to get support. The new operator checked - for the todo collection.

[Arlodotexe]

While implementing the workaround for this (using the DLL instead of the csproj), I ran into this issue again: #7035, except the workaround of "just run it twice" doesn't seem to work when using the DLL.

Had limited success with Ubuntu on WSL via mono-devel (#5082), but that doesn't work in CI because they come preinstalled with the "Xamarin" flavor of mono-devel, and even after uninstalling and reinstalling the correct version, docfx fails to run. Apparently we've been waiting on .NET Core support since 2016 (see #138), so using Linux isn't a good option either.

I'm no stranger to dealing with bugs and workarounds, but we're fully blocked here until something gets fixed.

[Arlodotexe]

Issue is still present on 17.3.3. Fresh clone, and recently wiped PC -- this machine has never had VS preview installed.

[c-ohle]

@Arlodotexe Thanks for letting us know before we do the same and waste time.

[Lulalaby]

While implementing the workaround for this (using the DLL instead of the csproj), I ran into this issue again: #7035, except the workaround of "just run it twice" doesn't seem to work when using the DLL.

Had limited success with Ubuntu on WSL via mono-devel (#5082), but that doesn't work in CI because they come preinstalled with the "Xamarin" flavor of mono-devel, and even after uninstalling and reinstalling the correct version, docfx fails to run. Apparently we've been waiting on .NET Core support since 2016 (see #138), so using Linux isn't a good option either.

I'm no stranger to dealing with bugs and workarounds, but we're fully blocked here until something gets fixed.

Even I tried because it breaks most of our lib docs ci.
No chance at all.

If I read correctly, it is msbuild right? Any chance to replace that manually?

[mawosoft]

With GitHub's CI images, I only had the problem with windows-latest, the DocFx builds run fine for me on ubuntu-latest and macos-latest.

• Package ref to docfx.console 2.59.3 in a NoTargets project.
• Explicit SDK version 6.0.400 in global.json
• csproj sources in docfx.json
• Explicitly build the sources before the docs.

Successful CI run with docfx build on Windows disabled: https://github.com/mawosoft/Mawosoft.Extensions.BenchmarkDotNet/actions/runs/2944501729

[vers-one]

This workaround proposed by jskeet works even with windows-latest for me.

[Lulalaby]

With GitHub's CI images, I only had the problem with windows-latest, the DocFx builds run fine for me on ubuntu-latest and macos-latest.

This fix works fine
Thanks you! That saved me 😅

Our changes: here

Hope microsoft still fixes it tho.

@vers-one thanks for the other method, didn't test tho because the first one is easier for me

[airbreather]

the workaround isn't appropriate when trying to run this in CI. DocFX should work out of the box, without these workarounds.

While I can't reopen it personally, I've been waiting for the supposed fix to make it into a new release of docfx.console so that I can try it out myself before asking for anything further to be done about this.

@asklar After updating my docfx.console reference to 2.59.4, I can confirm that the issue is completely resolved for me.

[carinae]

Same issue with all my projects, seems not able to build the metadata from the project file *.csproj anymore.
due to missing method :
'System.ReadOnlySpan1<Char> Microsoft.IO.Path.GetFileName(System.ReadOnlySpan1)'.

Visual studio Version 17.5.4
docfx nuget 2.59.0 (latest available)

It seems solved on docfx console 2.59.4, any chance to have an updated nuget ?

[carinae]

Version 2.59.4 is ok and build is working again but just needed to install it via the Package manager

PM>NuGet\Install-Package docfx.console -Version 2.59.4