I can successfully create a nuget package.
I have this:
<PackageReleaseNotes>See https://github.com/foo/bar/CHANGELOG.md</PackageReleaseNotes>
That renders as static text. Can I configure it to render as a link instead?
As far as I know, NuGet does not support rich text format in PackageReleaseNotes (nor does it support fetching content from link or file) yet. There is an NuGet issue related to this problem which links to other relevant issues (GUI, etc).
There is a nice little trick which can be used in .csproj file though. For example, if you have a ReleaseNotes.txt file:
1.0.5 Release (2022-09-20)
- Changed foo
1.0.4 Release (2022-08-13)
- Changed bar
1.0.0 Release (2022-01-15)
- Initial release
Then you can use this snippet in your .csproj file:
<PackageReleaseNotes>$([System.IO.File]::ReadAllText("$(MSBuildProjectDirectory)/ReleaseNotes.txt"))</PackageReleaseNotes>
To inject its contents into the package .nuspec on build. Of course, you need to make sure to actually update release notes before hitting Build.
Related
What I've been strugling with for some time:
I have a "traditional" (i.e. non-SDK) csproj file. I want to create a nuget package. That's easy but devil hides in the details and I end up in the following catch-22
I can manually call nuget pack .\Foo.csproj, with or without a nuspec file, but then I get the dreaded NU5128 error. The chosen answer suggests to simply ignore the error. I would happily do that, but after publishing the package locally, I noticed that the dependencies are not included. Though there is one dependency to JSON.net that I added for the sake of testing. The same error appears in AppVeyor if I configure my yml to create the package.
I can specify all the packaging related properties in the .csproj file by setting GeneratePackageOnBuild to true. It works and takes the dependencies right but then I can't patch the version like I could do with the replacement tokens of nuspec. The version defaults to 1.0.0.0 even if I change it in the AssemblyInfo.cs to 1.2.3.4.
Notes
This answer suggests that nuspec and csproj configuration can coexist and they are merged. The question is from 2013 so I guess it's not referring to SDK projects. Unfortunately that's not the case for me.
I tried adding a <NuspecFile> in the csproj but then it seems that replacement tokens don't work and I get the error described here. Probably because this instructed nuget to run pack on the nuspec instead of running it on csproj and merge the nuspec. I can't know for sure though as setting the build verbosity to Detailed didn't help to understand what nuget pack tried to do.
Getting the AssemblyInformationalVersion in msbuild and use it straight to the <Version> property isn't as straightforward as one might think and it also defeats the purpose as $version$ is doing exactly that according to the documentation:
AssemblyInformationalVersion if present, otherwise AssemblyVersion
Is there a way to really "merge" .csproj and .nuspec with $version$ patching and get the dependencies in the nuspec right?
So far the best course of action was to convert the project to SDK format. It has several advantages. Less configuration, no need for .nuspec file, no need for AssemblyInfo.cs or VersionInfo.cs files, .nupkg dependencies are correct and AppVeyor can patch directly the .csproj file if it's an SDK project file.
Not a solution per se if one wants to keep the legacy format, but it gets you going with the CI/CD instead of having you fighting with tools.
Documenting rest api using spring-restdocs in InteliJ Idea is fine, but I missing rendered "include" snippets of operation macro.
== Get Comments sorted
To get sorted according single attribute and with no specific ordering (asc-ending is default), you can refer to this example:
operation::comments/getSortedDescending[snippets='http-request,path-parameters,http-response']
I would expect that somehow I can enable spring-restdocs-asciidoc artefact to be used when rendering things in InteliJ Idea with asciidoctor plugin.
Associated issue https://github.com/asciidoctor/asciidoctor-intellij-plugin/issues/310
I've had a look at spring-restdocs-asciidoctor. The operation::[] is an extension that renders the content. It relies on an attribute snippets that needs to be set.
The IntelliJ plugin for AsciiDoc supports both ruby extensions and attributes for previews as experimental options.
To make it work I did the following:
checkout the project
running gradlew asciidoctor to generate the snippets
add a file .asciidoctorconfig to set the path to the generated snippets
add a directory .asciidoctor and place the extension in this directory
confirm the warning message "This project contains Asciidoctor Extensions..." in the IDE
You need to confirm the warning message every time you restart your IDE. As it will run Ruby code locally, this is a security issue. Maybe we'll enhance it in the future so you only need to reconfirm it once the extension's code changes.
The changes are on the following branch: https://github.com/ahus1/spring-restdocs/tree/poc_extension_intellij
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.
I want to make a custom build of my Dojo project. For example, it is located at D:/projects/myproject,. and I have the Dojo SDK at D:/programs/dojo1.8. I want to separate Dojo and my project code to be independent of Dojo version.
When I'm building a custom package is it required to have the Dojo SDK in the same folder as the main project (i.e. D:/projects/myproject/dojo)? Or may I launch the Dojo builder in a totally unrelated folder, specifying my project's package.js as a parameter?
Such as D:/programs/dojo1.8/buildscripts/build.bat --profile D:/projects/myproject/package.js. If so, what should I use as the basePath, releaseDir and packages options in my package.js file?
It is possible to include unrelated packages in the build.
In the command line specify the package you want to add, such as.
D:/programs/dojo1.8/buildscripts/build.bat --profile MyProfile.js --package d:\programs\dojo1.8
The specified package folder should contain a file named package.json with a package description. Format of the file could be found in dojo build documentation. Standard dojo, dijit and dojox packages have it. But nowhere said it must contain "directories: {lib: '.'}" entry to be built by dojo builder.
You may specify several packages separated by commas.
I've just committed some code changes to my repository and all of a sudden (after weeks of being fine). The TC build starts failing as it fails to download the NuGet package for Microsoft.Bcl.Build.1.0.6.
I ended up having to manually copy the contents of the packages directory to the TC build location which utterly defeats the point of NuGet.
What can I check to get to the root cause of this?
Everything about NuGet is enabled in the solution for getting packages.
I've blogged about this issue at http://sedodream.com/2012/12/24/SlowCheetahBuildServerSupportUpdated.aspx. To summarize NuGet package restore (prior to 2.7) is implemented as a part of the MSBuild build process. When MSBuild starts a build it will evaluate the project file and any Import declarations importing other files. This happens before any target gets executed.
Since NuGet pkg restore is a part of the build process the .targets files get restored at a point in time that it is too late for the Import statement to have any impact.
You can work around this by either checking in the .targets file as you stated, or by invoking pkg restore before the build process. I've created a NuGet package, PackageRestore, which can help with the latter approach.
To use PackageRestore just add the NuGet package to your project which will automatically create a file named packageRestore.proj in your projects directory. When configuring your build, you will need to build that item before your .sln/.csproj file.
OK This is a bit of a nasty issue.
If you are having this problem you need to do something rather ugly to your repository.
Make sure you are checking in the packages\repositories.config file.
Then if your build is failing with unresolved references to Microsoft.Bcl.Build you will need to also checkin the .targets file for this package. eg:
package\Microsoft.Bcl.Build.x.x.x\tools\Microsoft.Bcl.Build.targets
Hideous ...
This blog post is the most thorough one I've seen for explaining the workaround options:
http://blogs.msdn.com/b/dotnet/archive/2013/06/12/nuget-package-restore-issues.aspx
None are great IMO - this problem still needs a better solution.
But for the time being, the best recommended option is to check the Bcl.Build .targets file into source control - which means when the version of Bcl.Build is updated, you'll need to add the new .targets file, and remove the old one.
I think (but am not sure, so I created this SO question: What does the Microsoft.Bcl.Build NuGet package do?) that Microsoft.Bcl.Build is only needed for development, and is not needed on a build server. So, I have a Builder.targets file that only exists in the build environment, that is indirectly <import> ed into all of our projects, which includes this bit of MSBuild xml:
<!-- Skip Microsoft.Bcl.Build functionality when building only from Source. Presumably Microsoft.BclBuild is only needed for development. -->
<PropertyGroup>
<BclBuildImported>Ignore</BclBuildImported>
</PropertyGroup>
Since the block of MSBuild logic inserted into your project by the Bcl.Build nuget package is dependent on the BclBuildImported property being empty, this effectively sidesteps the problem in my build environment - the Microsoft.Bcl.Build steps are skipped, and it no longer breaks my CI builds.
Note that since it appears that this package manages binding redirects in your app.config, and ensures that transitive dependencies are included in your projects, it's important to leave in for development. But I'm not currently aware of a need for it in a build server environment.