dotnet Command Line Build Fails with 2025.9.30 Release under Windows Environment.

[StephenHidem]

Executing msbuild in the developer command prompt succeeds. Executing dotnet in the developer command prompt fails with BHT0002 error. My project is using EWSoftware.SHFB (2025.9.30) and EWSoftware.SHFB.NET (10.0.0) from NuGet.

• Environment: Windows 11
• Visual Studio 2022 Developer Command Prompt
• msbuild command line (my .shfbproj): msbuild Documentation\Documentation.shfbproj -t:Build -p:configuration=Debug
• dotnet command line (my .shfbproj): dotnet build Documentation\Documentation.shfbproj --configuration Debug

Console output from failed build:
C:\Users\Steph\source\repos\AntPlus>dotnet build Documentation\Documentation.shfbproj --configuration Debug
Restore complete (1.1s)
Documentation failed with 1 error(s) (0.1s)
SHFB : error BHT0002:
Unable to build project 'C:\Users\Steph\source\repos\AntPlus\Documentation\Documentation.shfbproj': Sandcastle.Cor
e.BuildEngine.BuilderException: Error reading project from 'C:\Users\Steph\source\repos\AntPlus\Documentation\Docu
mentation.shfbproj':
Invalid or missing SHFBSchemaVersion
---> Sandcastle.Core.BuildEngine.BuilderException: Invalid or missing SHFBSchemaVersion
at SandcastleBuilder.MSBuild.HelpProject.SandcastleProject.LoadProperties() in C:\GH\SHFB\SHFB\Source\Sandcastl
eBuilderMSBuild\HelpProject\SandcastleProject.cs:line 1805
--- End of inner exception stack trace ---
at SandcastleBuilder.MSBuild.HelpProject.SandcastleProject.LoadProperties() in C:\GH\SHFB\SHFB\Source\Sandcastl
eBuilderMSBuild\HelpProject\SandcastleProject.cs:line 1928
at SandcastleBuilder.MSBuild.HelpProject.SandcastleProject..ctor(Project existingProject) in C:\GH\SHFB\SHFB\So
urce\SandcastleBuilderMSBuild\HelpProject\SandcastleProject.cs:line 1693
at SandcastleBuilder.MSBuild.BuildHelp.Execute() in C:\GH\SHFB\SHFB\Source\SandcastleBuilderMSBuild\BuildHelp.c
s:line 405

Build failed with 1 error(s) in 1.9s

[EWSoftware]

Something has changed when running under dotnet build. The copy of the project the build task creates no longer contains any of the project properties. I'm not sure why since it looks like ToProjectRootElement should still copy them. It gets the file items but none of the properties. It just creates an empty PropertyGroup element.

Way back when SHFB was first updated to use MSBuild, the executing project was accessible to the build task so it was much easier to just get it rather than pass all the properties and file items to the build task and create a project from those values. Over time, that changed and the project instance was made internal so I resorted to some hacks with reflection to get at it and create a copy. It looks like I may have to rework it to do things by more conventional means which is probably long overdue.

In the meantime, you can work around the issue by specifying the command line property option /p:AlwaysLoadProject=True. That forces it to load a copy of the project rather than trying to use the executing instance. The only downside is that any command line property overrides will be ignored. You'll see a BHT0001 warning about that but if you aren't using property overrides, it shouldn't be an issue.

[StephenHidem]

I verified your workaround and it works for my Sandcastle project. I don't have any property overrides, so I can proceed with my efforts building help files under Linux/Github. I do get the BHT0001 warning.

[philipp-naused]

Building with MSBuild 18 (Visual Studio 2026) has the same issue.
Adding <AlwaysLoadProject>true</AlwaysLoadProject> works as a workaround.

[Peter-Simpson]

The work-round worked for me in my MSBuild script (see below), but per Eric's warning, the PresentationStyle parameter override was ignored so I got the default modern HTML output rather than the configured HtmlHelp1 CHM format.

I'm happy to try a beta fixed version if that's available.

