NuGet package should not use system-level SHFBROOT by default

[Zastai]

Currently, when using a package reference to EWSoftware.SHFB in a .shfbproj, builds work just fine on a machine without SHFB installed (which is what the package is there for).

However, if there is a version of SHFB installed on the machine, the package will use that, regardless of any version mismatch.
This leads to surprise broken builds on machines with a different version installed.

In my particular case, the project has

  <ItemGroup>
    <PackageReference Include="EWSoftware.SHFB" Version="2020.3.6" IsImplicitlyDefined="true" />
    <PackageReference Include="EWSoftware.SHFB.NETFramework" Version="4.8.0" IsImplicitlyDefined="true" GeneratePathProperty="true" />
  </ItemGroup>

And this works fine for CI (with no SHFB on the build nodes).

However, building that project on a machine with the current SHFB release (2022.2.6) fails:

  Initializing
  ValidatingDocumentationSources
SHFB : error BE0065: BUILD FAILED: Unable to determine target framework version for project [C:\...\xxx.shfbproj]

due to some change in behaviour/requirements.

The NuGet packages should probably use their bundled tools by default, in order to have reproducible builds.

If necessary, a property could be provided to explicitly choose to allow the override via the system install (e.g. UseSystemSHFB).

[Zastai]

There seems to be an additional issue with code using the environment variable instead of the build property.

I added

  <PropertyGroup>
    <!-- Make sure a system-level SHFB install is ignored (taking the tools from the NuGet package). -->
    <SHFBROOT></SHFBROOT>
  </PropertyGroup>

as a workaround for the issue above.

This allowed the documentation build to start, only to end up failing shortly after:

CoreBuildHelp:
  Building C:\Stuff\Sources\natural-services.dotnet\Anubex.NaturalServices.Docs\Anubex.NaturalServices.Docs.shfbproj
  Initializing
  ValidatingDocumentationSources
  GenerateSharedContent
  GenerateApiFilter
  GenerateReflectionInfo
  TransformReflectionInfo
SHFB : error BE0043: Unexpected error detected in last build step.  See build log for details. [C:\...\xxx.shfbproj]
  Failed

The log has:

...
Locating components in the following folder(s):
    C:\Users\xxx\.nuget\packages\ewsoftware.shfb.netframework\4.8.0\build\..\Tools\
    <project folder>
    C:\ProgramData\EWSoftware\Sandcastle Help File Builder\Components and Plug-Ins\
    C:\Users\xxx\.nuget\packages\ewsoftware.shfb\2020.3.6\Tools\
...
  XslTransform (v2020.3.6.0)
  Copyright &#169; 2006-2020, Microsoft Corporation, All Rights Reserved.
  Portions Copyright &#169; 2006-2020, Eric Woodruff, All Rights Reserved.
XslTransform : error : The transform file &#39;C:\Program Files (x86)\EWSoftware\Sandcastle Help File Builder\\ProductionTransforms\ApplyVSDocModel.xsl&#39; could not be loaded. The error is: Could not find a part of the path &#39;C:\Program Files (x86)\EWSoftware\Sandcastle Help File Builder\ProductionTransforms\ApplyVSDocModel.xsl&#39;. [C:\xxx\output\obj\xxx\Release\Website\TransformManifest.proj]

So despite SHFBROOT being cleared at the MSBuild level, causing the tools matching the NuGet package to be used, some of the processing seems to use the SHFBROOT envvar instead, in this case trying to use a transform that is apparently no longer included with SHFB.

This means that using p:SHFBROOT=... on the MSBuild command line, to use a specific installation of SHFB, is also broken if the SHFBROOT environment variable exists and has a different value.

(Note: the apparently-unconditional use of C:\ProgramData\EWSoftware\Sandcastle Help File Builder\Components and Plug-Ins\ in the component lookup feels like another potential break to repeatable builds.)

[EWSoftware]

The standalone GUI and Visual Studio package are built against a specific version of SHFB and if you use them, they will always use related tools and build engine. The Visual Studio package only contains enough to support project management so it does require the full set of tools be installed. If SHFBROOT isn't defined, they look for the tools locally based on the executing assembly location which likely won't work for Visual Studio as the package doesn't contain the full build engine. Bottom line, if you use the GUI or Visual Studio, use the installed version of SHFB and define SHFBROOT if using Visual Studio.

The packages are for MSBuild and build servers and they'll run with or without SHFB installed. However, if you're mixing older and newer versions there is no guarantee that it will work. That's especially true if the packages are for an older version and you edit the project with a newer version of the GUI that then updates the project with breaking changes. Pick a consistent version and all will be well. You can use different versions as long as there are no breaking changes that affect the build engine. You need to review the release notes for the versions involved and any in between to see if that's possible.

You can avoid issues by making the necessary import statements conditional. New projects contain the proper conditions and if you add the packages using the SHFB GUI or Visual Studio, it will attempt to update the project so that it will work either way. The template contains an example of the properties to use and make conditional (lines 3, 47, and 50).

[Zastai]

To me, it's the "they'll run with or without SHFB installed" that's a design error. That makes builds non-deterministic; the exact same source tree may or may not build depending on whether a particular version of SHFB is installed.

For example, just because I am stuck using version X for my own projects, should not mean I'm unable to build someone else's project using a different version of the package.

The whole point of NuGet packages is to use specific versions side by side.