Geeks With Blogs

News
Joe Mayo

Giovanni Bassi published the original NuGet package for LINQ to Twitter (L2T), which I'm appreciative of.  Since then, I have yet to do a release myself, but that is changing now.  The current version of LINQ to Twitter is stable enough for a release, so the time is right.  I think there are a few aspects of a LINQ to Twitter NuGet package that aren't as simple as point at a project and your done, so I'll document my process here in case anyone else is interested.

Getting Started

I had played around with NuGet during one of it's earliest releases, building a package and setting up a personal test server, so I was familiar enough to know where to start.  The project has pretty decent documentation, which is where I started. Visiting the site http://nuget.org and clicking on documentation brought me to http://docs.nuget.org.  Nice layout, I clicked on Creating and Publishing a Package, under the Creating Packages section.

Selecting a Packaging Strategy

After downloading and installing NuGet.exe, there are three choices for package creation: From an Assembly, From a Project, and From a convention based working directory.  The first couple of choices are the easiest and require the least amount of effort.  If you have a single assembly or a single project, the steps are numbingly simple to have a working NuGet package.  However, L2T supports different versions of multiple technologies and has potential for customizations beyond an assembly reference.  This narrows the L2T strategy to using a convention based working directory.  Before creating folders, I want to discuss the package specification first.

Creating the Package Spec

I typed NuGet spec and received a file named package.nuspec.  This is an XML file that has details about how the package is supposed to fit together - the fancy name is meta-data. This generated file is only a skeleton and doesn't have any L2T details, yet.  I renamed package.nuspec to LinqToTwitter.nuspec. Here's what LinqToTwitter.nuspec looks like after I modified the default values:



  
    LinqToTwitter
    2.0.21
    Joe Mayo
    Joe Mayo
    http://linqtotwitter.codeplex.com/license
    http://linqtotwitter.codeplex.com/
    http://download.codeplex.com/Project/Download/FileDownload.aspx?ProjectName=linqtotwitter&DownloadId=68381&Build=17672
    true
    LINQ to Twitter is a 3rd party LINQ Provider for the Twitter micro-blogging service. It uses standard LINQ syntax for queries and includes method calls for changes via the Twitter API.
    LINQ Twitter
  

When initially building this package, I was using an HTTP URL and encountered the following error:

'&' is an unexpected token. The expected token is ';'. Line 10, position 119.

The iconUrl element contained '&' parameter separators.  The error occurred because we're working with XML and the '&' needs to be encoded as '&'.  Making this change allowed the URL to be interpreted properly.

Most of the spec elements are self-explanatory, but I did notice that the requiresLicenseAcceptance defaults to false.

I imagine the tags will affect the results of a NuGet search operation, so I figured anyone who is interested in either LINQ or Twitter might want to know the package is there.  At this point, some people might experience an overwhelming desire to add tags like windows, dotnet, wpf, silverlight, wcf and others; but that might begin to fall into an undesirable category that would go under a tag named "spam", so please resist the urge. 

The default package.nuspec file contains an element named dependencies that is missing from my example. There was a time when L2T had a lot of dependencies outside of the framework, but now it doesn't have any. Next, I'm going to discuss the artifacts that actually go into the package.

Setting up Artifacts

I needed to create a file structure to hold L2T artifacts and immediately created a folder in the L2T solution area. After this brainless maneuver, I had second thoughts about the location of the package.  On one hand, it seems to make sense to manage it under source control.  However, on the other hand the L2T solution is already much larger than it needs to be with sample apps, resources, and the like.  People all over the world download the source code every day and don't enjoy the cheap and readily available bandwidth that I do.  I'm seriously considering lightening up the solution some time in the future, so it's a less than logical choice to be adding more weight now.  Besides, I can manage the NuGet package with my own source control and make it available separately because most people won't care about that it anyway.

The top level of the conventions based file system looks like this, which I created in a folder that I wanted to hold files in:

<base folder>
    LinqToTwitter.nuspec
    - content
    - lib
    - tools

The <base folder> above represents any folder in your file system.  I performed all commands from that folder, fully qualifying the file location of the NuGet.exe, which you won’t see in the examples (for simplicity), but should assume that I did.  Notice that I located LinqToTwitter.nuspec at the same level of the other folders, under <base folder>. I won't be using content or tools this time around, but will need them some time in the future.  What I'm most interested in is the lib folder, which is where I'll put the different versions of L2T assemblies.

