NuGet package XML documentation not visible in .NET Core 2.2 app - asp.net-core

I am using a NuGet package which has an XML documentation file.
But when I include the package in a .NET Core 2.2 app, the comments are not available with IntelliSense.
Is there something I'm missing either in the package or in my app to be able to see the documentation with IntelliSense?
Using VisualStudio 2017, Windows 10.
Update for Clarity
The NuGet package is a .NET Standard 1.3 class library. In Visual Studio when I build the project, I include the options to generate the package and documentation file. In the project file, I see the following PropertyGroup:
<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|AnyCPU'">
<DocumentationFile>C:\Users\[username]\[local path]\CommonEntities\CommonEntities\CommonEntities.xml</DocumentationFile>
</PropertyGroup>
When I open the package, I can see in the lib/netstandard1.3/ directory that CommonEntities.xml is included along with MakanalTech.CommonEntities.dll.
But, I'm wondering why the xml file has dropped the full name from MakanalTech.CommonEntities.xml as it is in the project to just CommonEntities.xml in the package. Maybe this is the cause of the issue?
The issue is then when I include the package as a dependency in another project, none of the XML comments/documentation are visible. So I can't hover over a type to see its description, and if I peek definition none of the comments/documentation are in the definition.
Class Library Product
https://imgur.com/zbE7ngM (can't post images yet)
Peeking at definition from other project:
https://imgur.com/pwmvpX7

Finally found the issue from this post. This seems quite buggy from Visual Studio 2017 not to handle this correctly and automatically.
In the .csproj file, I removed <DocumentationFile>[filepath-to-xml]</DocumentationFile> and added <GenerateDocumentationFile>true</GenerateDocumentationFile>.
I then repacked the library, cleared my nuget cache, and rebuilt the new project where it's included, and now I have all the XML documentation visible.

NuGet package XML documentation not visible in .NET Core 2.2 app
Just like what have you found that "in the lib/netstandard1.3/ directory that CommonEntities.xml is included along with MakanalTech.CommonEntities.dll.", the .xml file in the lib folder, then according to the document From a convention-based working directory:
Only the .dll file will be added as reference, .xml file will be copied to the project folder. That is the reason why the XML documentation not visible in .NET Core 2.2 app.
Besides, since you are using .netstandard project, .xml file will blocked be copied to the project folder automatically by the nuget issue 4837.
To resolve this issue, we have to create the .nuspec file with option contentFiles to include the .xml file and add this file to the project, please check the detail info from other thread.
But if you do not want to manually edit the .nuspec every release, you can use a post-build event to pack the nuget package automatically,like:
nuget pack "$(.NuspecFilePath)\xxx.nuspec"
Or you can add the .xml file to the project manually from the package directly, that package is in the path: C:\Users\<UserName>\.nuget\packages.
Hope this helps.

Related

How do I get the Microsoft.Data.SqlClient.SNI native binaries copied to the bin directory of a web application that targets .NET Framework 4.7.2?

