I never really ended up using MSpec on things at work. There were lots of lame reasons:

• We were using MbUnit and MSpec worked with NUnit (like I really care, seriously)
• We already had lots of existing tests and didn’t want the disjointed feeling of having two ways to do things
• I was already struggling at work getting people to adopt the new things I had already introduced into our environment.

I took what I could out of MSpec and the other Spec Driven Development stuff I got from the community and kind of rolled my own style of doing spec driven development just using MbUnit. I’ve since gathered that there are lots of people doing this.

Recently I had to do a small sample application in a short period of time. It wasn’t for work (i.e. no MbUnit legacy) and I still wanted to do it spec first, so I grabbed the latest MSpec and used that.

I noticed there are several small but appreciated changes that have been made since the last time I used MSpec, namely:

XUnit and (kind of) Gallio Support

To use Gallio/MbUnit or xUnit with MSpec, there’s really nothing special to do - just reference the testing framework you want to use and the adapter assembly.

The adapter assembly is the magic part of MSpec. It helps the unit testing framework build a model of the tests to run. When using MSpec, you’re not putting attributes on things anymore to indicate they are unit tests. The adapter is needed so the unit testing framework knows what to run as tests.

For NUnit and xUnit, there are a bunch of nice extension methods defined for doing systemUnderTest.ShouldXXX() style assertions. There aren’t any for MbUnit, but I made some in my fork of MSpec if you’re interested.

I imagine you could write an adapter for MSTest, as well as some extension methods, but my interest in MSTest-ifying MSpec this ends there.

Once you start using these extension methods, the unit testing framework dependencies kind of melt away:

public class when_pricing_an_item_that_requires_no_sales_tax : with_an_item_to_price
{
    static Money price;

    Because of = () => {

        the_product.is_not_taxed()
                   .when_shipped_to(our_destination);

        price = pricingService.PriceItem(1, the_product, our_destination);
    };

    It prices_as_the_base_price = () =>
        price.ShouldEqual(our_base_price);
}

Where’s the test framework code? Does this use NUnit? MbUnit? The only assertion here is in ShouldEqual, which is one of those extension methods that calls who cares which unit testing framework.

That’s the real lesson here: who cares which unit testing framework you’re using - that decision doesn’t add any value to your product, and doesn’t make this a valid excuse for not using MSpec. If one framework or the other works better with your build process or some tool you are using, just use that framework.

Pending

    public class when_pricing_an_item_that_requires_sales_tax_where_we_are_shipping : with_an_item_to_price
    {
            It includes_the_tax_in_the_price;
            It includes_the_tax_in_the_total_tax;
            It doesnt_include_the_tax_in_the_subtotal;
            It doesnt_include_the_tax_in_the_line_item_total;
    }

I saw Aaron demo this somewhere once, maybe at an #altnetseattle meeting or something, but I didn’t get it at first. I thought it was about going off and writing a bunch of Tests then implementing them. My view that you write one Test, then implement, then another, etc.

The difference is, when doing things Spec first, it’s…well…it’s just different. I think one reason I like one test at a time is that I am testing close to the implementation at that point. Since I am in the process of designing the system while doing TDD, I don’t know what the rest of the design is going to look like till I get there. If I write too many tests, I am speculating about what the design is going to look like.

Specs aren’t so much about the physical design of the system so they don’t change (as much) as the design evolves. If they do, they have good (read: business) reason. It’s not wrong to translate specs into code as part of the same process you are getting them (ex.: talking with a product owner…taking notes in the form of "public class whatever_context { It does_this; It does_that; …}".) That process is unlikely to be as granular as TDD tests, as no business person that is making money wants to hold your hand all day while they spoon feed you one thing at a time.

The output from running the above specs is:

when pricing an item that requires sales tax where we are shipping
>> includes the tax in the price (NOT IMPLEMENTED)
>> the tax in the total tax (NOT IMPLEMENTED)
>> include the tax in the subtotal (NOT IMPLEMENTED)
>> include the tax in the line item total (NOT IMPLEMENTED)

You can go ahead and spec things out ahead of time just saying "It does_whatever" and you’ll get a nice report of what’s to be done.

Behavior

This feature answers a question I’ve had since the first time I saw someone do BDD: What do you do when you want to specify the same behavior for multiple contexts?

[Subject("Calculating sales tax")]
public class when_an_item_is_a_kind_of_food : with_an_invoice_with_one_item
{
    Because of = () => invoice = new Invoice().WithSomeKindOf(Category.Food);
    Behaves_like<NoSalesTaxAdded> no_sales_tax_added;
}

[Subject("Calculating sales tax")]
public class when_an_item_is_a_kind_of_medical_supply : with_an_invoice_with_one_item
{
    Because of = () => invoice = new Invoice().WithSomeKindOf(Category.MedicalSupplies);
    Behaves_like<NoSalesTaxAdded> no_sales_tax_added;
}

[Behaviors]
public class NoSalesTaxAdded
{
    protected static Invoice invoice;

