Coding

Packaging Contract Assemblies Like A Pro

This is a short follow up to my NuGet Like A Pro post.  I left an additional step out of that post, even though I almost always need to to do it.  I didn’t think this next step was widely applicable, and wanted to position the previous post as a “Super Duper Happy Path” that most people could follow with out confusing digressions.

However, I did my self a disservice by leaving it out, because now whenever I need to refresh my memory by reading my own post, I am left still having to figure out this one step again.  So, I’m going to post it here so that I’ve got all my documentation in one place.

Contract Assemblies

If you don’t know what they are, then you probably don’t need to read this post.  However, if you are curious they are an artifact created when using Code Contracts.

Code Contracts provide a language-agnostic way to express coding assumptions in .NET programs. The contracts take the form of preconditions, postconditions, and object invariants. Contracts act as checked documentation of your external and internal APIs. The contracts are used to improve testing via runtime checking, enable static contract verification, and documentation generation.

In other words, Code Contracts are another form of static analysis and client code needs to know about your contracts in order to properly evaluate their own contracts.  This is where the contract assembly comes in, it provides the contract information about the assembly in your package.

So you need to create this assembly, put it in your nuget package so that the contract checker can find it, and then give nuget a hint indicating that only the “normal” assembly should get a project reference, while the contract assembly (which only contains metadata) should not be referenced by the project.

Creating the Contract Assembly

This step is easy, but I will include it for those who are new.  First one must visit the Visual Studio Gallery and download the tools.  Once the tools are installed, the Visual Studio project properties page will grow a new blade, pictured below.

Code Contracts Control Panel
Code Contracts Control Panel

I check almost everything in the “Static Checking” section and leave “Runtime Checking” alone.  It would be off topic to explain why in this post, but you can visit the Code Contracts website and make your own decision.  You can also choose not to turn anything on, yet still build the Contract Reference Assembly.  This will let clients using Contracts know that you don’t have any.

By default, the Contract Reference Assembly is not configured to build, but as you can see in the red rectangle, I have turned it on.

Now when I build my project, the additional assembly is created (below the build output folder, in a subfolder called “CodeContracts”)

The Contract Assembly
The Contract Assembly

Adding to the package

Now that you have the assembly you can let nuget know about it by adding a file reference to the nuspec file.  This reference goes in the files node, which is a child of the package node.  I usually put it right after the metadata node:

  </metadata>
  <files>
    <file src="bin\Debug\CodeContracts\TemporaryFile.Contracts.dll" target="lib\net45" />
  </files>
</package>

After rebuilding, you will see that the Contract assembly is now packaged with the normal library.

Packaged
Packaged

However, if you were to use this package as is, NuGet would add a reference to the Contracts assembly as well as the library.  To prevent that, we provide NuGet a white list of assemblies which should be referenced, and it will ignore the rest.

To do this, add a child node to metadata called “references” and a “reference” node for the normal library.

    <references>
      <reference file="TemporaryFile.dll" />
    </references>
  </metadata>
  ...
</package>

Now rebuild again, and the NuGet Package Explorer will indicate that the assembly references have been “filtered”.

Filtered
Filtered

Conclusion

So, to distribute Contract Assemblies (or other any assembly which should not be referenced) follow the steps above.  First create the assembly you want to distribute.  Next add a file reference to the nuspec which points at the new assembly.  Then, add a references node and add references to each assembly which should be referenced (the new assembly should not be in this section, but the original assembly should be).  After filtering your references you are ready to go.  Upload your package to your favorite feed (nuget.org, myget.org, proget, etc…) and pour yourself a drink.

Coding

CodeProvider: Create Contract Class

I’ve used the free offering (CodeRush Xpress) from Developer Express for years, and my feelings about it can be summed up by paraphrasing Larry Wall: “A machine without CodeRush is a sad machine indeed.”  Over the last few weeks I’ve been interested in implementing my own CodeRush plugin.  Prompted in no small part by Mark Miller’s decision to implement my CodeRush plugin suggestion during the weekly CodeRush Feature Workshop, I’ve taken the plunge and written my first plugin.  Here it is.

