[Bug] Error CS0234 when Upgrading from 2.61.0 to 2.62.xx

[kevingostomski]

Describe the bug

I wanted to migrate the Docfx Version from 2.59.2 to 2.62.1 but apperently in addition to issue #8428, I can not build documentation from source code (.cs file extensions). The Error CS0234 appears, which means that he does not find the namespace. Version 2.61.0 works as exptected and I can build the automated API documentation via .cs file extensions with the same docfx.json which I used for 2.59.2. When I build the API documentation with the .sln file or the .csproj extension in Version 2.62.xx, than it works too, but I do not need complete documentation for all namespaces and classes. I can use Filter APIs to exclude the unnecessary namespaces if I work with the .sln, but that does not seem right if it worked in version 2.61.0. For myself, I can not say what change from the release notes in version 2.62.0 broke the expected behavior.

To Reproduce
Steps to reproduce the behavior:

1. Project with API documentation for specific .cs files
2. docfx
3. docfx serve _site

Expected behavior
Functional output like in version 2.61.0

Context (please complete the following information):

• OS: Windows
• Docfx version: [e.g. 2.62.x]

Additional context
Unfortunately, I can not send a .zip file with the complete project and the two solutions which I try to build an automated API for because of my work regulations but you can see in the following the docfx.json which works in version 2.59.2 and 2.61.0 but is broken in 2.62.x. In the picture, you see the msbuild error CS0234.

Error CS0234

docfx..json

{
  "metadata": [{
      "src": [{
        "files": ["src/AdamWS/**/ADAMAPIv01.asmx.cs", "src/AdamWS/**/IdmAPIv01.asmx.cs", "src/AdamWS/**/DataObjects/**.cs"],
        "exclude": ["_site/**", "**/bin/**", "**/obj/**", "**/[Tt]ests/**"]
      }],
      "dest": "adam/soap-api",
      "disableGitFeatures": false,
      "disableDefaultFilter": false
    },
    {
      "src": [{
        "files": ["src/CachedExchangeWS/**/AGAPIv02.asmx.cs", "src/CachedExchangeWS/**/AGAPIv02_1.asmx.cs", "src/CachedExchangeWS/**/APIv05_1.asmx.cs", "src/CachedExchangeWS/**/APIv05_2.asmx.cs", "src/CachedExchangeWS/**/DataObjects/*.cs"],
        "exclude": ["_site/**", "**/bin/**", "**/obj/**", "**/[Tt]ests/**"]
      }],
      "dest": "mail/soap-api",
      "disableGitFeatures": false,
      "disableDefaultFilter": false
    }
  ],
  "build": {
    "content": [{
        "files": ["adam/**.yml", "adam/**.md"]
      },
      {
        "files": ["mail/**.md", "mail/**.yml"]
      },
	  {
        "files": ["toc.yml", "index.md"]
      },
      {
        "files": ["changelog/**.md", "changelog/**/toc.yml"]
      },
      {
        "exclude": ["_site/**", "**/bin/**", "**/obj/**", "**/[Tt]ests/**"]
      }
    ],
    "resource": [{
      "files": ["images/**"]
    }],
    "overwrite": [{
      "files": ["_site/**.md"],
      "exclude": ["obj/**", "_site/**"]
    }],
    "dest": "_site",
    "globalMetadataFiles": [],
    "fileMetadataFiles": [],
    "template": ["default", "templates/singulinkfx", "plugins/memberpage.2.59.0/content"],
    "postProcessors": [],
    "markdownEngineName": "markdig",
    "noLangKeyword": false,
    "keepFileLink": false,
    "cleanupCacheHistory": false,
    "disableGitFeatures": false,
    "globalMetadata": {
      "_appTitle": "IT Center RWTH Aachen University",
      "_appName": "Doc Portal",
      "_appFaviconPath": "images/favicon.ico",
      "_appLogoPath": "images/rwth-itc.png",
      "_appFooter": "<strong>© IT Center RWTH Aachen University. All rights reserved.</strong>",
      "_copyrightFooter": " ",
      "_enableSearch": true,
      "_disableSideFilter": false,
      "_enableNewTab": true,
      "_disableContribution": false,
      "_disableBreadcrumb": false
    }
  }
}

[yufeih]

The change on strict compilation check triggered this error. Without strict compilation check, a C# file with compilation errors can sometimes still produce documentation, with weird problems in unknown places.

It doesn't seem like a good idea to officially support generating docs from a bad compilation.

[kevingostomski]

@yufeih Are you sure about that ? Because the whole projects in Visual Studio 2019 do not show any errors on building which includes compiling, packaging, testing and so on.

The error says, that he just does not find the using declaratives in version 2.62.x but in 2.61.0 it still seems to work. In the following, you see the file under src/AdamWS/**/ADAMAPIv01.asmx.cs. I opened the solution and you see in the console the building output with no errors.

For me, it sounds like a different problem.

[kevingostomski]

Here a .zip file API-Doc.zip so the problem should be clearer and can be run locally

[yufeih]

Setting metadata/src/files to csharp files is equivalent to creating an empty csproj that contains only the files matching the glob, not building an existing project and include documentation only for the cs files matching the glob .

The same error message would appear if you remove source code that does not match this glob pattern from the solution:

 ["src/AdamWS/**/ADAMAPIv01.asmx.cs", "src/AdamWS/**/IdmAPIv01.asmx.cs", "src/AdamWS/**/DataObjects/**.cs"]

[CrayonPastel]

It seems that versions later than 2.61.0 (including 2.63.1) take no account of the dependence relations among .csproj files, which .sln solution file defines; thus they cause CS0246 first, then CS0234 as a consequence.

