I've looked for descriptions of the files that go into a Nuget Package (.nupkg), but I have yet to find a definitive guide, most everything assumes you have to use Nuget Explorer, or the Nuget.exe -- but well, let's just say I'm obstinate.
Using the Nuget Explorer to create a package produces a directory with files that I'd like to create using a script or some other tool (besides Nuget.exe). So, given this simple directory layout generated by Nuget Explorer, I'm looking for definition of the .psmdcp file, the .rels file, the [Content_Types.xml] file, and of course the ProjectX.nuspec file.
I can find some details, or deduce them, for [Content_Typex.xml] and the .nuspec file. I tried making a package with just the lib/ dir, it's content, and a nuspec file, but apparently that isn't enough, and I get Package does not contain a manifest -- which I suspect means that the .nuspec alone isn't the full manifest.
lib/
ProjectX.dll
ProjectX.pdb
package/
package/services/metadata/core-properties/____hash____.psmdcp
_rel/
.rels
[Content_Types.xml]
ProjectX.nuspec
Is there no guide for making a .nupkg by hand? Is it really that complicated a process?
.nuspec defines properties about your package (the metadata) as well as a list of files to include in the package. There are plenty of descriptions of this around, so the bits that needs to be addressed are the files that are added by the tools:
.nupkg files follow the Open Packaging Convention. As you have figured out, it is really a .zip file with some predefined files. The _rels directory contain relationships between "parts". Think of a Word document containing images and Excel spreadsheet tables to get an intuition of "parts".
Packages mostly contain only one part; the package itself (but can probably contain sub-packages for modules). The _rels/.rels file defines the relationship for the main, top-level package. A relationship has an ID, a url that describes the kind of relationship and a target, which is the file which has this relationship to the package. Most packages has a relationship to the .nuspec file, which is of kind "manifest", and to the .psmdcp file, which is of kind "core-properties". The IDs of these relationships only need to be unique within the package, so they could be simply strings such as "R1", "R2", but for some reason they are "R" + 16 first bytes of GUID, in choco.
The core-properties seems to be mostly a rehash of the manifest file, dressed in Dublin Core tags instead of the nuspec; I guess in theory other programs could present the package based on these (if you embed it in a Word-document!). Probably psmdcp is an abbreviation of "Package Services Metadata Dublin Core Properties". Checking NuGet.Core/NuGet.Packaging/PackageCreation/Authoring/PackageBuilder.cs we see that the name of the file is a simply a GUID with "N" format (just digits). The lastModifiedBy property is the version information of the "choco" assembly itself; I guess you can really put anything there if you create the files yourself.
[Content Types.xml] defines the file format of extensions, in the form of MIME types. This is mostly boiler-plate.
So, in conclusion: Based on the .nuspec you can generate all the other missing files and put together the .nupkg yourself, even in a Powershell script.
I've written a blog post about how you could use the NuGet XSD:
http://www.xavierdecoster.com/post/2012/03/08/Hidden-gem-the-NuGet-package-manifest-XSD.aspx
Also, take a look at the NuGet package conventions in the docs:
http://docs.nuget.org/docs/creating-packages/creating-and-publishing-a-package#Package_Conventions
If you need more detailed hands-on, there's also a Pro NuGet book that goes in-depth into various scenarios:
http://www.amazon.com/NuGet-Professional-Apress-Maarten-Balliauw/dp/1430241918
Related
What is the proper way of delivering temporary build-time assets using nuget?
I am making a nuget package with a single file, which dependent projects require during the build phase. I would like the content of the file to be copied to obj\$(Configuration) folder inside a dependent project before proceeding with the rest of the build. Of course, the obj folder is temporary, so I would like my file to be copied there again as part of the next build if obj gets cleared out.
I tried contentFiles approach described here. This takes care of packaging my file inside nupkg file, but I was unable to set it up so that my file gets delivered (and re-delivered) to obj\$(Configuration).
You're looking for NuGet's MSBuild extensibility. Unfortunately it means you'll need to learn a bit about MSBuild if you don't already know it. I recommend running msbuild -bl or dotnet build -bl, which will create a msbuild.binlog file, which you can view with the msbuild structured log viewer.
One option is to have a target that creates the file in the intermediate output directory at an appropriate time (probably need to use BeforeTargets). You could use the Inputs and Outputs attributes to have msbuild do incremental build checks and skip copying when it doesn't need to, possibly making the build a little faster.
However, unless the file is has dynmanic content, copying the file is a waste. it's just going to be included as an item in another part of the build process. So, if it's static content, you could just create the relevant item in your targets file from your package's extracted directory, and then it's just as good as if it was copied to the intermediate output directory, without wasted time and duplicated disk space.
I have build a nuget package at published it to a nuget.server site. But when I try to use the package form the server the .targets file from build folder is not in the file. But if I use the package from a local folder it works as it should. How do I get it to work ?
If i look in the package in the folder on the server it looks ok.
It's not clear to me if you mean using (referencing and restoring) a package, or building (packing) a package.
If the problem is with packing the nupkg, NuGet requires the props and targets files to have specific filenames in specific folders, but if you got it to work at least once, you probably already know that. If this is not the problem with packing, you need to give us more information because not using the correct filename convention is the most common problem and I can't guess what else the problem could be. In particular, if the package is being packed differently on your local machine compared to when it is packed on the server, it means there is something different between how you pack on the two computers, so we need more information about how the build and pack work with your project.
If the problem is with using (restoring) the package, there are a few possibilities. My best guess is that you once had a package without the targets file working correctly, and you restored the package on the server. By design, NuGet packages are immutable which means it's invalid for the contents of a package (same ID and version) to change. This allows NuGet to download the package from a remote feed once, save it in the global package folder (not a cache; they never expire) and the next time NuGet needs to restore the same package (id + version) it uses the one in the global package folder, it does not download again. This means if you once built a bad nupkg and restored it on a machine, then fix the nupkg and kept the same version number, that machine will never get the fixed nupkg. You need to delete it from the global packages folder. I'm not 100% sure, but I think if you have a local file feed and you restore a project that uses packages.config, the nupkg does not get saved in the global packages folder, so doesn't have the same problem. In short, I think the problem is that you changed the nupkg contents once without changing the version number, and one of the machines has the old copy in its global packages folder that it keeps using.
If that's not the problem, the next most likely cause is that the nupkg on the server feed has different contents to the nupkg in the local feed. I've never used NuGet.Server, but some nuget respositories (like nuget.org) do not allow overwriting nupkgs. So, if you pushed a nupkg to your server, fixed a problem in your nupkg without changing the version, then tried to push again, the second push might have failed.
In summary, your question doesn't provide enough information for us to help you, but I wrote about the most common issues above. If it doesn't help, you need to provide us with more information. An example of the problem is the best way to give us enough information to help you.
I have .NetStandard library. I'm going to use it in .NetFramework and .NetCoreApp applications.
It uses System.Configuration.ConfigurationManager package for work with config files. I need to transform these config files during my library installation.
I found 2 ways:
tools folder in nuget package with install.ps1 file in it
content folder with app.config.install.xdt file in it
Non of them is does not work - nuget doesn't run install.ps1, nuget doesn't transform App.config.
There is a code from csproj:
<ItemGroup>
<Content Include="Content\app.config.install.xdt">
<PackagePath>content</PackagePath>
</Content>
</ItemGroup>
Nuget package contains this file... So I have no idea why it doesn't work.
Is this problem related to .NetStandard? What I'm doing wrong?
Executing ps1 scripts, and XDT transforms are both features that only work with packages.config, but not PackageReference. .NET Core (and I think .NET Standard) projects only work with SDK-style projects, and SDK style projects only support PackageReference. Packages.config only works with "old-style" projects, which may also PackageReference.
The way that Microsoft's ASP.NET Core libraries deal with this difference is that they no longer read settings directly from web.config. Instead the program has to register callback functions that will modify an existing in-memory options object. For example
services.AddMyService(options =>
{
options.setting = newValue;
});
This has some advantages to your users.
They are no longer limited to storing the configuration value in the location the library author demanded. They can choose to load configuration from a database, a configuration service, an xml file, a json file, or just hard-code it in the app. But it lets each developer choose what's best for their own system.
If the user overrides a setting that the package puts in the config file, and each update of the package overrides the user's preference, the user gets annoyed that the package doesn't respect their choice to change the default.
If the user doesn't want to override a setting that the package put in the config file, and the package author doesn't want to overwrite the config file each update, then it's very difficult for the package author to change a default value.
ASP.NET Core's new model is better for everyone because the package author creates the options object and pre-populates it with default values and then call the user's delegate method allowing them to change the settings they care about. If the package author wants to change a default value, they do so in their own code, publish a new package, and users that don't change the value get the new default, and users who explicitly set the value in their code keep using the value they want to, from whatever configuration store they want.
So, the TL:DR answer is that you can't do what you asked for with PackageReference projects, but I hope my longer answer has given you ideas how you can redesign your library which gives better both the package author and package user a better experience.
I am currently working on changing our codebase to use Nuget. As part of the process the copying of ressources to the output directory should be moved from postbuild events in the projects to the files tag in the .nuspec file.
For the particular project the ressource was called Resources.resx and is renamed to something more specific during the copy (yes I know great programming - not mine and not my place to change it).
Is it possible to change the filename using the file node in nuspec or do I need to keep a postbuild in this case?
My attemp of renaming it with the target property fails:
< file src="foo/bar.resx" target="foo/foobar.resx"/>
creates the following output:
"foo/foobar.resx/bar.rex"
I found a familiar problem on github but it was rejected due to being posted on a dead branch and not trying to rename a file but change its type.
https://github.com/NuGet/Home/issues/2019
Thanks for the help
This functionality is not built into NuGet. The only conceivable way to do this would be to implement a powershell script (install.ps1) that would handle the rename of both the file and the csproj.
Late to the party, but this looks like it could work:
From: https://learn.microsoft.com/en-us/nuget/reference/nuspec
Renaming a content file in the package
Source file:
ie\css\style.css
.nuspec entry:
<file src="ie\css\style.css" target="Content\css\ie.css" />
Packaged result:
content\css\ie.css
Edit:
I found this post (https://stackoverflow.com/a/45601252/182888) where it says:
Note: The File extension in src and target must match or the specified target will be treated like a directory.
So keep that in mind or it might trip you up.
I store all SSIS packages in Subversion repository, their configuration files as well. Configuration file almost always stored in the same folder where package is.
Problem is - SSIS seems to always store path to configuration file (the one saved in the package itself) as an absolute path.
When someone else checks out folder with the package in the location different from where I had on my development PC the configuration file is not detected (because my absolute path is stored and it doesn't exist on the other developer PC). So another developer has to remove this configuration and add it again from where it is now on his local hard drive. Then changed package is saved which will cause new version to be committed. When I get that version from SVN it will no longer match local path on my PC.
On a related note: another developer may want to change values in configuration file as well. If I later get the latest version of everything from SVN package will no longer work on my PC.
How do you work around these inconveniences?
Another solution is to save your configuration in a database with an environment variable as the first configuration to tell it what database to look in, that's what we do. We have scripts to populate ssisconfig for each server in our source control, but the package uses the actual table data for the database in the environment variable we are using.
Anyone who has heard my SQL Saturday presentations knows I don't much care for XML and this is one of the reasons. A trick to using XML configuration with varying locations is to use an environment variable (indirect configuration) to direct SSIS where it can look for that resource. The big, big downside to this approach is you'd generally need to create an environment variable for each set of configuration files or have a massive, honking .dtsconfig file which becomes painful for versioning.
The option I prefer if XML configuration is a must is that the "variableness" is removed. Developers and admins get together and everyone agrees "there will be a folder everywhere SSIS is done to hold configuration files and that location is X" and then it's just a matter of solving for X. At a previous job, we used D:\ssisdata\configs
#HLGEM's approach of a table for configurations is hands down my favorite approach to SSIS configuration (until you get to 2012 and their project deployment model where configuration is an entirely different animal)
I add a folder called "config" under my projects folder, add it to source control and mantain the config file in this folder. You can also add it to the SSIS project if you like.
I think its a good solution because everybody can have this folder and dowload the config file.
When the package is deployed it will read the config file from where you inform in the deployment manifest so this solution wont impact your development