What’s it for?

A code provider in CodeRush automatically creates typical code blocks appropriate to the current coding context.  For example, the suggestion Mark Miller implemented was to add the IDisposable interface to an existing class.  When called on a class that does not implement IDisposable, this code provider adds “IDisposable” to the type declaration, implements the appropriate methods, and ensures that any disposable fields owned by the class are disposed.  Writing this code by hand typically took a bout 20 minutes.  Using Visual Studio code snippets got that down to about 5 minutes.  Using CodeRush, the code is generated instantly and consistently.  Pretty cool.

For those of you out there using Code Contracts, I’ve created a code provider that will implement a buddy class to hold contracts for an interface.  The provider will add a namespace reference to System.Diagnostics.Contracts to your interface file, decorate your interface with the ContractClassAttribute, then generate the buddy class in a separate class.  The buddy class file will import all the namespace references from the interface file, and the code provider will decorate it with the ContractClassForAttribute.  Each method and property on the interface will be explicitly implemented in the buddy class.  Property getters and non-void methods will return the default values for their types.  A TODO comment is placed into each member body, indicating where the contracts should go.

A little sugar

Since I’m scratching my own itch with this plugin, I decided to take it as far as I could.  I use FxCop and StyleCop on all my production code, so I wanted to make sure that the buddy class would leave me as little work to do as possible.  So, if the interface file has a file header comment, this is copied, updated with the buddy class file name, then placed at the head of buddy class file.  The namespace references are sorted in the order that StyleCop expects, and placed inside the the file namespace.  The provider generates an Xml documentation summary comment for the buddy class.  When Xml documentation comments are found on the interface, these are copied onto the appropriate methods in the buddy class.

Example

A few days ago I didn’t even know how to implement an interface contract, but I figured it was possible and quickly found this article Code Contracts Primer – Part 6 Interface Contracts by Derik Whittaker.  If Part 6 is any indication of the quality of this series, then Derik’s articles are a great place to start learning about Code Contracts if you are new to the subject.  (Another nice resource is Towards Code Correctness: Integrating Software Contracts and Unit Testing).  I’m going to use an example I’ve adapted from Derik’s article to show how the “Create Contract Class” code provider works.

You start with an interface that you would like to create specifications for:

//-----------------------------------------------------------------------
// <copyright file="IPayrollCalculator.cs" company="Jim Counts">
//     Copyright (c) Jim Counts 2011. All rights reserved.
// </copyright>
//-----------------------------------------------------------------------
namespace PayrollCalculatorExample
{
  using System;
  using System.Collections.Generic;
  using System.Linq;
  using System.Text;

  /// <summary>
  /// Describes a payroll calculator.
  /// </summary>
  public interface IPayrollCalculator
  {
    /// <summary>
    /// Gets the state or province.
    /// </summary>
    string StateOrProvince { get; }

    /// <summary>
    /// Gets or sets a value indicating whether to withhold tax.
    /// </summary>
    /// <value>
    ///   <c>true</c> if withholding tax; otherwise, <c>false</c>.
    /// </value>
    bool WithholdTax { get; set; }

    /// <summary>
    /// Calculates the paycheck.
    /// </summary>
    /// <param name="baseRate">The base rate.</param>
    /// <param name="hoursWorked">The hours worked.</param>
    /// <returns>The paycheck amount.</returns>
    double CalculatePaycheck(double baseRate, int hoursWorked);

    /// <summary>
    /// Determines the base rate.
    /// </summary>
    /// <param name="employeeType">Type of the employee.</param>
    /// <returns>The employee base rate.</returns>
    double DetermineBaseRate(EmployeeType employeeType);
  }
}