How can I <Import> a .targets file that is included in <PackageReference>d NuGet package in a non-SDK-style web application project that targets .NET 4.7.2?
Background
The web application project is not an SDK-style project. It references a class library project in the same solution. This class library project is an SDK-style project. It has a package reference to Microsoft.Data.SqlClient version 4.1.0, which depends on Microsoft.Data.SqlClient.SNI.runtime 4.0.0. The latter contains native binaries which are automatically copied to the bin directory of the project.
The native binaries are not copied to the bin directory of the web application project. This is probably because of this:
SNI is the native C++ library that SqlClient depends on for various network operations when running on Windows. In .NET Framework applications that are built with the MSBuild Project SDK, native DLLs aren't managed with restore commands. So a ".targets" file is included in the "Microsoft.Data.SqlClient.SNI" NuGet package that defines the necessary "Copy" operations.
The included ".targets" file is auto-referenced when a direct dependency is made to the "Microsoft.Data.SqlClient" library. In scenarios where a transitive (indirect) reference is made, this ".targets" file should be manually referenced to ensure "Copy" operations can execute when necessary.
Recommended Solution: Make sure the ".targets" file is referenced in the application's ".csproj" file to ensure "Copy" operations are executed.
Source
Not sure what "built with the MSBuild Project SDK" means exactly, but I think my scenario qualifies.
Now I'm trying to implement the recommended solution, but I cannot get it to work.
What I did
Step 1: add package reference to Microsoft.Data.SqlClient.SNI version 4.0.0:
<PackageReference Include="Microsoft.Data.SqlClient.SNI">
<GeneratePathProperty>true</GeneratePathProperty>
<Version>4.0.0</Version>
</PackageReference>
I added <GeneratePathProperty> because of step 2 below. According to the documentation this should make a property available that can be used to refer to files in the package:
Sometimes it is desirable to reference files in a package from an MSBuild target. In packages.config based projects, the packages are installed in a folder relative to the project file. However in PackageReference, the packages are consumed from the global-packages folder, which can vary from machine to machine.
To bridge that gap, NuGet introduced a property that points to the location from which the package will be consumed.
Step 2: import the targets file:
<Import Project="$(PkgMicrosoft_Data_SqlClient_SNI)\build\net46\Microsoft.Data.SqlClient.SNI.targets" Condition="Exists('$(PkgMicrosoft_Data_SqlClient_SNI)\build\net46\Microsoft.Data.SqlClient.SNI.targets')" />
You can see that the package contains this targets file using the NuGet package explorer (link). The PkgMicrosoft_Data_SqlClient_SNI property is named according to the documentation (linked above) and based on their example:
MSBuild properties and package identities do not have the same restrictions so the package identity needs to be changed to an MSBuild friendly name, prefixed by the word Pkg.
Step 3: verify the tool versions on our agent:
MSBuild 16.11.2.50704 (installed on the agent C:\Program Files (x86)\Microsoft Visual Studio\2019\Enterprise\MSBuild\Current\bin)
NuGet 6.1.0.106 (installed via a pipeline task)
According to the documentation linked above, these fulfil the minimum requirements (MSBuild 16 and NuGet 5).
Step 4: run nuget restore on our build agent and then build the project using the Azure DevOps MSBuild#1 task with msbuildArguments: '/t:Build'.
Step 4: collect output and publish as an artifact.
Outcome:
The SNI files are not present in the output. When building locally with MSBuild 17.0.0.52104 (installed in 'C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\MSBuild\Current\bin') I do see the SNI files.

How can I get GitVersion /UpdateAssemblyInfo to work with ASP.NET Core 2.0 project

