Including LINQPad samples in NuGet packages

You can include LINQPad sample queries in NuGet packages, and LINQPad will display them automatically in the Samples treeview when the package is downloaded:

NuGetSamples

This is a great way to demonstrate your library, using lightweight interactive scripts.

Users don't need the premium (paid) edition of LINQPad. The licensing restriction has been relaxed so that NuGet packages that contain LINQPad samples can be searched and downloaded by users of the free edition.

The process of including LINQPad sample queries with your NuGet package is as simple creating a folder called linqpad-samples in your package root, and xcopying your sample queries into there. Visual Studio ignores this folder, so it won't have any effect except when consumed from LINQPad.

Here are the steps:

  1. Create your samples in LINQPad. Use subfolders to organize content.
  2. Update your NuGet packing script to copy your samples into a folder called linqpad-samples.
  3. Add the linqpad-samples tag to your NuGet submission to ensure free access.

The linqpad-samples folder should be created at the root of your package. For example:

lib
	net40
		...
	net45
		...
content
	...
tools
	...
linqpad-samples
	Getting Started
		Basic usage.linq
		...

FAQ

Do I need to make any changes to my .nuspec file to get the linqpad-samples folder included?

Not if you're using the convention-based approach for creating your NuGet package. The command-line utility will include the linqpad-samples folder automatically.

Is there anything special to creating the sample queries?

Your samples are nothing more than standard LINQPad queries (.linq files) that demonstrate your NuGet package. You can write them in any supported language (C#, VB, F#) and they can be expressions, statements or programs. You can save your queries into any folder hierarchy. The samples don't need to reference or demo your NuGet package, although it's likely you'll want them to.

Should my queries reference the NuGet package itself, or its assemblies?

Either. Ordinary assembly (file) references have the advantage of letting you write your queries before publishing the NuGet package (and letting you run them against unreleased builds). Another benefit is you can use the free edition of LINQPad to write them. Of course, when you add an assembly file reference, you must specify its location. The good news is that you can use anything that's valid on your local system and not worry about making the path valid for the end user. As long as the assemblies that you reference exist somewhere in your NuGet package (in its lib folder, or in the lib folder of one of its dependencies), LINQPad will fix them up automatically when the query is opened via the Samples treeview.

What about dependencies?

If your dependencies include samples, these will appear too, as a sub-node in your samples treeview. This is handy if your project is split over several packages.

Can I sort my queries into a logical order without prefixing them with numbers?

Certainly. Just right-click your folder in My Queries and choose 'Reorder Items'. (LINQPad then creates a file called 'order.txt' which specifies the ordering of files and subfolders.) If your queries are not located within the My Queries folder, you can move the latter temporarily by clicking the 'Set Folder' link.

Can I create a NuGet package that's a purely a LINQPad sample library?

Sure. You can demo other NuGet packages, or none at all.

Can I include other files, such sample XML data, with my queries?

Yes: Put any other files that you need in the same folder as your queries (or in any folder such that the relative path won't change when you copy the query into linqpad-samples). In your queries, add a reference to those files via the 'Add Reference' dialog (press F4, click 'Browse, and then change the dropdown to search for all files (*.*) rather than just DLLs and EXEs, and browse to your file). You can then get the full path of that file with Util.GetFullPath("myfile.xml").

Is there anything special to submitting a NuGet library that includes LINQPad samples?

Include the tag linqpad-samples. This ensures that users of the free edition of LINQPad can view and download it.