    It has_no_sales_tax_added = () =>
    {
        foreach (var item in invoice.Items)
            invoice.GetPostTaxValueFor(item).ShouldEqual(item.Value);
    };
}

In the samples that come with MSpec, there is an example of two implementations of the same interface, like a TypeFixture in MbUnit.

It seems like, in the applications I work on, I rarely run across a need to use this kind of test, but I do sometimes need RowTest-like tests, or, more often, factory driven tests - like to specify that for a certain set of contexts, there is some behavior. My example above is a lame attempt to illustrate this.

What’s Next

That’s kind of the technical view of things. Hopefully I’ve gotten your attention and you are git clone-ing MSpec in the background right now. I hope to post part 2 of this in a couple of days, with some examples of how I use MSpec in real code.

1. Relaxing on the Couch(DB)
2. Installing the Couch(DB)
3. PUTting the Couch(DB) in Your Living Room
4. GETting Documents From CouchDB

Today, I want to talk about how to delete a document from CouchDB. In order to do that, we have to use the HTTP DELETE operation (how convenient). Removing a document from CouchDB can be done using the following request:

DELETE /documentstore/13ce4780-62c8-4074-9955-8c99966b84bb
?rev=1-2901013762

This makes CouchDB return the following response:

{
"ok":true,
"id":"13ce4780-62c8-4074-9955-8c99966b84bb",
"rev":"2-3500205450"
}

This confirms that the document has been removed by CouchDB. But is it really gone? Not exactly. We might be able to retrieve it using its revision number. Sending the following request:

GET /documentstore/13ce4780-62c8-4074-9955-8c99966b84bb
?rev=2-3500205450

still indicates that the document we just deleted still exists:

{
"_id":"13ce4780-62c8-4074-9955-8c99966b84bb",
"_rev":"2-3500205450",
"_deleted":true
}

Notice that the _deleted attribute indicates that the document has indeed been deleted. It’s even possible to resurrect the document at hand by performing an update, bringing the document back amongst the living documents.

However, I don’t consider that a good idea in all scenarios. In fact, as pointed out by this comment on my previous post, one should not blindly rely on the MVCC tokens for version control of documents, something that I neglected to point out in that post. When CouchDB is configured for compaction or replication with other instances of CouchDB, then this approach is not recommended. In case of compaction , CouchDB will actively purge old versions of documents and deleted documents. In case of replication, a particular node in a clustered environment doesn’t necessarily have the complete version history of a document. Bottom line, use this feature very carefully.

For my next post, I will talk about how to create attachment for a document.

Till next time

First lets start with how to get started with multithreading in WPF. If you don’t want to read how this actually works and just want to get the source and start playing ,here is the Source Code.

Your WPF application may need to perform intensive tasks that consume large amounts of time. Executing these tasks on a separate thread allows you to maintain the responsiveness of the UI while the task is performed. Enter the BackgroundWorker. The BackgroundWorker is the recommended way to run time consuming tasks on a separate, dedicated thread, leaving the UI responsive.

Running a Background Process

The RunWorkerAsync method starts the execution of the background process by raising the DoWork event. The code in the DoWork event handler is executed on a separate thread.

int maxRecords = 1000;

BackgroundWorker worker = new BackgroundWorker();

worker.DoWork += delegate(object s, DoWorkEventArgs args)

{

    for (int x = 1; x < maxRecords; x++)

    {

        System.Threading.Thread.Sleep(10);

    }

};

worker.RunWorkerAsync();

Providing Parameters to the Process

Your background process may required one or more parameters, such as the address of a file to download. You can provide a parameter in the RunWorkerAsync method that will be available as the Argument property in the DoWork event handler.

BackgroundWorker worker = new BackgroundWorker();

worker.DoWork += delegate(object s, DoWorkEventArgs args)

{

    string path = (string)args.Argument;

    //do something

};

worker.RunWorkerAsync("c:\\myFile.txt");

Returning a Value from the Process

You might want to return a value from a background process, such as a result from a calculation. You can return a value by setting the Result property of the DoWorkEventArgs in the DoWork event handler. Then, this value can be retrieved from the Result property of the RunWorkerCompletedEventArgs parameter int the RunWorkerCompleted event handler.

BackgroundWorker worker = new BackgroundWorker();

worker.DoWork += delegate(object s, DoWorkEventArgs args)

{

    args.Result = CalculationMethod();

};

worker.RunWorkerCompleted += delegate(object s, RunWorkerCompletedEventArgs args)

{

    object result = args.Result;

};

worker.RunWorkerAsync();

Cancelling the Background Process

You may want to allow the user to cancel a long running process. In order to support this you must first set the WorkerSupportsCancellation to true. You call the CancelAsync mtehod to attempt to cancel the process. When you call the CancelAsync method it sets the CancellationPending property of the BackgroundWorker to true. Then you must check for the value of the CancellationPending property in the DoWork event handler, and if it is true, set the Cancel property of the DoWorkEventArgs parameter to true.

