SHFBROOT and ComponentPath with NuGet in Azure DevOps

[eriksorngard]

Hello,

I am trying to move running SHBF to our Azure DevOps build pipeline, after running it locally for years, but have not been able to configure the SHFBROOT variable correctly.

I have installed the EWSoftware.SHBF and EWSoftware.SHBF.NETFramework packages in the .NET Framework project.

As the solution does not have a package folder when working locally with VS2019, I have not been able to come up with a valid SHFBROOT and ComponentPath. Just to see what happened, I also copied the two PackageReference items from the .NET framework project to the SHFB project.

So far, the .NET framework project builds as expected, after both the required packages have been installed by NuGet restore, before MSBuild throws an error because it has not found the SandcastleHelpFileBuilder.targets.

How can I determine what is the correct path to the targets file?

[tom-englert]

This is fixed in #720, however it looks like this has not been released yet for all framework versions, only the NETFramework 4.8.0 package sets the ComponentPath.

[EWSoftware]

The property file is in the core tools package and the .NET 4.8 version of the reflection data set package. If you're using those, I assume it should work.

[eriksorngard]

Thank you for your help, though I still get the error "Error MSB4019: The imported project "D:\SandcastleHelpFileBuilder.targets" was not found."

Initially I did not fully realize the difference between use of Packages.config and PackageReference, and the lack of a packages folder is of course due to this being a solution with only PackageReference projects. I have removed the ComponentPath and SHFBROOT variables from the SHFB project file, and added two package references:

  <ItemGroup>
    <PackageReference Include="EWSoftware.SHFB" Version="2019.9.15" />
    <PackageReference Include="EWSoftware.SHFB.NETFramework" Version="4.8.0" />
  </ItemGroup>

These are the latest versions available, and included in the SHFB project file before the failing line. Both packages are being installed, because of their inclusion i the .NET framework project.

Does the item group with PackageReference tags have to be located in a special place of the project file?

[eriksorngard]

I did manage to get SHFB working, but had to find out where the build pipeline is putting the PackageReference packages, and reference them with SHFBROOT and ComponentPath:

<PropertyGroup>
  <ComponentPath>C:\Users\VssAdministrator\.nuget\packages\ewsoftware.shfb.netframework\4.8.0</ComponentPath>
</PropertyGroup>
<PropertyGroup>
  <SHFBROOT Condition=" '$(SHFBROOT)' == '' ">C:\Users\VssAdministrator\.nuget\packages\ewsoftware.shfb\2019.9.15\tools</SHFBROOT>
</PropertyGroup>

[tom-englert]

Just tried by my own - looks like SHFB projects do not support nuget packages at all.

• Right click on a SHFB project shows "Manage Nuget Packages" disabled
• Nothing will be restored when manually adding a PackageReference

[EWSoftware]

As far as I know, that's always been the case. The packages have to be in the documented project in the solution rather than the SHFB project itself.

[eriksorngard]

When using PackageReference, the packages are neither in the SHFB project nor the doumented .NET framework project. They are only referenced from the documented project, which requires the long paths in my previous message to tell the build pipeline and SHFB where things are.

[tom-englert]

@eriksorngard @EWSoftware There is a simple workaround to use the nuget packages directly, without hardcoding the path to the nuget packages:
Add a new project (e.g. Documentation.build.csproj) in the same directory as your Documentation.shfb project, with the following content:

<Project ToolsVersion="Current" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" Condition="Exists('$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props')" />
  <PropertyGroup>
    <TargetFrameworkVersion>v4.6.2</TargetFrameworkVersion>
    <ProjectGuid>{45C2507A-D756-4383-AA29-145416FEF56C}</ProjectGuid>
  </PropertyGroup>
  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
  </PropertyGroup>
  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="EWSoftware.SHFB" Version="2019.9.15" />
    <PackageReference Include="EWSoftware.SHFB.NETFramework" Version="4.8.0" />
  </ItemGroup>
  <Import Project="Documentation.shfbproj" />
</Project>

Now do not build Documentation.shfb but the Documentation.build.csproj.

[eriksorngard]

