Please add NuGet support to shfb projects in VisualStudio

Topics: Developer Forum, User Forum
Oct 2, 2014 at 11:17 AM
Use Case:

In our projects we are referencing a lot of NuGet packages. Types of these packages are used in public classes or interfaces, so they appear also in the generated documentation.

So to generate documentation I have two SHFB projects:
Documentation.shfbproj
References.shfbproj

The first one generates the documentation for my own projects, the second one is used by the "Additional Reference Links Plugin". So the References.shfbproj points to the .xml and .dll files of the NuGet packages as documentation sources.

This all works great as long as I don't update the NuGet packages, because now the documentation source path to the NuGet packages points to an old nonexisting version. Therefor it would be great that the NuGet Update process is aware of the Sandcastle project and also update a packages.config and the documentation sources inside the shfbproj.

The only problem I see is that it is not obvious if the NuGet package should be added as Reference or as Documentation source. Perhaps it would be best to add it to both.
Coordinator
Oct 2, 2014 at 3:13 PM
The problem here is that NuGet updates the project so it would have to be made aware of the SHFB project type. That's beyond my control. I think a simpler solution exists. The NuGet package assemblies ultimately end up in the .\Debug or .\Release folder of the project that references them. I'd suggest pointing the references project documentation sources at one of those folders instead. You can also make it configurable by using the Configuration macro in the name like this: ..\ProjectFolder\bin\$(Configuration)\NuGetAssembly.dll.

Eric
Oct 2, 2014 at 9:10 PM
I have to try it out, but I think this will only work locally and not on TFS build, because the build agent changes the outputdir.
Coordinator
Oct 3, 2014 at 12:25 AM
$(OutDir) may work in both cases instead of bin\$(Configuration).

Eric
Oct 10, 2014 at 12:26 PM
$(OutDir) doesn't work in additional references projects because they are not build directly, so it is not populated.

This is my solution for now:
...
        <FrameworkVersion>.NET Framework 4.5</FrameworkVersion>
    </PropertyGroup>
    <Choose>
        <When Condition="Exists('..\..\Binaries\$(Configuration)')">
            <PropertyGroup>
                <Binaries>..\..\Binaries\$(Configuration)</Binaries>
            </PropertyGroup>
        </When>
        <Otherwise>
            <PropertyGroup>
                <Binaries>..\..\..\bin</Binaries>
            </PropertyGroup>
        </Otherwise>
    </Choose>
    <PropertyGroup>
        <OutputPath>.\Help</OutputPath>
        <Language>en-US</Language>
        <DocumentationSources>
            <DocumentationSource sourceFile="$(Binaries)\Foo.XML" />
            <DocumentationSource sourceFile="$(Binaries)\Foo.dll" />
        </DocumentationSources>
...
Oct 31, 2014 at 11:55 AM
No update to NuGet is required, but the workaround isn't especially pretty.

https://github.com/DartVS/DartVS/blob/93be9f3d6732f0c25eb3c9a910440a53461cf8ab/DanTup.DartVS.Vsix/ProjectSystem/DartProjectNode.cs#L60-L73

Keep in mind that NuGet will only add the assemblies to the References section, not as documentation sources. If that does not work for the purposes of your reference project then it will need to be implemented separately before NuGet support will have the desired result.
Coordinator
Oct 31, 2014 at 3:09 PM
That doesn't apply in this instance as he wants them in the additional references project where they have to be documentation sources.