int maxRecords = 1000;

BackgroundWorker worker = new BackgroundWorker();

worker.WorkerSupportsCancellation = true;

worker.DoWork += delegate(object s, DoWorkEventArgs args)

{

    for (int x = 1; x < maxRecords; x++)

    {

        //check if there is a cancelat

        if (worker.CancellationPending)

        {

            args.Cancel = true;

            return;

        }

        System.Threading.Thread.Sleep(10);

    }

};

worker.RunWorkerAsync();

Reporting the Progress of a Background Process

You can report the progress of a background process back to the primary thread by calling the ReportProgress method. This method raises the ProgressChanged event and allows you to pass a parameter that indicated the percentage of progress that has been completed. Make sure you set the WorkerReportsProgess property of the BackgroundWorker to true.

int maxRecords = 1000;

BackgroundWorker worker = new BackgroundWorker();

worker.WorkerReportsProgress = true;

worker.DoWork += delegate(object s, DoWorkEventArgs args)

{

    for (int x = 1; x < maxRecords; x++)

    {

        System.Threading.Thread.Sleep(10);

        worker.ReportProgress(Convert.ToInt32(((decimal)x / (decimal)maxRecords) * 100));

    }

};

worker.ProgressChanged += delegate(object s, ProgressChangedEventArgs args)

{

    int percentage = args.ProgressPercentage;

};

worker.RunWorkerAsync();

Using the Dispatcher to Access Controls on Another Thread

At times, you may want to change the user interface from a worker thread. For example, you may want to enable or disable buttons, or show a modal ProgressBar that provides more detailed progress information than is allowed by the ReportProgress method. The WPF threading model provides the Dispatcher class for cross thread calls. By using the Dispatcher, you can safely update your user interface from background worker threads.

You can get a reference to the Dispacther object for a UI element from its Dispatcher property.

System.Windows.Threading.Dispatcher aDisp = Button1.Dispatcher;

Dispatcher provides two main methods that you will use; Invoke and BeginInvoke. Both methods allows you to call a method safely on the UI thread. The BeginInvoke method allows you to call a method asynchronously, and the Invoke method allows you to call a method synchronously.

Putting It All Together

Lets say I have a time consuming task in my application.  I want to execute this time consuming task on a background thread, but I also want to show a modal progress dialog that shows a message and the percent of the completed task. I also want to allow the user to cancel the process at anytime. So the first thing I need to do is create my progress dialog window that has a label to display my percent completed, a progress bar to graphically show the progress, and a cancel button so the user can cancel the process.

<Window x:Class="MultiThreading.ProgressDialog"

    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"

    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"

    Title="ProgressDialog" Height="115" Width="300" WindowStyle="ToolWindow" WindowStartupLocation="CenterOwner">

    <Grid>

        <StackPanel>

            <Label x:Name="lblProgress" Content="0%"/>

            <ProgressBar x:Name="progress" Height="25" IsIndeterminate="False"></ProgressBar>

            <StackPanel Orientation="Horizontal" HorizontalAlignment="Right">

                <Button x:Name="btnCancel" Click="btnCancel_Click">Cancel</Button>

            </StackPanel>

        </StackPanel>

    </Grid>

</Window>

I need to expose two properties; ProgressText to set my label, and ProgressValue to set the progress bar value. I also need to expose an event so when the user hits the cancel button the process will stop.

   1: public string ProgressText

   2: {

   3:     set

   4:     {

   5:         this.lblProgress.Content = value;

   6:     }

   7: }

   8:  

   9: public int ProgressValue

  10: {

  11:     set

  12:     {

  13:         this.progress.Value = value;

  14:     }

  15: }

  16:  

  17: public event EventHandler Cancel = delegate { };

  18:  

  19: private void btnCancel_Click(object sender, RoutedEventArgs e)

  20: {

  21:     Cancel(sender, e);

  22: }

Now on my main application I need a button to execute this long running process and show my progress dialog.

<Button Height="23" Name="btnDispacther" Click="btnDispacther_Click">Using Dispatcher</Button>

Now lets code the background worker.

//our bg worker

BackgroundWorker worker;

//our progress dialog window

ProgressDialog pd;

private void btnDispacther_Click(object sender, RoutedEventArgs e)

{

    int maxRecords = 1000;

    pd = new ProgressDialog();

    //hook into the cancel event

    pd.Cancel += CancelProcess;

    //get our dispatcher

    System.Windows.Threading.Dispatcher pdDispatcher = pd.Dispatcher;

    //create our background worker and support cancellation

    worker = new BackgroundWorker();

    worker.WorkerSupportsCancellation = true;

    worker.DoWork += delegate(object s, DoWorkEventArgs args)

    {

        for (int x = 1; x < maxRecords; x++)

        {

            if (worker.CancellationPending)

            {

                args.Cancel = true;

                return;

            }

            System.Threading.Thread.Sleep(10);

            //create a new delegate for updating our progress text

            UpdateProgressDelegate update = new UpdateProgressDelegate(UpdateProgressText);

            //invoke the dispatcher and pass the percentage and max record count

            pdDispatcher.BeginInvoke(update, Convert.ToInt32(((decimal)x / (decimal)maxRecords) * 100), maxRecords);

        }

    };

    worker.RunWorkerCompleted += delegate(object s, RunWorkerCompletedEventArgs args)

    {

        pd.Close();

    };

    //run the process then show the progress dialog

    worker.RunWorkerAsync();

    pd.ShowDialog();

}