Assembly Versioning Conventions

From the docs, the framework version convention goes like this:

lib\{framework name}{version}

The frameworks L2T supports are .NET (v3.5 and v4) and Silverlight (v4), so my folder structure, under lib, looks like this:

<base folder>
    - content
    - lib
        - net20
            LinqToTwitter.dll
        - new40
            LinqToTwitter.dll
        - sl40
            LinqToTwitterAg.dll
    - tools

The process I used to place DLL's into each folder is: Set Release mode, open the L2T project, set the version, rebuild, and copy the built DLL from the project Release output folder into its corresponding NuGet folder.

The documentation has details on the conventions and more information on options like supporting micro-framework and client or full profiles.  I might look at these options in the future, but this is where I'm at today.

This finishes creation of the package.  The next step is to prepare the package for publication.

Preparing the Package

Running the following command allows you to build and publish NuGet packages from your machine:

NuGet setapikey <your api key>

You can get this API key by creating a Nuget account at http://nuget.org.  After you have an account, click on the MY ACCOUNT link and the API key will be there.  I know that the command option says API key, but the page calls it an Access Key.

The following command builds the package:

NuGet pack .\LinqToTwitter.nuspec

This command creates a file named LinqToTwitter.2.0.21.nupkg.  At this point, I could publish the package, but I have this habit of testing applications before deploying them to production.

Setting up a NuGet Test Server

In the documentation, there's a section on Hosting Your Own NuGet Feeds, that explains how to set up a local NuGet server. This is what I did to verify that my package is built properly and downloads like I expect it to.  Here are the steps I took, which closely mirror the docs.

  1. I created a folder called LocalNuGetFeed and copied LinqToTwitter.2.0.21.nupkg into it.
  2. In VS 2010, I selected Tools, Library Package Manager, Package Manager Settings.
  3. Under the Package Manager branch in Options, select Package Sources. This is where you can create any number of NuGet library sources, including your own server.
  4. To add the test server, type a Name (I called mine LocalTest), put the file path to the LocalNuGetFeed folder in the Source, and click the Add button.  You'll see your server under the normal NuGet server.
  5. Click the OK button and your server is now set up.

Next, it was time to test.  Here are some basic steps showing what I did:

  1. Opened a project to test on. I created a brand new Console project.
  2. Right-click on references and select Manage NuGet Packages.
  3. In the accordion menu on the left, click On-Line. You'll see the new LocalTest server that was added during the previous steps.
  4. Click the LocalTest server and observe that the LinqToTwitter package appears.
  5. After verifying that the version and all other information was correct. I clicked the install button.

... of course it worked.  Further tests included creating a .NET 3.5 Console app and creating a Silverlight app.  In each chase, NuGet created a proper reference to the appropriate assembly version.

One anomaly I saw during the process was an access denied error after switching .NET Framework versions on a package that was already opened.  I shut down VS and reopened and the problem went away.

The Final Push

Once I confirmed the package was working properly, I need to publish it.  In other words, I needed to deploy the package to the NuGet server so other developers can download it.  Here's the command:

NuGet push .\LinqToTwitter.2.0.21.nupkg

After running through the command-line percentage updates, I received confirmation that the package was published.  It took a minute for it to appear on the site, but after a page refresh, the new package showed up at the top of the list as the default package.  I needed to edit the Title to remove spaces because the server used the package ID, but other than that everything worked fine.

Summary

I've shown you my experience in building a NuGet package, using LINQ to Twitter as the example application. You saw how I got started, built the package, tested, and deployed.  When testing, you saw how easy it is to create a local NuGet server.  My decision making process was based on my own situation and the assumptions for LINQ to Twitter, but maybe it will help you think about what decisions affect your applications.  I've found the entire process to be fun and interesting.  Kudos to the folks who built this because I continue to be impressed.

@JoeMayo

Posted on Monday, July 11, 2011 4:34 AM Twitter , LINQ , LINQ to Twitter , NuGet | Back to top

Copyright © Joe Mayo | Powered by: GeeksWithBlogs.net