We have been using a Bamboo build server for a while now and we have GitVersion installed so it can be selected as a task in the Build plan. We typically use the /UpdateAssembleInfo argument when we run the task. For .NET Framework projects, this would update the assemblyinfo file in the source with the bamboo versioning settings so the .NET assemblies had the same version info as our Bamboo builds and subsequent Bamboo deployment, allowing us to know the version of the deployed project in the field by examining the assembly file properties. This was all working quite well.
However, we are now building and deploying .NET Core 2.0 solutions and are finding that GitVersion /UpdateAssemblyInfo is not working.
I searched for a fix for .NET Core but was only able to find solutions that involved using the project.json file, which is no longer used with .NET Core 2.0 ( it changed to the *.csproj file).
I looked at http://gitversion.readthedocs.io/en/latest/usage/command-line/ and I tried running
gitversion.exe /UpdateAssemblyInfo MyProjectName.AssemblyInfo.cs /EnsureAssemblyInfo
where MyProjectName represents the actual project name suffix for the assemblyinfo.cs file in the .NET Core 2.0 ..\\obj\release\netcoreapp2.0 folder. But it did not update that file.
I have to assume that there has to be a solution for using GitVersion with Bamboo and.NET Core 2.0 but I am having a hard time finding one.
Any ideas?
The latest version of GitVersion provides /updateprojectfiles switch to update version info in the Sdk-style .csproj/.vbproj/.fsproj recursively.
From GitVersion/Usage/CommandLine/Arguments:
/updateprojectfiles
Will recursively search for all project files
(.csproj/.vbproj/.fsproj) files in the git repo and update them
Note: This is only compatible with the newer Sdk projects
It produces the needed attributes even if they are not present in the project files, resulting in following properties:
<Project>
<PropertyGroup>
<AssemblyVersion>1.0.0.0</AssemblyVersion>
<FileVersion>1.0.0.0</FileVersion>
<InformationalVersion>1.0.0-versionNumber.N+Branch.branchName.Sha.commitId</InformationalVersion>
<Version>1.0.0-versionNumberNNNN</Version>
</PropertyGroup>
As a workaround, you may consider specifying the assembly info as project properties in .csproj
<PropertyGroup>
<Version>1.2.3.4</Version>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
...
</PropertyGroup>
and then setting values during dotnet build. In addition to its options, the dotnet build command accepts MSBuild options like /property
/property:name=value
/p:name=value
Set or override the specified project-level properties, where name is the property name and value is the property value. Specify each property separately, or use a semicolon or comma to separate multiple properties.
So your build command will be something like
dotnet build /p:Version=1.2.3.4;AssemblyVersion=1.2.3.4

NuGet package contentFiles artifacts installed as links in ASP.NET Core MVC project

