docfx
docfx copied to clipboard
dotnet
DocFX can't generate Api docs when VS is not installed
Operating System: Windows
DocFX Version Used: 2.58.9.0
Template used: default
Steps to Reproduce:
- I have Build Tools installed on my CI build server (Windows) with no full blown IDE. DocFX can't compile my projects for Api documentation.
Expected Behavior: Generate yml files under api directory.
Actual Behavior: Content documentation is generated but not Api. Here is what I see in logs:
[MetadataCommand.ExtractMetadata]Using msbuild C:\Program Files (x86)\Microsoft Visual Studio\2017\BuildTools\MSBuild\15.0\Bin as inner compiler. [MetadataCommand.ExtractMetadata]E:/BuildAgents/2.165.2/1/_work/77/s/Proj.Docs/src/App.Core/src/App.Core.Common.csproj)Workspace failed with: [Failure] Msbuild failed when processing the file 'E:\BuildAgents\2.165.2\1\_work\77\s\Proj.Docs\src\App.Core\src\App.Core.Common.csproj' with message: The SDK 'Microsoft.NET.Sdk' specified could not be found. E:\BuildAgents\2.165.2\1\_work\77\s\Proj.Docs\src\App.Core\src\App.Core.Common.csproj
Without the SDK available, it can't generate the metadata needed, since it won't be able to understand the project or infer the type parameters. Once you have generated the API Yaml, you don't need VS, but you will need it to analyze your code.
@sameer-kumar did you find a workaround for this issue? I'm facing the same issue with older docfx versions, however, if I use the latest I get a StackOverflow exception.
@laura-rodriguez nope. I gave up. I'm now using build machine with VS installed.
I’m assuming this is the metadata step? There’s no way to analyze and generate metadata from a project and source code without having the tools to interpret that.
All you really need are the SDKs that your projects rely on, so they can be understood. (yes build tools also install these if you enable the right workloads)
Also, in a newer .NET SDKs (starting from .NET 6), special environment variable is required in some cases:
SET MSBuildEnableWorkloadResolver=false
I have 2 VMs with agents - VM1 with full IDE and VM2 with just Build Tools and SDKs. My code projects compiles fine and successfully with VM2. However, I can't get DocFX to generate API docs. But it works fine if I use VM1 and all docs are generated.
Docfx uses MSBuildWorkspace to analyze projects. There is a good article on how MsBuildWorkspace works and how to prepare an environment:
The recommended way to set up MSBuild is to install Visual Studio 2017 (or newer) or the Build Tools for Visual Studio 2017 (or newer) on the machine that MSBuildWorkspace will run on. The important detail is to ensure that the installation has the necessary workloads and components to support the projects you'll be loading. For example, if C# is not installed, you will not be able to load C# projects. Similarly, if a project targets .NET Framework 4.7.3, that targeting pack must be installed. A good rule of thumb is, if you can build the project with MSBuild at the command-line, MSBuildWorkspace should be able to load it.
For this particular case, the latest version should load Microsoft.NET.Sdk once you have the corresponding .NET SDK installed.