//our delegate used for updating the UI

public delegate void UpdateProgressDelegate(int percentage, int recordCount);

//this is the method that the deleagte will execute

public void UpdateProgressText(int percentage, int recordCount)

{

    //set our progress dialog text and value

    pd.ProgressText = string.Format("{0}% of {1} Records", percentage.ToString(), recordCount);

    pd.ProgressValue = percentage;

}

void CancelProcess(object sender, EventArgs e)

{

    //cancel the process

    worker.CancelAsync();

}

That’s it. See, I told you it wasn’t that bad. Now that you have a basic understanding of multithreading, try to see how creative you can get on implementing it in your WPF application.

What all of those have in common is that none of them will profile .net Compact Framework.  But I found a profiler yesterday that does, plus it is free: EQATEC Profiler. 

The basics of how to use this profiler is to “point” the profiler at your application (the executable, not the source), then use the Profiler “build”.  What happens here is the profiler modifies your executable to include new tracing/logging for the profiler, but in a different directory (a *-Profiled directory).

If you look in the Profiling options you will see a directory where the profile logs are written. Note: the log is an xml file in the form of an *.eqlog file.

Now, if you are running a plain-Jane .net desktop executable, you can just click run and start profiling.  If you are running a .net cf executable you need to do a little more work.   The little more work is connect your device/emulator to you operating system, and copy the profile-enabled executables to the device.  Then manually run the executable on the device.  Once done, find the *.eqlog file on the device and copy it to your host machine.  From there you can simply double click the log file and analyze the results.

  Here is what you get in return.  The report includes:

• Total(full)Total number of milliseconds a method took to run in each case.  Includes calls to child methods
• Avg(full) Average number of milliseconds each call of the method took to run
• Total(self) Total number of milliseconds a method took to run, excluding child calls
• Avg(self) Average number of time the method took per call
• Calls – Total number of calls to the method
• Method Name (why is this last?)

Note: go to the Help page for more details.

The pretty picture in the Details portion of the UI is an interactive call stack browser.

OK, so is this enough? Yes, but it is 100% that what I was able to get.  Even though the results are somewhat simplistic, it is still very useful.  I was able to find where I had some performance problems.  I would love to have a UI to compare profile runs, but this will do for now.

One other thing this profiler does not do is Memory Profiling (NetCFCLRProfiler.exe, once installed, found at C:\Program Files\Microsoft.NET\SDK\CompactFramework\v3.5\bin).  Fortunately there is one in the Power Toys for .Net Compact Framework 3.5.  If I get some time I’ll go over that one later.

Also, for further info on profiling .net cf applications, check out this post by David Kline.

1. Relaxing on the Couch(DB)
2. Installing the Couch(DB)
3. PUTting the Couch(DB) in Your Living Room

In my latest post, I explained how easy it is to create and manage documents in CouchDB. Today, I want to talk about how to retrieve a document from CouchDB.

In order to retrieve a document from CouchDB, we make use of the HTTP GET operation (duh). Using the GET method for retrieving a document takes the following general form:

http://myhost:5984/my_database/my_id

Its as simple as that. So, for example, sending the following request:

GET /documentstore/96f49e5a-6b5b-47ed-9234-9a98d600013e

makes CouchDB return the following response:

{
"_id":"96f49e5a-6b5b-47ed-9234-9a98d600013e",
"_rev":"2-1534297415",
"Author":"Stephen Hawking",
"Title":"The Universe in a Nutshell",
"Tags":[{"Name":"Physics"},{"Name":"Universe"},{"Name":"Space"}]
}

As already mentioned, CouchDB provides MVCC (multi-version concurrency control) for the documents it stores. Using the GET operation makes it possible to take advantage of this built-in feature. Notice that the first digit of the revision number in the example above indicates that this is the second version of the document we retrieved. This means that CouchDB possibly has an earlier version of the document. In order to find out what revisions are available, we can issue the following request:

GET /documentstore/96f49e5a-6b5b-47ed-9234-9a98d600013e?revs=true

CouchDB returns the current revision of the document as before, but now with an additional field named _revisions:

{
"_id":"96f49e5a-6b5b-47ed-9234-9a98d600013e",
"_rev":"2-1534297415",
"Author":"Stephen Hawking",
"Title":"The Universe in a Nutshell",
"Tags":[{"Name":"Physics"},{"Name":"Universe"},{"Name":"Space"}],
"_revisions":{"start":2,"ids":["1534297415","3158114761"]},
}