Many thanks, Peter

<!-- Restore packages and build the Library Help  -->
		<MSBuild Projects="$(LibraryHelpDirectory)\$(LibraryHelpVSSolution)" 
				 Targets="Restore;Build" 
				 Properties="AlwaysLoadProject=True;Platform=$(LibraryBuildPlatform);Configuration=$(LibraryBuildConfiguration);HelpFileFormat=HtmlHelp1;PresentationStyle=VS2013"
				 />

[EWSoftware]

The workaround for overriding project properties is to use an override project file specified with the CustomBeforeSHFBTargets or CustomAfterSHFBTargets property. Either one works. For command line builds just add /p:CustomBeforeSHFBTargets=C:\Full\Path\To\Overrides.proj (a fully qualified path is required).

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <HelpFileFormat>HtmlHelp1</HelpFileFormat>
    <PresentationStyle>VS2013</PresentationStyle>
  </PropertyGroup>

  <PropertyGroup>
    <!-- Add the overridden properties as the value of the SubstitutionTags property -->
    <SubstitutionTags>$(SubstitutionTags);HelpFileFormat=$(HelpFileFormat);
        PresentationStyle=$(PresentationStyle)</SubstitutionTags>
  </PropertyGroup>

</Project>

For the MSBuild task, the below should work.

<MSBuild Projects="$(LibraryHelpDirectory)\$(LibraryHelpVSSolution)" 
    Targets="Restore;Build" Properties="AlwaysLoadProject=True;Platform=$(LibraryBuildPlatform);
    Configuration=$(LibraryBuildConfiguration);CustomBeforeSHFBTargets=$(LibraryHelpDirectory)\Overrides.proj"/>

Once the new release is published, AlwaysLoadProject=True can be removed.

[Peter-Simpson]

Thanks for the suggestion Eric but it doesn't seem to work. I wonder whether the CustomBeforeSHFBTargets property is also being ignored per the error message:

SHFB : warning BHT0001: Unable to get executing project: Unable to obtain matching project from the global collection. The specified project will be loaded but command line property overrides will be ignored.

[EWSoftware]

CustomBeforeSHFBTargets is part of the targets file and effectively imports the properties and puts them in the SubstitutionTags property. Those are applied after the project is loaded by the task. Try running it manually from the command line. Also, it's important the path to the overrides file is correct and fully qualified or it will be ignored.

[Peter-Simpson]

I have managed to get this going in two ways now: firstly using an <Exec> tag and secondly using an <MSBuild> tag. I have always used a fully qualified path, but what was throwing me was whether or not the path needed to be quoted.

The exec tag looks like this:

<Exec Command='MSBuild "$(LibraryHelpDirectory)\$(LibraryHelpVSSolution)" /p:AlwaysLoadProject=True /p:CustomBeforeSHFBTargets="$(LibraryHelpDirectory)\Overrides.proj" /p:Platform="$(LibraryBuildPlatform)" /p:Configuration=$(LibraryBuildConfiguration) /t:restore;build' ConsoleToMSBuild="true" WorkingDirectory="$(LibraryDirectory)" />

while the MSBuild tag looks like this:

<ExtraSHFBParameters>AlwaysLoadProject=True;CustomBeforeSHFBTargets=$(LibraryHelpDirectory)\Overrides.proj;/ExtraSHFBParameters>

<MSBuild Projects="$(LibraryHelpDirectory)\$(LibraryHelpVSSolution)" 
    Targets="Restore;Build" 
    Properties='$(ExtraSHFBParameters); Platform=$(LibraryBuildPlatform); Configuration=$(LibraryBuildConfiguration);'/>   

In the Exec tag I had to enclose the Overrides.proj path in quotes so that it was interpreted as a single string, without quotes it was interpreted as multiple strings depending on how many spaces there were in the path.

In the MSBuild tag I had to omit all quotes even though the path contained spaces. All my attempts to use single quote, double quote and the " character failed. Out of desperation I omitted them all and it worked!

Hopefully this may help someone else following down this path.