We have an internal JavaScript library that we'd like to share between multiple projects. Actually we are already sharing it via file copying, but this has (predictably) resulted in multiple forks of the code.
The consuming projects are a mix of "full" ASP.NET (MVC and Web Forms) and ASP.NET Core MVC. (I'm planning on creating two separate packages.)
Installing into ASP.NET projects seems to work fine, but I'm having problems with ASP.NET Core.
Initially I had all the artifacts within a files element, and nothing at all was showing up in the consuming project. After re-reading the docs, I realized that ASP.NET Core projects would use a PackageReference ... so I would have to use a contentFiles element instead of (or in addition to) a files element.
I created a contentFiles folder and a script to copy the requisite files from the source project folder structure into contentFiles/any/any/wwwroot/lib/ourAwesomeWidget, and modified the package manifest accordingly.
This works. Sort of. The package appears to get build correctly. The files do get added to the consuming project, but they get added as links; the actual files (the link targets) reside in my local package cache.
The relevant portion of the package manifest is:
<metadata minClientVersion="3.3">
...
<contentFiles>
<files include="**/*" buildAction="Content"
copyToOutput="true" flatten="false" />
</contentFiles>
</metadata>
<files>
<file src="contentFiles\**" target="contentFiles" />
</files>
Part of the issue is that I don't find the docs very clear concerning contentFiles. All the examples show a single file element ... but the include attribute on the files element is required, so it's not clear what the individual file elements would even do.
Is there a way to get the actual files (not links) added to the consuming project? Or, alternatively, is there a way to get the package to install as a "normal" package (rather than a PackageReference)?
Update:
I did some further digging and found this answer by #Martin to a similar question -- but he answered this one before I had a chance to update it.
It appears this behavior (adding files as links) is by design.
I find this highly unsatisfactory, because (as #Martin points out), our JavaScript library will not be available during development on consuming projects.
But part 2 of my question still stands. According to the docs,
By default, PackageReference is used for .NET Core projects, .NET Standard projects, and UWP projects targeting Windows 10 Build 15063 (Creators Update) and later.
Is there a way to trigger the non-default behavior, i.e. allow .NET Core projects to consume packages other than via PackageReference?
contentFiles are supposed to be added as a link. The contentFiles section controls the msbuild items that are generated for these files into the obj\projectname.csproj.nuget.g.props file.
The copyToOutput="true" will cause the items to be copied to the output and publish directory. However that does not help you when running the application during development, since it will be run from the project directory, not the output directory.
Consider consuming client libraries via npm (since bower is deprecated).

In which file do you set nuget packages for a .NET Core project?

I found something called "MyProjectName.deps.json" in the "bin" directory. But if i delete the "bin" directory and build my project again it gets created again. Where does VisualStudio pull this data from (which packages should be included in the project)?
This is based upon the obj\project.assets.json file (generated by NuGet restore) which defines inputs to the build logic that are used for the generation of the .deps.json file, along with other references from the project file.

Unable to build WixStdBootstrapperApplication - get error "C:\tools\WixBuild.props" was not found

I am trying to make changes to the WixStandardBootstrapperApplication.cpp and generate a dll as per the suggestion from this link. I have downloaded the wix310-debug source and am modifying the file present under wix310-debug\src\ext\BalExtension\wixstdba\ location. There is a wixstdba.vcxproj file under this location which I am trying to open using Visual Studio 2012. Whenever I try to do that I get the error:
Unable to read the project file "wixstdba.vcxproj". The imported project "C:\tools\WixBuild.props" was not found.
I am not sure what should I do to correct this. Also, based on the referenced link, I think I am updating the correct file but let me know if that is not the case. Any help in this would be great. Thanks in advance.
In your vcxproj there's a line like this:
<Import Project="$([MSBuild]::GetDirectoryNameOfFileAbove($(MSBuildProjectDirectory), wix.proj))\tools\WixBuild.targets" />
The debug source isn't really the source of wix. It includes all the wix source files but it is not really buildable. This zip has all the built pdbs and is used to debug only.
You want to download the wix source from wixtoolset's github so that you can build wixstdba. But, this is for version 3.10.3 currently and may have some version specific changes but I don't see anything that would be an issue using the dll built here against wix 3.10.2 since the engine and bootstrapper application interfaces should have remained the same.
But, you should be able to build all this with only the WixStdBA project. You will have to copy over the wixstdba folder. Edit the vcxproj and remove the import line mentioned above (it should be near the bottom).
Now, add this project to your a new solution or your installer solution in visual studio. We need to add addition include and library directories. All these include directories will be in your wix install location (default C:\Program Files (x86)\WiX Toolset v3.10) In Properties -> C/C++ -> General -> additional include directories add your wix SDK include path. If you are using visual studio 2013 you can use the full path or you can use "$(WIX)\SDK\vs2013\inc". $(WIX) should reference the WIX environment variable which points to the install directory which is added when installing wix. This should be the better option if you will be building on a build system with wix installed since the location may be different across machines.
Now for addition library directories, we go to the Properties -> Linker -> General -> Additional Library Directoryes and add in the correct lib path. If you are using visual studio 2013 you want to put in $(WIX)\SDK\vs2013\lib\x86. Finally we need to reference the libs that are needed to build the bootstrapper dll. Under Linker -> Input -> Additional Dependencies, add in "dutil.lib;balutil.lib". My additional dependencies has a lot more stuff and I don't remember if it was by default there. Here's my Additional Dependencies in full anyways
dutil.lib;balutil.lib;advapi32.lib;comctl32.lib;comdlg32.lib;gdi32.lib;gdiplus.lib;kernel32.lib;msimg32.lib;odbc32.lib;odbccp32.lib;ole32.lib;oleaut32.lib;shell32.lib;shlwapi.lib;user32.lib;uuid.lib;wininet.lib;winspool.lib;version.lib;%(AdditionalDependencies)
With this you should be able to build the wixstdba project and get a dll built. Without editing any code this should be the exact same as the wix included wixstdba.dll.
You could try referencing this dll instead of the wix included one (have to define your own BootstrapperApplication instead of using the BootstrapperApplicationRef to one of the wix ones) or just drop in this dll into your wix location's bin.