In order to retrieve the first revision of our document, we can send the following request to retrieve it:

GET /documentstore/96f49e5a-6b5b-47ed-9234-9a98d600013e?rev=1-3158114761

As expected, CouchDB now returns the first revision of the document:

{
"_id":"96f49e5a-6b5b-47ed-9234-9a98d600013e",
"_rev":"1-3158114761",
"Author":"Stephen Hawking",
"Title":"The Universe in a Nutshell",
"Tags":[{"Name":"Physics"},{"Name":"Universe"}]
}

It seems that for the second revision of the document, we have added an extra tag. Having this kind of automatic versioning for your data is a really nice feature in my book.

For my next post, I will talk about how to delete a document from CouchDB..

Till next time

Oh well.

It seams that each time I start a new project I have to relearn how to grab values out of a DropDownList – I mean “select element”.  Anyway, I’m trying to get this down before I go nuts and have to learn it all over again.

Basic Select

First off, here is the basic html I’m talking about:

   1: <select id="ComboBox" >

   2:       <option value="1">Value 1</option>

   3:       <option value="2">Value 2</option>

   4:       <option value="3">Value 3</option>

   5:       <option value="4">Value 4</option>

   6:       <optgroup label="Group1">

   7:         <option value="5">Value 5</option>

   8:         <option value="6">Value 6</option>

   9:         <option value="7">Value 7</option>

  10:         <option value="8">Value 8</option>

  11:       </optgroup>

  12:     </select>

Value 1 Value 2 Value 3 Value 4 Value 5 Value 6 Value 7 Value 8

Nice and simple.  Now, the basic things you want to do with said select statement:

1. Get the value of the selected item.

2. Get the text of the selected item.

3. Find out when the value changed

4. Programmatically set the selected item.

5. Modify the list.

Most of those are very easy with JQuery, but one is slightly strange. Lets go through these one by one:

1. Get the value of the selected item

This is the easiest.  Use the val method.  All done.

   1: $("#ComboBox").val()

2. Get the text of the selected item

You would think this would be easy as well, but it isn’t.  You cannot just use the text() method on the combobox.  That will give you the text values of all of the options in a single string.  Not what you want.  The trick is to use the :selected query modifier on the option.

   1: $("#ComboBox option:selected").text()

Now, you might be tempted to use the ‘>’ (means direct descendent of) between the #ComboBox and the option — don’t.  If you look at my example above, that code will only work for options not in optgroup nodes.

3. Find out when the select value changed

This is also rather easy with JQuery.

   1: $("#ComboBox").change(function() { /* do something here */ });

4. Programmatically set the selected item.

   1: $("#ComboBox").val(2);

5. Modify the list.

Modifying a select element is not fundamentally different than modifying any other element in the dom, but there are a few basics here to keep in mind. Mainly: try to avoid using the dom directly.  Create html strings instead.