Then, put your cursor on the interface declaration and use CTRL+~ to bring up the CodeRush menu.  Select the “Create Contract Class” menu item and the code provider goes to work.

CRMenu

The provider creates a new class in a new file.  The name is chosen by convention.  The provider removes the leading ‘I’ from the interface name and concatenates “Contract” to the end.  So in this example, it generates a class called PayrollCalculatorContract, and puts it in PayrollCalculatorContract.cs:

//-----------------------------------------------------------------------
// <copyright file="PayrollCalculatorContract.cs" company="Jim Counts">
//     Copyright (c) Jim Counts 2011. All rights reserved.
// </copyright>
//-----------------------------------------------------------------------
namespace PayrollCalculatorExample
{
  using System;
  using System.Collections.Generic;
  using System.Diagnostics.Contracts;
  using System.Linq;
  using System.Text;

  /// <summary>PayrollCalculatorContract class contains CodeContract declarations for IPayrollCalculator.</summary>
  [ContractClassFor(typeof(IPayrollCalculator))]
  public sealed class PayrollCalculatorContract : IPayrollCalculator
  {
    /// <summary>
    /// Gets the state or province.
    /// </summary>
    string IPayrollCalculator.StateOrProvince
    {
      get
      {
        // TODO: Add Contracts Here
        // CodeContracts runtime will ignore this return value.
        return default(string);
      }
    }

    /// <summary>
    /// Gets or sets a value indicating whether to withhold tax.
    /// </summary>
    /// <value>
    ///<c>true</c> if withholding tax; otherwise, <c>false</c>.
    /// </value>
    bool IPayrollCalculator.WithholdTax
    {
      get
      {
        // TODO: Add Contracts Here
        // CodeContracts runtime will ignore this return value.
        return default(bool);
      }
      set
      {
        // TODO: Add Contracts Here
      }
    }

    double IPayrollCalculator.CalculatePaycheck(double baseRate, int hoursWorked)
    {
      // TODO: Add Contracts Here
      // CodeContracts runtime will ignore this return value.
      return default(double);
    }

    double IPayrollCalculator.DetermineBaseRate(EmployeeType employeeType)
    {
      // TODO: Add Contracts Here
      // CodeContracts runtime will ignore this return value.
      return default(double);
    }
  }
}

The type declaration for IPayrollCalculator is decorated with the appropriate attribute, and the Contracts namespace reference is tucked right between System.Collections.Generic and System.Linq:

namespace PayrollCalculatorExample
{
  using System;
  using System.Collections.Generic;
  using System.Diagnostics.Contracts;
  using System.Linq;
  using System.Text;

  /// <summary>
  /// Describes a payroll calculator.
  /// </summary>
  [ContractClass(typeof(PayrollCalculatorContract))]
  public interface IPayrollCalculator
  {

When the provider finishes, you will be looking at the buddy class implementation, and the project should compile as is.  In this example, StyleCop has three complaints, two of them related to fact that there is not a blank line between the getter and setter for “WithholdTax” and one complaint that there is not a leading space preceding the <value> tag in the XML documentation for “WithholdTax”.  Pretty nice.  If you care about those warnings, you have two things to fix, and if you don’t you can get straight to writing your contracts!

Warts

This code provider is definitely alpha.  I know it may have some issues with VB.NET interfaces that are not nested inside an explicit namespace.  I haven’t done any testing with anything except C#, or any coding style except my own.  Also, the provider is ripe for refactoring.   Just because it makes a pretty buddy class, don’t assume the provider is pretty… it ain’t.  Anyway, I hope to clean it up in future revisions.

Thanks

Thanks go out to Developer Express for providing such a powerful tool for free, Mark Miller and Rory Becker for hosting the weekly CodeRush Feature Workshop, and once again to Rory for maintaining the CodeRush and DXCore Community Plugins site.  I would not have been able to figure out half the tricks implemented in this code provider without access to the source code for CR_GenerateTest.

Code

Here is the initial code drop, with before and after examples.