Thank you for suggesting the additional project file. Running locally in Visual Studio, this works, but in the build pipeline, I am now unfortunately back to the old error message: I build the csproj project, and the shfbproj project do not know where SandcastleHelpFileBuilder.targets is.

Project "d:\a\1\s\Transformation Messages.sln" (1) is building "d:\a\1\s\Documentation\Documentation.build.csproj" (4) on node 1 (default targets).
d:\a\1\s\Documentation\Documentation.shfbproj(134,3): error MSB4019: The imported project "D:\SandcastleHelpFileBuilder.targets" was not found. Confirm that the path in the <Import> declaration is correct, and that the file exists on disk.

[tom-englert]

I tried locally with MSBuild, after setting the SHFBROOT environment variable to empty, and it worked all fine, now referencing the .targets from the nuget package.
Maybe SHFBROOT on your build server is not initially empty?

[tom-englert]

It's a hen-egg problem - if the nugets haven't been restored, the .shfbproj can't be loaded, so restore fails, because the common targets are missing.
That should work:

<Project ToolsVersion="Current" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" Condition="Exists('$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props')" />
  <PropertyGroup>
    <TargetFrameworkVersion>v4.6.2</TargetFrameworkVersion>
    <ProjectGuid>{45C2507A-D756-4383-AA29-145416FEF56C}</ProjectGuid>
  </PropertyGroup>
  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
  </PropertyGroup>
  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="EWSoftware.SHFB" Version="2019.9.15" />
    <PackageReference Include="EWSoftware.SHFB.NETFramework" Version="4.8.0" />
  </ItemGroup>
  <Import Project="$(MSBuildToolsPath)\Microsoft.Common.targets" Condition="'$(MSBuildRestoreSessionId)' != ''"/>
  <Import Project="Documentation.shfbproj"  Condition="'$(MSBuildRestoreSessionId)' == ''"/>
</Project>

[tom-englert]

Finally looking at the differences between a .csproj and the .shfbproj, we can make the .shfbproj support nuget packages with these changes:

<?xml version="1.0" encoding="utf-8"?>
<Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003" ToolsVersion="14.0">
  <!-- Import the common props to support NuGet packages via PackageReference -->
  <Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" Condition="Exists('$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props')" />
  <PropertyGroup>
     <!-- A framework version is required for NuGet restore, can be any valid version -->
    <TargetFrameworkVersion>v4.6.2</TargetFrameworkVersion>
    <PublishableProject>false</PublishableProject>
...
  <ItemGroup>
    <PackageReference Include="EWSoftware.SHFB" Version="2019.9.15" />
    <PackageReference Include="EWSoftware.SHFB.NETFramework" Version="4.8.0" />
  </ItemGroup>
  <!-- Import the common build targets during NuGet restore, because $(SHFBROOT) is not set yet -->
  <Import Project="$(MSBuildToolsPath)\Microsoft.Common.targets" Condition="'$(MSBuildRestoreSessionId)' != ''"/>
  <!-- Import the SHFB build targets during build -->
  <Import Project="$(SHFBROOT)\SandcastleHelpFileBuilder.targets" Condition="'$(MSBuildRestoreSessionId)' == ''"/>
</Project>

This will make the extra c# project obsolete.

[eriksorngard]

Thank you for your effort in making this work. Putting everything inside the shfbproj file would be the optimal solution. Unfortunately, it still does not work in our Azure DevOps pipeline, which still produces the same error message:

\Documentation.shfbproj(184,3): Error MSB4019: The imported project "D:\SandcastleHelpFileBuilder.targets" was not found. Confirm that the path in the <Import> declaration is correct, and that the file exists on disk.

There are no references to SHFBROOT in the solution elsewhere that I can find, but somehow MSBuild always looks at "D:" for some reason.

Since the documented project also reference the two SHFB packages, I have also tried to remove them from here, in case there was some interference, but with no change.

[tom-englert]

This works great here:
https://ci.appveyor.com/project/tom-englert/tomstoolbox
https://github.com/tom-englert/TomsToolbox/blob/master/appveyor.yml
https://github.com/tom-englert/TomsToolbox/blob/master/Documentation/Documentation.shfbproj

• What VS-Version do you use?
• How do you restore your nuget packages?