Clear the list:   $(“#ComboBox”).html(“”);

Add to the list: $(“<option value=’9’>Value 9</option>”).appendTo(“#ComboBox”);

Simple as that.

1. Relaxing on the Couch(DB)
2. Installing the Couch(DB)

Now, for this post I want to talk about how to create and manage documents. As I already mentioned in my introductory blog post, CouchDB is accessible through a RESTful HTTP/JSON API. This means that documents are stored as JSON objects. Let me show you an example of how to store a document in CouchDB. 

Suppose we have a class named Document (how creative of me). A Document has a title, an author and a collection of Tag objects. A Tag is a value object that has a name.

public class Document
{
    private readonly ISet<Tag> _tags;

    public String Author { get; }
    public String Title { get; }
    public Guid Id { get; }
    public String Version { get; }

    public IEnumerable<Tag> Tags
    {
        get { return _tags; }
    }
}

public class Tag : ValueObject<Tag>
{
    public String Name { get; private set; }

    public Tag(String name)
    {
        Name = name;
        RegisterProperty(value => value.Name);
    }
} 

Nothing fancy so far. Now in order to save an instance of this class, we have to serialize it to its JSON representation. I’ve been using Json.NET for this purpose, but you might as well use the JavaScriptSerializer class from the .NET framework.

Now, in order to save a document, we make use of the PUT HTTP method. This implies that we have to provide our own document identifier. We have to initialize the Id property with a new GUID for a new Document. We could also make use the POST HTTP method. This way you don’t have to specify your own document identifier and let CouchDB generate one for you when the document is initially stored. But this is discouraged because proxies and other network intermediaries are able to resend POST requests resulting in duplicate documents.

Creating a new document in CouchDB using the PUT method takes the following general form:

http://myhost:5984/my_database/my_id

So for our example, sending the following request:

PUT /documentstore/80c8675d-2015-45f5-a3c7-098226e15ce3 HTTP/1.1
Content-Type: application/json
Host: 146.135.16.100:5984
Content-Length: 1215256
Expect: 100-continue

{
"Author":"Stephen Hawking",
"Title":"The Universe in a Nutshell",
"Tags":[{"Name":"Physics"},{"Name":"Universe"}]
}

makes CouchDB return the following response:

{
"ok":true,
"id":"80c8675d-2015-45f5-a3c7-098226e15ce3",
"rev":"1-1437623276"
}

You probably figured out by now that this response means that the document has successfully been stored by CouchDB. Notice that it also returns a revision number that was generated upon creating the document in the database. This is important when we try to save changes to the document later on.

If you’re as suspicious as I am, you probably want to verify whether CouchDB  correctly stored the document we’ve provided. You can do this using Futon, the web-based user interface of CouchDB. You can access Futon through the following URL:

http://myhost:5984/_utils

Say that we already want to make some changes to the document we just created. Lets add a new tag to the document named ‘Space’. We add a new Tag object to the instance of our Document, we serialize it back to its JSON representation and send the following request, asking CouchDB to save the changes:

PUT /documentstore/80c8675d-2015-45f5-a3c7-098226e15ce3 HTTP/1.1
Content-Type: application/json
Host: 146.135.16.100:5984
Content-Length: 1705803
Expect: 100-continue

{
"_rev":"1-1437623276",
"Author":"Stephen Hawking",
"Title":"The Universe in a Nutshell",
"Tags":[{"Name":"Physics"},{"Name":"Universe"},{"Name":"Space"}]
}

Notice that we are using the PUT method again, but now we also provided the revision number we got back from our first response when we initially created the document. Also notice that we are sending the complete document again, but now with the extra tag.

CouchDB returns the following response that contains a new revision number for the document:

{
"ok":true,
"id":"80c8675d-2015-45f5-a3c7-098226e15ce3",
"rev":"2-3213552600"
}

Again, you can use Futon to verify if CouchDB stored a new version of the document. For my next post on CouchDB, I will talk about how retrieve a document from CouchDB.

At Blackfin, we use SourceGear Vault and CruiseControl.net. (We’re moving to Subversion and TeamCity, but that’s a different post.)  One of our projects on one of our CC.NET servers was failing with this exception:

“The working folder state information for C:\CruiseControl.NET\Build\MyProject\working is incompatible with this version of Vault.  Please choose a different working folder path.  The specific compatibility exception was: Could not detect the file type in the supplied stream.”

Vault likes to litter your system with lots of little state files, and on rare occasion these files get corrupted.  To fix, you just delete the local cache directories, re-get repositories, and you’re on your way again.  Piece of cake. 

I deleted all the cache files on this server, from C:\Documents and Settings\{username}\Local Settings\Application Data\SourceGear.  To be thorough, I delete all the cache files I can find for all users.  BUT, the exceptions continue.

Thinking to myself, “well obviously I’ve not deleted the right directory” I run a search for all directories named “Vault_1”, which turns up…nothing.

What follows next is a bunch of flailing about, checking for cc.net bugs, and to sum up: grasping at straws.  What *should* have happened is that I re-read the exception and think carefully about what causes it: a corrupted state file that I haven’t deleted yet.

I run CruiseControl.Net as a service, under the local NetworkService account.  Therefore, I [failed to] reason, the cache files must be in C:\Documents and Settings\NetworkService\Local Settings\Application Data\SourceGear.  But I couldn’t find this directory on the system.  Except that the NetworkService directory is marked as a “protected Operating System file”.  Remember that Folder option “Hide protected operating system files (recommended)” that you always switch off and ignore the dialog box that pops up?  It was still checked…

Uncheck that dumb setting, go into the directory, delete the cache, and now the build works again. 

Lesson: sometimes exceptions tell you exactly what’s wrong.  Don’t be so quick to search for exotic solutions when the obvious one is staring you in the face.

What makes a good Software Test engineer?

“A good test engineer has a ‘test to break’ attitude, an ability to take the point of view of the customer, a strong desire for quality, and an attention to detail. Tact and diplomacy are useful in maintaining a cooperative relationship with developers, and an ability to communicate with both technical (developers) and non-technical (customers, management) people is useful. Previous software development experience can be helpful as it provides a deeper understanding of the software development process, gives the tester an appreciation for the developers’ point of view, and reduce the learning curve in automated test tool programming. Judgment skills are needed to assess high-risk or critical areas of an application on which to focus testing efforts when time is limited.”

In my opinion, more emphasis should be placed on the statement italicized above. Taking it a step further, I would say a developer with previous development knowledge of the product under test is even more valuable. Obviously domain knowledge is what increases this value. From previous experiences with organizations, the development skills of the tester are often largely ignored.

“Writing code? That’s what our developers do, not our testers.”

If we are not placing a greater emphasis on the development skills of the tester, we are missing opportunities to fully test the product. Testers with a development background are more familiar with the developer’s perspective. They know the tricks developers do when writing code, they know their shortcuts and tendencies. These testers can also provide developers with insight into defensive coding, adding hooks to make automation easier, securing the product from attacks, ect.

I would argue the inverse is true as well, that having previous testing experience of the product would add value to the transition of a tester into development. A developer with a testing background should improve the testability and security of the product, because they, too, understand the importance and impact of test.

To me, test and development should be shared responsibilities. If a developer is out sick, on vacation, or the team needs a resource, a tester should be able to fill in, developing product code. If a tester is needed for similar reasons, a developer should be able to switch gears and fulfill that need as well. Neither should be more exciting nor glamorous. The organization should respect both disciplines equally. Testing is the last line of defense. 

The software engineer should have two personae, constructive and destructive. Perhaps this is similar to Dr. Jekyll and Mr. Hyde, where we replace the “evil” in Mr. Hyde with “destructive product testing.”

But there are a lot of opinions here and a lot of good discussion. Anyway, you can follow the thread. Note: I did a little bit of editing because Tony Rasa doesn’t like capital letters.

David Starr

Here comes a religious discussion.

You are building a new enterprise app. Let’s use my RecipeBox example. It is an MVC app.

What do you think about this project structure? $ = A Visual Studio Project

$RecipeBox.Core
              \Services
              \Assemblers
              \Contracts (or Interfaces) for entities and repositories
$RecipeBox.Domain
              \Entities
              \Repositories
              \Validators
$RecipeBox.Data
              \DTOs
              \Repositories
$RecipeBox.Web
              The MVC app

Thoughts?

Tony Rasa

I prefer having fewer projects and splitting things out after figuring out what the need is - so, having a .Core and .Web (along with .Tests), but then Core contains namespaces similar to what you’ve described.  But that’s just me.

There are projects where we’ve split things out by project to enforce design rules, (maybe .Web should never directly reference .Data for example) in cases where we don’t trust the developers, or there is a ‘control issue’ with the project team…  I prefer personal responsibility and reviews myself, but I suppose you’ll never get anywhere trusting to the good nature of people..

Jason Grundy

I agree with Tony - Web, Core and Test. Within these, especially as the project grows, I am starting to use namespaces as DDD modules to subdivide the app into functional areas. Nothing worse than having 250 entities in a single namsespace!

Scott Nichols

I actually like having multiple assemblies (like you laid out) for an "enterprise app". Granted "enterprise app" can mean a lot of things to a lot of people but I’ll go with the following assumptions.
- Used by a business/company/group, more likely in an intranet setting.
- The app components will be living in physical and logical tiers owned/managed by users.
- There is a possibility that other types of clients (windows, services, reporting SSRS, etc) may need to access/integrate with the apps data.
- etc, etc..
With some of these assumptions in mind I have found (my opinion) that having multiple assemblies will give you a greater degree of separation of concern, reusability between tiers and clients, and better maintainability if any of
these assemblies get reused by something other than the MVC app.  The Application Architecture Guide http://www.codeplex.com/AppArch outlines these practices as well. In fact, when I look at your example I do not think you have gone far enough. For instance…
@ = A Solution
# = A VS Solution Folder (and namespace)

$ = A Visual Studio Project
@RecipeBox
#RecipeBox.Core
                $\Services
                $\Assemblers
                $\Contracts (or Interfaces) for entities and repositories

Why would I do this?
If your Contracts and Services are in their own assemblies you can reuse them independently of each other which would be very important if you ever wanted to create a WCF service for this app (one example). Maybe down the
road you wanted to have two different implementations of the service class but they both still implement the same interface.  In any case, it would work just fine by leaving all these classes in a single RecipeBox.Core DLL
as you listed them.  Your DLL would just be a bit bigger than it needed to be if you just wanted to share your interfaces for example. Personal preference, I’ve always liked my interfaces (contracts) in their own
assembly.

The downside to all of this is that the more assemblies you add the more management is involved of your entire solution (keeping track of everything).  That was the main reason Rocky Lhotka decided to roll all the CSLA assemblies into a single DLL, much easier to distribute.  That move made sense to me though, because to use the CSLA framework you had to reference just about every assembly anyway.  That is not necessarily the case with a distributed enterprise scenario, you pick and choose more discriminately based on what you are trying to accomplish.

I have also found one other major factor that helps determine how you distribute/group your assemblies.  The structure of your IT organization. Really large distributed teams tend to break things down much more
granularly, more assemblies.  Smaller more centralized teams tend to like less assembles.  This is just an observation I’ve noticed over the years.
My two cents

David Starr

Yeah, I am, thinking in similar terms to exactly what you are saying. The other thing I like about separation via projects is a real enforcement of programming through interfaces. This is forced because to not do so would create circular project references.
Thanks, guys.

Chris Brandsma

I agree with Tony and Jason here.  But I don’t think any of us believe this is a major fighting point.

With the extra projects you get forced separation.  Which is nice for junior devs (or devs you want to put handcuffs on).  But a bad dev will figure out a way to screw up almost anything.

With fewer projects and namespaces you have a virtual separation.  But the solution loads quicker. 

I like solutions that load faster.

Jason Grundy

Some more observations:

Jeremy Miller would say that an assembly is a unit of deployment.

With multiple projects your compile time will be significantly higher.

When you have multiple pieces that need to integrate for a specific purpose then I don’t think that a single VS solution is necessarily the best solution anyway.

Darrel Carver

One last point on having more projects and assemblies.  You can separate the work among your project team.   That usually means people are working on more thing independently (interfaces can help enforce that).  It also means less conflicts when you check in the work to source code control.

David Starr

That’s what I am doing here.
Physical separation for different teams with a "meet in the middle via contract" agreement.

Jarod Ferguson

some thoughts….

Just curious, but what are the units of deployment, how many app domains? ( are the services WCF? asking because of the word *contract* in there)

This is all relevant to team size, but is sounds like you are heading in the direction of a larger org with many teams?

Its it ideal for team to be separated by modules, vertical slices. Meeting in the middle with a wcf contract may make your teams horizontal.

Why are there repositories at the Data layer & Domain layer?

What is the Data layer? I would make this DLL your contract/interface dll with all your service interfaces AND Dtos, this way the client only has to reference this one Dll to get the service interface & DTO.

As with Jason, I would move to a more vertical ‘business minded’ aka, DDD, namespacing structure as soon as the application architecture would let you (after .Domain in this example). It can get mind numbing to work in all those layers, when what you are trying to do is all related.

E.g

$RecipeBox.Domain
              \Entities\Customer.cs
              \Repositories\CustomerRepository.cs
              \Validators\CustomerValidator.cs
$RecipeBox.Domain
              \Customers
                        Customer.cs
                        CustomerRepository.cs
                        CustomerValidator.cs

Scott Nichols

While we are on the topic, the physical folder structure is very important to get nailed down as well, otherwise your source control implementation/maintenance can get a bit ugly too.   David, I imagine you being the TFS guy would be all over this.  My group put together this basic outline on how to structure the source control folders (hopefully my attachment comes through), any thoughts?

It is basically a variation of what Microsoft published at http://msdn.microsoft.com/en-us/library/bb668992.aspx. It mentions TFS but could obviously be applied to any system.

Tony Rasa

The "so we can switch to Technology X later, if we want" argument always sets off my YAGNI alarm.  If you know that you’re going to need the enterprise-wide solution, supporting multiple front ends etc, then yeah, you gotta go with the added complexity.  Scott’s one of the guys who has those extra requirements, too often i hear it applied to the
"selling junk online / customer management" website.  I think its easier to scale to that as a need is identified (ideally towards the beginning but sometimes you don’t get that luxury), otherwise you’re adding complexity without the payoff…hey, haven’t we had this discussion before

Agree on the source layout issue as well, pick a structure that works for you and run with it.. don’t let the jr devs mess up the source tree!  better yet, train the jr devs so they know better…

Chris Brandsma

Side note: this is a case where I’m not as worried about the junior devs.  Mid-levels or or mis-promoted seniors will cause more damage.

Scott Nichols

I am a huge advocate of KIS (keep it simple) and would not disagree with anyone who is trying to keep the number of assemblies to as few as absolutely needed.  I imagine given this crowd that with David’s MVC app if developed by any of us it would be layered and broken-down into a very nice API following the SOLID principles.  However, given a few other pieces of key information (not provided by David) the same code would be broken-down and packaged differently.    

David was pretty vague on the requirements (purposely so I bet).  I’ll pick on Chris for a bit (he is man enough to handle it :-)  His typical clients (correct me if I am wrong) are not the big enterprise guys that are going to have large distributed teams or infrastructure requirements that require lots of end-points that various systems will need to touch or integrate with.   He is going into a company to build application X as fast and under budget as possible in his own little sand box so to speak.   If I were in Chris’s shoes I would build this fictitious MVC app as single tired as possible.  Ok being me, I would still probably have at least three assembles.  Anything to deal or relate to data into a DAL assembly, all service type code especially if messaging based like WCF into a Services assembly, and all the remaining MVC code into a single app assembly.   Although, if it were all in one assembly I would not lose any sleep over it , Chris writes nice code, I am sure it could be repackaged later if needed quite easily.

My typical world is a bit different.  I may get the same request to build an MVC app but there would be added requirements.  This app would probably need to get data from a few systems and then provide it’s data to several other systems (highly integrated/distributed).  Multi clients in some form would be in the mix and an architecture that could easily scale the various tiers as the enterprise demands grow.   With that, you tend to break things down a bit more so you can reuse your code as I describe in my earlier e-mail.   You still need to keep your head about you though, and not go crazy on your physical abstractions (assembly madness) .  You do it where it makes sense to meet a business requirement.  Start simple (KIS) and repackage (multiple assemblies) as needed to reuse various code bases to fulfill your architecture needs.