Only versions later than 2.61.0 do not properly work, while docfx 2.61.0, msbuild, dotnet-build and stylecop perfectly do for the same set of source codes.

[CrayonPastel]

Please, revert ASAP the logic analyzing dependence among .csproj files to docfx 2.61.0 equivalent.
Even with docfx 2.66.0, CS0246 and CS0234 errors continue to occur.
The same source code fails to be compiled only by docfx 2.62.0 or later.

[yufeih]

@CrayonPastel Can you provide a minimal repro of the issue? It appears MSBuildWorkspace already does dependency analysis under the hood making the logic in docfx redundant.

[kevingostomski]

Here a .zip file API-Doc.zip so the problem should be clearer and can be run locally

@yufeih If this example is to big or not good enough, I created another project to test it. It is sill the same error CS0234 on docfx.console when trying to build the doc site, which you can see in the picture after every version like @CrayonPastel mentioned it. Opening the project in Visual Studio 2019 or 2022 does not generate build errors. I used version 2.64.0 trying to generate it.

Here the .zip file:

docfx_project.zip

To reproduce the error:

1. Download the .zip
2. Navigate to dir in cmd
3. Call docfx to generate and seeing the errors

If CrayonPastel want to provide another one, feel free.

[yufeih]

@kevingostomski @CrayonPastel,

When you set metadata.src.files to *.cs, docfx only builds the included cs files, ignoring the containing project's settings, like project references, assembly references, and compilation settings. That's why you're seeing CS0246 and CS0234 errors.

In version 2.61.0, csharp compilation errors and warnings weren't shown in the output. To achieve the same behavior in 2.66.0, you can set the allowCompilationErrors option to true. This will still display the errors but let the build continue, just like in 2.61.0.

If you want to eliminate the errors completely, try changing metadata.src.files to src/**/*.csproj. This will build the projects, which takes into account the references and settings in the csproj.

[CrayonPastel]

@yufeih
Thanks a lot. I have tried based on your advice.

The point I am raising is neither a single .csproj file or a set of .cs files under a single .csproj. What I mean is that I am expecting docfx to parse and compile the dependecies among .csproj files PRECISELY AS .sln SOLITION FILE DEFINES. docfx 2.61.0, msbuild and stylecop parse so, while docfx 2.62.0 or later does not.

When I specify ".cs" for "src" in the docfx.json as you advised, it globs all the .cs files without considering the dll dependencies; however, it throws CS0246 meaning that some classes (or .cs files under other ".csproj"s) fail to be found. It is quite natural, because the compiler handling a certain source folder cannot locate or find the namespace (dll) or the reference folder containing the .cs files controlled by other .csproj files.

On the other hand, when I specify ".csproj" for "src" in the docfx.json, it does consider the dll references; however, it does not parse precisely the dependencies among .csproj files defined in the .sln solution file, in docfx 2.62.0 or later. As a result, if the docfx starts to parse earlier a subsequent dll that refers to another dll, it throws CS0246 and CS0234 errors. In other words, the namespaces (dlls) to be imported as "using XXXX" fails to be found. This has not happened in docfx 2.61.0.

A certain solution file of mine defines .csproj depencencies as follows:

Project("{XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX00}") = "Lib1", "Lib1\Lib1.csproj", "{XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX01}"
EndProject
Project("{XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX00}") = "Lib2", "Lib2\Lib2.csproj", "{XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX02}"
	ProjectSection(ProjectDependencies) = postProject
		{XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX01} = {XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX01}
	EndProjectSection
EndProject
Project("{XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX00}") = "Lib3", "Lib3\Lib3.csproj", "{XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX03}"
	ProjectSection(ProjectDependencies) = postProject
		{XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX01} = {XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX01}
		{XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX02} = {XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX02}
	EndProjectSection
EndProject
Project("{XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX00}") = "Main", "Main\Main.csproj", "{XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX99}"
	ProjectSection(ProjectDependencies) = postProject
		{XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX01} = {XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX01}
		{XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX02} = {XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX02}
		{XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX03} = {XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX03}
	EndProjectSection
EndProject

The solution should be compiled as Lib1.dll -> Lib2.dll -> Lib3.dll -> Main.exe, due to the dependencies included. docfx 2.61.0 and msbuild do so, while docfx 2.62.0 or later seems to try first to touch Main.exe, then to parse Lib3.dll, and it fails as a consequence.

I would appreciate your advice if you find any possible error in my docfx.json settings or anything else. I would like to report that I have detected that docfx 2.61.0 and 2.62.0 or later are not consistent in the terms of ".csproj"s dependency analysis.

[yufeih]

@CrayonPastel is there a minimal repro on the dependency problem you are describing? We should support automatic dependency analysis of <ProjectReference> defined in csproj files, this is an example config in our test site that references csproj with project dependencies.

[CrayonPastel]

Here's a set of minimal source code files and docfx materials -- Sample.zip.

I can compile the files in the "src" subfolder into an executable binary with "dotnet build" command, but I cannot generate a set of API documents with docfx 2.62.0+. "docfx metadata" fails with CS0246 errors, which indicate that a type or namespace cannot be found. The errors occur in the following files:

• SampleCode2.cs: Lib1 Library is not found
• SampleCode3.cs: Lib1 & Lib2 Libraries are not found
• Main.cs: Lib3 Library is not found

While trying to reproduce, I noticed that "docfx build" command can work without warning even with ver. 2.62.0+ after "docfx metadata" has been once executed with ver. 2.61.0. However, "docfx metadata" itself still cannot work with ver. 2.62.0+.