Metadata source file set to csproj not generating metadata

[CalvinWilkinson]

Operating System: (Windows or Linux or MacOS) Windows

Visual Studio Version:

Microsoft Visual Studio Community 2022
Version 17.3.1
VisualStudio.17.Release/17.3.1+32811.315
Microsoft .NET Framework
Version 4.8.04161

DocFX Version Used: v2.59.3 (Installed via chocolaty)

Template used: (default or statictoc or contain custom template) default

Steps to Reproduce:

1. Create basic bare bones docfx project just like in walkthroughs
2. Create simple C# project that sits next to the same base folder as the docfx project
3. Run docfx .\docfx.json --serve command

• Executed in the terminal in the docfx project directory

Expected Behavior: Metadata to be generated

Actual Behavior: No metadata generated

---

More Context

I have tried pointing to other things besides the csproj file such as the library itself as also the .cs files.

If pointing to the library, the metadata is generated but the documentation is all barebones method signatures with no /// comment docs added. I assume this is normal behavior and is due to reflection. 🤷🏼

If pointing to the .cs files, I get the best result by getting the /// comments in the metadata, but some of the metadata is messed up. Things like <list type="bullet"></list> and <see cref="System.Drawing.Color"/> do not work.

I also tried installing Visual Studio 2019 just in case and that still did not work when pointing to the project file. I am currently using the latest version of Visual Studio 2022 Community with version being ****

After all of this trouble, I doubled back and simply followed the walkthroughs exactly and still got the same result. At this point, I feel like new updates to MSBuild is causing the issue when pointing to the project file?

---

Results After Command:

Folder contents in VSCode:

What page looks like when served:

[vers-one]

Yep, the new version of MSBuild broke DocFX.

[paulushub]

@CalvinWilkinson As pointed out by @vers-one, this issue is already reported.

[CalvinWilkinson]

Thanks for the update @paulushub and @vers-one!!

[CalvinWilkinson]

@paulushub and/or @vers-one

Quick Update

As I was reading through #8136 and #8097, I seen a comment by @KalleOlaviNiemitalo mentioning a workaround.

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.

Before I was only producing the dll. I was getting the metadata generated correctly, but without all of the triple-slash comments. Once I added the XML documentation file, I got both. This workaround is fine for me but, I still have some issues.

Issues:

1. Bullet and number lists are not rendering correctly.
   • <list type="bullet"></list>
   • <list type="number"></list>
2. The XML element <see langword="string"/> that is not rendering correctly.
3. System.Drawing.Color cref not rendering correctly as a link.
   • I am using <see cref="Color"/>
4. <example></example> not rendering at all
5. <code></code> not rendering at all

XML code in project with issues:

1. Bullet list nested in number list
2. Lang word
3. Color cref
4. example and code XML

Below are the results:

Result of <see langword="string"/> and <list type="number"></list> issues:

Result of <list type="bullet"></list> and <see cref="Color"/> issues:

I was going to create some issues for these problems, but wanted to touch base with you first. Let me know if I should create some issues.

Good news is that I am closer to getting all of this working. 🙂

Thanks for help!! 🙏🏼

[vers-one]

@CalvinWilkinson, I am not an expert on DocFX (I started to use it just a few days ago myself) but that suggestion doesn't seem like a good workaround to me as it can't produce the same documentation as DocFX does when it uses the source code directly (possibly due to inherent metadata loss when the source code gets compiled into a .NET assembly).

I am using this workaround instead.

[CalvinWilkinson]

@vers-one Thank you for the info. Greatly appreciate that. I myself only started using docfx about a month ago. I am new as well. I will check out that workaround. 🙏🏼

[CalvinWilkinson]

@yufeih Quick update on this one. I finally got around to getting back to this issue. I updated to v.2.61.0 to see what is working and what is not.

Things Working:

1. The <list type="bullet"/> are now rendering correctly.
2. The <list type="number"/> are now rendering correctly.
3. The <see langword=""/> are now working correctly.

Things still not working:

1. The System.Drawing.Color type reference using <see cref=""/> XML in the remarks section.

   Note The XML used for this is <see cref="Color"/>.<see cref="Color.A"/> and the intended result is Color.A.

Maybe not working:

1. The reference to the System.Drawing.Color type in the Returns and Parameters sections.
   • I am not sure if these are suppose to be links that point to the MS docs or not.

Here is the screen shot of the actual output.

[yufeih]

@CalvinWilkinson It seems the described problem is similar to https://github.com/dotnet/docfx/issues/8488 and can be addressed by adding an xrefService property.