Discovering Code

Code Contracts and Test-Driven Development

noreply@blogger.com (Craig S.) — Fri, 07 Mar 2014 04:44:00 +0000

Introduction

This post will be mostly about Microsoft’s Research in Software Engineering (RiSE) group’s Code Contracts. I’ll also cover the role of code contracts in conjunction with test-driven development. There seems to be a debate over the role of test-driven development when using code contracts. I’m going to weigh in on that debate.

In order to demonstrate code contracts, I’m going to return to the Category class that I used as an example in my blog post Advanced Test-Driven Development. This post may also be a little on the longer side.

An Introduction to Code Contracts

What are code contracts? Where did they come from? Why should I care?

The term ‘code contract’ was coined by Bertrand Meyer while he was developing the Eiffel programming language around 1986. In fact, code contracts are a core part of the Eiffel programming language to this day.

Code contracts are a way of specifying pre-conditions, post-conditions for methods and invariants for objects. Pre-conditions are predicates that specify conditions that must be met in order for a method to be in a state that can result in successful execution. Post-conditions are predicates that must be met upon any exit from a method. Invariants are predicates that validate state that must hold at all throughout the lifetime of an object.

Microsoft & Code Contracts

Microsoft’s RiSE team first introduced code contracts to .NET as an extension to the C# language known as Spec#. Spec# was basically a DSL especially for defining code contracts when programming in C#. Fast forward a few years, and shortly after the release of the .NET Framework 3.5, the RiSE team released the successor to Spec#, Code Contracts, in the form of an assembly that you can reference from your project. This assembly replaced the DSL with a native C# language implementation. For the first time in .NET (aside from the Spec# augmented language), programmers could employ code contracts (and not just simple guard conditions at method entry and rudimentary forms of post-conditions). With the release of the .NET Framework 4.0, Code Contracts have found their way into the base class library (BCL) itself. Code contracts can be found in the System.Diagnostics.Contracts namespace. You no longer need to reference an external assembly to employ code contracts.

In order to make full use of code contracts in your .NET projects, you will need to install the necessary tooling from Microsoft’s RiSE Code Contracts site. Installing this tooling installs a new project properties tab for controlling how contracts are incorporated into your assemblies, whether contracts will be enforced at runtime, and/or whether or not the static analyzer will perform an analysis of your code. For the full details, check out the Code Contracts documentation. Furthermore, the tooling installs a code contracts re-writer. The re-writer is the component responsible for weaving the necessary IL into your assemblies in order to enforce the contracts according to the options specified. OK, enough of the history lesson. Let’s get to the fun part: the code.

Using Code Contracts with the Category Class

As I stated in the introduction to this post, I’m going to be reusing the Category class example I went through in my post on advanced TDD. This class represents a category that you might find in some online e-commerce product catalog. I'm going to highlight just a few areas of the Category class as it pertains to implementing code contracts. The first part of the class we’re going to look at is instantiating the class given a name, since the pre- and post-conditions are pretty easy to follow. Also, because of this easiness, it will be easier to introduce how to incorporate unit testing when using Code Contracts.

So, starting with the a category's name: it cannot be null; it must not be the empty string; and it must not consist solely of whitespace. In my advanced TDD post, we enforced these requirements with the following code:

public class Category
{
    private string name;

    public Category(string name)
    {
        if (string.IsNullOrWhiteSpace(name))
            throw new InvalidCategoryNameException();

        this.name = SanitizeName(name);
    }
}

The guard clause is known as a pre-condition. This particular form of pre-condition is considered a defensive programming style. If the name parameter is null, the empty string, or only whitespace, an InvalidCategoryNameException exception is thrown. Notice that the constructor has no post-conditions—there is no code to ensure that the private class field name also satisfies these conditions. (In all honesty, it's hard to think of a reason why, if the name parameter meets the pre-conditions, the corresponding class field would not end up being assigned.) Let's see what this same constructor would look like using Code Contracts.

using System;
using System.Diagnostics.CodeContracts;

namespace DDDSportsStore.Domain
{
    public class Category
    {
        private string name;

        public Category(string name)
        {
            Contract.Requires<InvalidCategoryNameException>(
                !string.IsNullOrWhiteSpace(name)
            );
            Contract.Ensures(!string.IsNullOrWhiteSpace(this.name));

            this.name = SanitizeName(name);
        }
    }
}

As you can see, the guard clause was replaced with a call to Contract.Requires<T>(bool precondition). (Important: read the documentation before using the generic form of the Requires method in your release code.) This line of code guarantees that if the name parameter does not meet the specified pre-condition, the specified exception will be thrown. Similarly, we have stated a post-condition: namely that when this constructor exits, the class's name field will also not be null, an empty string, or whitespace. In my advanced TDD post, the constructor ended up having a lot more guard clauses in it for other properties of the Category class. Don't worry, we'll come to those soon.

Code Contract Violations

When a pre-condition, post-condition, or invariant condition is violated, an exception is thrown. The exception is the System.Diagnostics.Contracts.ContractException. The catch is, this exception’s access modifier is internal; so you can’t catch this exception directly. This is actually a very good design decision on the part of the RiSE team, even thought it causes headaches for us developers—especially when it comes to unit testing. Programmers should not be able to circumvent contract violations by catching these exceptions and “handling” them. Contracts are guarantees. Pre-conditions guarantee that, given parameters that satisfy the stated pre-conditions, the method can perform its duties. Similarly, post-conditions guarantee to the caller that upon exit from the method, certain conditions will be true. And invariants guarantee that certain conditions hold throughout the lifetime of the object before and after each method call. So while this is a bit of a pain when it comes to unit testing, this was a very good decision.

Code Contracts and Test-Driven Development

As I alluded to in the introduction to this post, there is a debate that’s been going on in Internet land regarding the roles of code contracts and test-driven development and when and how they are used together. I’ve seen many people giving bad advice in regards to these development practices and I wish to argue the case for my opinion in the next few paragraphs.

What, traditionally, has been the purpose of unit tests (especially those unit tests written as part of a test-driven development effort)? Traditionally, they’re written to ensure that a method does what it’s supposed to do. In fact, there’s a whole style of test-driven development known as behavior driven development (BDD). BDD’s main focus is tests that are named after the behavior that the function is performing. BDD tests strive to be as human readable as possible in an effort to be somewhat of a requirements document for the code base. (I’m over simplifying a bit—I urge you to become familiar with it, as the style has many merits over regular TDD.) But no matter the testing style you use, tests are written to verify that: 1) method parameters are checked to ensure successful execution of a method; 2) the method executes successfully and the proper outputs are returned; and 3) that the state of the object is valid when the method has finished executing (not all tests require this last point to be checked). The first point sounds a lot like pre-conditions—and in a sense, that’s exactly what’s being checked. The second point sounds exactly like post-conditions—and it is. The third point, if part of the test, might be an object invariant (I say might, because what’s being tested in the third point may only be true for that particular case and not a true invariant.)

So now the question is, if I use code contracts, do I need to test pre-conditions and post-conditions? Emphatically, I say YES!! You will find many who disagree with me. Let’s examine the two main arguments against writing tests that exercise code contracts.

You Don’t Write Unit Tests that Exercise Debug Asserts—Why Write Tests That Exercise Your Contracts?

First, I would like to say that this is an invalid statement to begin with. Of course you don’t exercise debug asserts. There’s nothing you can do with them in the testing framework. Your test will fail if a debug assert fails because the program aborts (and therefore, your test runner aborts, too)! So that’s just a ridiculous comparison to make. Furthermore, pre-conditions are not debug asserts. I think this argument comes about because there is a Contract.Assert method in Code Contracts. But this method is not used as a pre- or post-condition. The Contract.Assert method is used as a hint to the static analyzer that, at some point in your code, some condition should hold. That’s it. It’s just a hint to the static analyzer—not a contract. These hints are sometimes needed in order to give the static analyzer a little bit of help when it can’t quite figure out what should hold or not.

Testing Code Contracts Pre-Conditions is Akin to Testing the BCL

This argument is almost plausible; but ultimately, it is flawed. First, it is true that Code Contracts are now a part of the .NET base class library. That’s what makes this argument so plausible. However, when you write tests to test your pre-conditions, the goal is not to test that Code Contracts “does the right thing” when a contract is violated. Indeed, that would be silly. It’s 3rd party code that I have no control over, so why test it? No, what I am testing is that I didn’t accidentally mistype the condition that is checked as part of the pre-condition contract!

Seriously, you must write unit tests for your pre-conditions. While adding code contracts to the Category class used in this blog post, I did mistype a pre-condition specification. The specification was supposed to ensure that when adding a subcategory to a category, the category being added as a subcategory is not null and was not the NullCategory. So when I ran my unit tests and two of them failed (again, I had added the contracts after I had already written the majority of the class in this instance using the standard defensive coding practice of guard clauses at method entry), I was surprised. What happened is that I had accidentally used an || instead of an && in the pre-condition (I probably had copied the guard clause condition; pre-conditions are often the opposite of traditional guard clauses—guard clauses check that something isn’t true, pre-conditions check that something is true). So again I say, YES, you must test your pre-conditions to ensure, not that Code Contracts is behaving, but that you didn’t mistype your pre-condition!

I do find, however, that it’s not practical to test your post-conditions, even though the same possibility of mistyping the post-condition exists. This is because 1) it’s really hard to make your method fail a post-condition on purpose, and 2) chances are, if your post-condition is wrong, a ContractException exception will be thrown. Again, this argument is not water tight—but it is difficult to test post-conditions, and therefore I believe, not worth the effort.

I think that these two arguments are the most frequent reasons given for not testing your code contracts; and I think I have demonstrated why these arguments don’t hold water.

Test-Driven Development with Code Contracts

Now that we have that out of the way, I want to share with you how you can perform test-driven development while using code contracts. This did take me quite a bit of time to figure out. So let’s re-introduce unit tests for the constructor as it's currently implemented above.

The first thing we need to take care of is the fact that when a contract is violated, a private ContractException exception is thrown, and since it’s private, it cannot be caught. So how can we test our pre-conditions? Code contracts provides an event on the static Contract class called ContractFailed. You can subscribe to this event to get access to the contract exception that was thrown. You can also flag the exception as handled from within this event. (So apparently, even thought you can’t catch the exception, you can subscribe to this event and effectively handle it there. Why any good developer would do this is beyond me, after all, why use code contracts in the first place, then? But for unit testing, this is just the hook we need for testing our contracts—but this is the only place where you should ever write this code.)

Now if you remember back to our constructor example, I was using the generic form of the Contract.Requires method that allowed me to specify the exception that is thrown. How this works is, upon a contract violation, code contracts will still throw the System.Diagnostics.Contracts.ContractException exception. But there is a class that is emitted as part of the code contracts re-writer that is able to catch this exception. When the exception is caught, the exception’s InnerException property contains an instance of the exception specified for the generic type parameter. This inner exception is then thrown back to the application. (Read the documentation before using the generic version of Contract.Requires.)

Shown below, I have written a class that subscribes to the Contract.ContractFailed event, which is meant to serve as a base class for all test classes that will be testing objects written with code contracts.

using System;
using System.Diagnostics.Contracts;
using Microsoft.VisualStudio.TestTools.UnitTesting;

namespace DDDSportsStore.Domain.Tests
{
    // Probably not the best named class for this purpose...
    // but good enough.
    [TestClass]
    public abstract class UnitTestBase
    {
        private EventHandler<ContractFailedEventArgs> ContractFailedHandler = 
            new EventHandler<ContractFailedEventArgs>((s, e) => e.SetHandled());

        [TestInitialize]
        public void HookContractFailed()
        {
            Contract.ContractFailed += ContractFailedHandler;
        }

        [TestCleanup]
        public void UnhookContractFailed()
        {
            Contract.ContractFailed -= ContractFailedHandler;
        }
    }
}

This class has both a setup and a teardown method. It hooks and unhooks an event handler to handle the Contract.ContractFailed event. In the official documentation, the RiSE team show that you should call e.SetUnwind(). If you call that method, your unit tests will stop running the moment a contract is violated. That’s because that method causes another exception to be thrown. Any exception thrown from the ContractFailed event handler winds up causing the application to terminate—which means no other tests will run because the test runner will be terminated. But in this case, we want the exception to be thrown because it verifies that when we pass invalid parameters to the method under test, that the pre-condition contract was specified correctly, and therefore, the correct exception is thrown. So now you can use your test framework’s method for asserting thrown exceptions and the tests will pass. Let’s look at an example test that tests our Category constructor by passing a null name, an empty string name, and a name consisting entirely of whitespace.

[TestClass]
public CategoryTests : UnitTestBase
{
    private void AssertCannotCreateCategoryWithName(string name)
    {
        ExceptionAssert.Throws<InvalidCategoryNameException>(
            () => new Category(name)
        );
    }

    [TestMethod]
    When_creating_a_category_with_an_invalid_name_then_an_InvalidCategoryNameException_is_thrown()
    {
        AssertCannotCreateCategoryWithName(null);
        AssertCannotCreateCategoryWithName(string.Empty);
        AssertCannotCreateCategoryWithName("\n");
    }
}

If you look back to my previous post, you will see my implementation of the ExceptionAssert class that I created to handle testing for thrown exceptions. I prefer using this utility class to using the ExpectedExceptionAttribute attribute. Pretty much, that's all there is to incorporating unit tests with code that uses code contracts and maintaining the ability to test that you typed your pre-conditions correctly. If you don't want to use the generic form of the Contract.Requires method (and there may be good reasons for you to do so, see the code contracts documentation for details), then you may need to modify how you test your pre-conditions. But the basic elements remain the same. I'll leave that as an exercise for you.

For the remainder of this blog post, I'm going to skip showing unit tests. As, apart from what I showed above, there's nothing different about my unit tests than what I demonstrated in my previous blog post. For the rest of this post, I want to focus on Code Contracts and incorporating more of its features into your classes.

Code Contracts and Inheritance

The great thing about Code Contracts is that you don’t need to redefine them on all of your sub-types. Once you define them on a base class, they’re defined for all sub-types. In this way, using Code Contracts can help ensure that your code follows the Liskov Substitution Principle (LSP). Because code contracts are inherited, all derived types can be used in place of their base types and clients are guaranteed that all pre-conditions, post-conditions, and invariants of the base type will still hold on all derived types.

This does have some implications for derived types however. Derived types are not allowed to define pre-conditions that are stronger than their base types (in fact, doing so would most likely be a direct violation of the LSP to begin with). It is interesting to note, that while weaker pre-conditions should be allowed, they are not. The RiSE team, in their work with Spec#, found that allowing weaker pre-conditions often provided little value but added a large amount of complexity to the analyzer. So in effect, you cannot even add any pre-conditions to derived types. This is even true for interfaces (after all, interfaces are nothing more than pure, abstract classes for which C# has simply provided syntactic sugar (and built-in compiler constraints) in the form of the interface keyword). It should also be noted that if you don’t specify any pre-condition on a method in a base class, then that method is considered to have the weakest of all pre-conditions: true.

These same rules, however, do not apply to post-conditions. You are allowed to specify stronger post-conditions on derived types. This just provides further guarantees for clients that call those methods on derived types compared to their base class method counterparts.

Code Contracts and Abstract Class Methods and Interfaces

Naturally, the question should arise: how can I implement contracts on abstract class methods and interfaces, neither of which are permitted to have method bodies? The answer is to create a special class that overrides the abstract class methods or implements the interface. Code Contracts provides two attributes, one that adorns the abstract class or interface (ContractClassAttribute), and the other that adorns the contract class itself (ContractClassForAttribute).

Keeping Your Contracts DRY

If you find yourself repeating many contracts over and over again in various methods throughout your objects, you can group them together into methods adorned with the ContractAbbreviatorAttribute attribute and call them directly from methods that require the contracts. Let me show you an example. For any Category that is created, it must have a non-null list of subcategories. It’s parent category must also not be null (if a category has no parent, it should have the NullCategory Category.None assigned as its property value). And of course, a category should not have a null, empty string, or whitespace only name after it’s been instantiated. Here’s how I can “group” my contracts together:

public class Category
{
    public static readonly Category None = new NullCategory();

    private string name;
    private Category parentCategory;
    private List<Category> subCategories;

    protected Category()
    {
        subCategories = new List<Category>();
    }

    public Category(string name) : this(name, None) { }

    public Category(string name, Category parent) : this()
    {
        Contract.Requires<InvalidCategoryNameException>(
            !string.IsNullOrWhiteSpace(name)
        );
        Contract.Requires(parent != null);
        EnsureThisCategoryIsValid();

        this.name = SanitizeName(name);
        if (parentCategory == null)
            parentCategory = parent;
        else
            SetParentCategory(parent);
    }

    [ContractAbbreviator]
    private void EnsureThisCategoryIsValid()
    {
        // Obviously, separate calls to Ensures or Requires are ANDed together...
        Contract.Ensures(subCategories != null);
        Contract.Ensures(
            this == None || 
            !(string.IsNullOrWhiteSpace(name) || parentCategory == null)
        );
    }
}

Again, while this example is trivial, if you have a lot of methods with the same pre- and/or post-conditions, this can be a valuable tool in keeping your code contracts code DRY.

Specifying Object Invariants

Code contracts has a way of telling the analyzer the various invariants of your objects. Invariants are conditions that must be met by your object after each public method call. In the Category class, for example, the following invariants are true: a category’s name is not null, a category’s parent is not null, and a category’s list of subcategories is not null. These conditions can be checked by placing them within calls to Contract.Invariant inside of a method adorned with the ContractInvariantMethodAttribute attribute as shown below:

[ContractInvariantMethod]
public void CategoryInvariants()
{
    Contract.Invariant(Name != null);
    Contract.Invariant(Parent != null);
    Contract.Invariant(Subcategories != null);
}

Invariants can be especially useful with automatic properties (properties that don't have explicit backing fields that are retrieved/assigned from the property's getters/setters).

Code Contract Helper Methods

Let's say you have some helper method to help you in determining whether certain conditions hold (either for pre- or post-conditions on a method) due to some complex logic. You don't really want all that complex logic in the Contract.Requires or Contract.Ensures method call. So instead, you'll have something like Contract.Ensures(ThisMethodsResultsAreVaild());. In order to use this method without code contracts emitting an error at compile time, you should mark the method as pure using the PureAttribute attribute. This tells code contracts that this method has no visible side-effects and will remove the compiler error. The effects of the PureAttribute attribute are also inherited by derived classes.

Giving the Analyzer a Helping Hand

Determining the various states that the source code could leave the object in at any particular time is a fairly difficult task. You’ll see this is true when you start to use Code Contracts because it will slow down your build times a bit (static analysis runs as a post-build activity). For this reason, Microsoft does suggest that you only run contract checking for a custom build configuration that you would create in addition to your normal Debug and Release builds (e.g., Checked).

Due to the complexity involved in analyzing the source code, sometimes the static analyzer will ask for your help. It does this by writing informational messages to the Error Output window in Visual Studio. Sometimes it tells you exactly what it’s looking for in the form of suggesting appropriate Contract.Requires or Contract.Ensures statements. Other times, it tells you that it’s assuming one thing or another (and suggests that you specify these assumptions for next time).

Code Contracts has two other static methods on the Contract class called Assume and Assert. These are not pre- or post-conditions or even object invariants. In the case of Assume, you’re informing the static analyzer that it should assume the condition specified for the argument to the method is true at that point in the execution of the code. It is merely a hint to the analyzer. On the other hand, Assert tells the static analyzer that some condition must be true at that point in code execution in order for successful execution to continue. If at runtime (for builds where asserts are left in the code, such as your Checked build confiuration) an assertion is violated, your program will terminate.

Conclusion

I've touched upon many of the features of Microsoft's RiSE Code Contracts in this blog post along with a few code illustrations. If you find Code Contracts interesting and an acceptable way of practicing Design by Contract, I encourage you to check out the Code Contracts website and the corresponding documentation. Below, find the complete Category class re-written to include all Code Contracts. Except for having to hook the ContractFailed event in a base class for all my unit tests in order to test that expected exceptions where thrown, the unit tests did not need to change in any other way, and so I have not repeated them here. Until next time, take care.

using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.Diagnostics.Contracts;
using System.Text.RegularExpressions;

namespace DDDSportsStore.Domain
{
    [DebuggerDisplay("[Name: {Name}]")]
    public partial class Category
    {
        public static readonly Category None = new NullCategory();
        private string name;
        private Category parentCategory;
        private List subCategories;

        protected Category() 
        {
            subCategories = new List();
        }

        public Category(string name) : this(name, None) { }

        private Category(string name, Category parent) : this()
        {
            Contract.Requires<InvalidCategoryNameException>(
                !string.IsNullOrWhiteSpace(name)
            );
            RequiresCategoryIsNotNull(parent);
            EnsureThisCategoryIsValid();

            this.name = SanitizeName(name);

            if (parentCategory == null)
                parentCategory = parent;
            else
                SetParentCategory(parent);
        }

        protected virtual int Id { get; set; }

        public virtual string Name
        {
            get { return name; }
            set 
            {
                RequiresValidName(value);
                name = SanitizeName(value); 
            }
        }

        public virtual Category Parent 
        {
            get { return parentCategory; }
            set 
            {
                RequiresCategoryIsNotNull(value);
                Contract.Assume(parentCategory != null);
                SetParentCategory(value); 
            }
        }

        public IReadOnlyCollection Subcategories 
        {
            get 
            {
                Contract.Ensures(
                    Contract.ForAll(
                        Contract.Result<IReadOnlyCollection<Category>>(), 
                        c => c != null && c != Category.None
                    )
                );
                Contract.Assume(subCategories != null);

                return subCategories; 
            } 
        }

        /// <summary>
        ///     Creates a new <see cref="Category"/> as a subcategory of the
        ///     current instance.
        /// </summary>
        /// <param name="name">The name of the new category.</param>
        /// <exception cref="InvalidOperationException">
        ///     Thrown if the current instance is <see cref="Category.None"/>
        /// </exception>
        /// <exception cref="InvalidCategoryNameException">
        ///     Thrown if the <paramref name="name"/> is <c>null</c>, 
        ///     the empty string, or consists entirely of whitespace.
        /// </exception>
        public virtual Category AddSubcategory(string name)
        {
            RequiresValidName(name);

            Category subCategory = new Category(name, this);
            AddSubcategory(subCategory);
            return subCategory;
        }

        private void AddSubcategory(Category c)
        {
            Contract.Requires<InvalidOperationException>(
                this != Category.None && !(c == None || c == null)
            );
            Contract.Requires<InvalidOperationException>(
                !(
                      Contract.Exists<Category>(
                          subCategories, sc => sc.Name == c.Name
                      )
                 )
            );

            this.subCategories.Add(c);
        }

        public bool Equals(Category other)
        {
            if ((object)other == null)
                return false;

            return this.ToString() == other.ToString();
        }

        private string SanitizeName(string proposedName)
        {
            Contract.Assume(!string.IsNullOrWhiteSpace(proposedName));
            return Regex.Replace(proposedName, @"\s+", " ");
        }

        private void SetParentCategory(Category c)
        {
            RequiresCategoryIsNotNull(c);
            RequiresCategoryIsNotNull(parentCategory);
            Contract.Requires<InvalidOperationException>(
                c == Category.None || !this.HasDescendant(c), 
                "Attempted to set the parent of this category to " +
                "one of this category's descendants."
            );

            parentCategory = c;
            if (parentCategory != None)
                parentCategory.AddSubcategory(this);
        }

        #region System.Object Overrides

        public override bool Equals(object obj)
        {
            if (obj == null)
                return false;

            Category c = obj as Category;
            if ((object)c == null)
                return false;

            return this.ToString() == c.ToString();
        }

        public override int GetHashCode()
        {
            return this.ToString().GetHashCode();
        }

        public override string ToString()
        {
            return Parent == Category.None ?
                Name : string.Concat(Parent.ToString(), "/", Name);
        }

        #endregion

        #region Operator Overrides

        public static bool operator ==(Category a, Category b)
        {
            if (object.ReferenceEquals(a, b))
                return true;

            if ((object)a == null || (object)b == null)
                return false;

            return a.ToString() == b.ToString();
        }

        public static bool operator !=(Category a, Category b)
        {
            return !(a == b);
        }

        #endregion

        #region Code Contracts Helper Methods

        [ContractInvariantMethod]
        private void CategoryInvariants()
        {
            Contract.Invariant(Name != null);
            Contract.Invariant(Parent != null);
            Contract.Invariant(Subcategories != null);
        }

        [Pure]
        private bool HasDescendant(Category c)
        {
            RequiresCategoryIsNotNull(c);

            bool result = false;

            if (this == c)
                result = true;
            else if (c.Parent != None)
                result = this.HasDescendant(c.Parent);

            return result;
        }

        [ContractAbbreviator]
        private void EnsureThisCategoryIsValid()
        {
            Contract.Ensures(subCategories != null);
            Contract.Ensures(this == None || 
               !(string.IsNullOrWhiteSpace(name) || parentCategory == null));
        }

        [ContractAbbreviator]
        private void RequiresValidName(string name)
        {
            Contract.Requires<InvalidCategoryNameException>(
                this == None || !string.IsNullOrWhiteSpace(name)
            );
        }

        [ContractAbbreviator]
        private void RequiresCategoryIsNotNull(Category c)
        {
            Contract.Requires(c != null);
        }

        #endregion
    }
}

Mighty Moose and Contextual (a/k/a Hierarchical) TDD

noreply@blogger.com (Craig S.) — Sun, 02 Mar 2014 03:19:00 +0000

Introduction

In my last few blog posts, I introduced Mighty Moose and advanced TDD using nested, hierarchical context classes. If you have started using Mighty Moose and tried your hand at contextual TDD (that’s my new name for it, it seems to fit), also known as hierarchical testing, you may have noticed a problem.

The Test Runner Behind Mighty Moose

Mighty Moose is compatible with the following testing frameworks:

MS Test
NUnit
xUnit
MbUnit
SimpleTest
MSpec

What may be surprising is that Mighty Moose does not necessarily use the native test runners for these frameworks. Mighty Moose has its own test runner called AutoTest.Net. From what I can tell, it appears that Mighty Moose implements a bunch of Adapters that it uses to interact with the various testing frameworks it supports. The Adapters don’t make use of the native test framework engines themselves. The Adapters contain their own implementation. Unfortunately, it appears the execution of the Adapters may not be 100% compatible with the test framework you’re using to write your tests.

So, imagine my surprise when I refactored all of my tests to use nested, hierarchical classes in order to constrain the boundaries of the various setups I would need (see my last blog post on advanced TDD). Mighty Moose started reporting that all of my abstract base class tests were broken! (The actual error was that AutoTest.Net was unable to instantiate an abstract class. No, really?) I ran my tests in Visual Studio using the CTRL+R, T shortcut. This invokes the native MS Test test runner. I pop on over to the Test Explorer window, and what do I find? All of my tests pass.

On the one hand, having these Adapters are great; you don’t have to learn a different testing framework API in order to use Mighty Moose. On the other hand, my confidence in Mighty Moose is now lower than I would otherwise like because the output is not 100% compatible with the native test runner. How can I be sure that in all instances the tests are actually passing or failing (or even that AutoTest.Net is reporting the right result, for that matter)?

AutoTest.Net is Broken

So obviously, there’s a bug in AutoTest.Net, which is what Mighty Moose uses to run your tests; and it’s a pretty big one. AutoTest.Net recognizes that you have various test classes (a là the TestClassAttribute attribute). And so it tries to instantiate any class decorated with that attribute without checking if it’s valid to instantiate said class. But wait, it gets worse. It finds the nested inner class (which derives from the abstract base classes) and only runs the tests found in the concrete derived class (none of the inherited base class tests run with the derived class).

Is there a way around this? Well, yes, but you should be careful. The way to avoid this problem with Mighty Moose is to not make the base classes abstract. However, this will lead to the base class tests executing for every class which derives from that base class. And this won’t be true just for AutoTest.Net, but also for MS Test. (I don’t know about NUnit and xUnit since I’ve never used them.)

So what, you say? That’s ok, as long as Mighty Moose works. Well, consider this. You have 100 tests in your base class, and 100 tests in a derived class. How many tests will get executed? 300 tests. 100 for the base class, 100 for the derived class’s inherited base class methods, and 100 tests contained in the derived class itself. OK, so you don’t have 100 tests in a single test class. However, in a production system, you may have upwards of 5000 tests. (And that’s just when they’re running once!) So now multiply a good chunk of those tests and pretty soon you’re pushing 15000 tests. (And keep in mind that that's assuming that you're only nesting one level. If you nest two levels deep, now you have an explosion of the possible number of tests that will execute.) It’s wasteful of time and computing resources.

Conclusion

If you have a really small project and don’t mind tests being executed more than once, by all means, go for it. But it’s really not a good of a solution. AutoTest.Net should take into account whether or not a class is abstract and ignore it if it’s marked with the TestClassAttribute attribute. Furthermore, AutoTest.Net should look to see if a test class is a derived class and ensure that the derived class’s base class hierarchy is properly instantiated and that all inherited members are executed as part of the derived class.

Hopefully the authors of AutoTest.Net will fix this bug soon. Until then, if you have a small project, go for it. Otherwise, it’s probably best not to use Mighty Moose. If you really need a continuous test runner, check out NCrunch. I’ve been using it at work and I really like that continuous test runner, too. (Oh, and as far as the cost for NCrunch, while I don’t want to pay for it for personal use at this time, it’s really not that expensive; and if things were different as far as the level of development I do personally, I’d definitely pay for it.)

Advanced Test-Driven Development

noreply@blogger.com (Craig S.) — Wed, 26 Feb 2014 02:29:00 +0000

Introduction

At my current place of employment, I was recently introduced to the “Uncle Bob” series of videos, more properly titled Clean Coders. In episodes 19 through 23, Robert Martin begins a series on advanced test-driven development.

One of the things that was mentioned in that series is about how your tests should be treated no differently than production code. That means that your tests should also follow the SOLID principles: Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation/Separation, and the Dependency Inversion principles (see the videos for clarifications surrounding applying these principles in relation to unit tests, however). Also, another good coding principle is DRY—don’t repeat yourself.

Traditional TDD

In .NET, I use the standard MS Test test framework. I know, it’s not great, and I should use NUnit or xUnit, right? But really, I don’t like NUnit (or xUnit). Actually, MS Test isn’t great either (too many attributes), but I like it better than NUnit or xUnit. Feel free to disagree with me. I'm not writing this blog post to argue about the best testing framework. See Roy Osherove's blog for a more in-depth discussion regarding the merits (or lack thereof) of various testing frameworks. (Hint: he has a very low opinion of MS Test—but that's OK, he's entitled to his opinion.)

Anyway, the point is, the MS Test framework does not support the notion of setup contexts (nor does NUnit or xUnit, for that matter). Yes, yes, there is a TestInitializeAttribute that you can adorn a method with to provide a test class with a setup method (and NUnit’s corresponding SetupAttribute attribute), but that’s not what I’m talking about.

Usually when we create tests, we create one test class for each class under test (CUT). Invariably, one of two things can take place when it comes to common data needed for tests (though, maybe not needed for each test):

Create private test class fields and initialize them in the setup method adorned with the TestInitializeAttribute attribute
Just re-create all test setup information within each test method in the Arrange section of the test

I usually follow number 2, but I was always bothered by it. After all, it violates DRY. I just hate it. But option 1 is no better! You end up instantiating a lot of fields and data for each and every test method in the class, regardless of whether the currently executing test needs all of the data. This can be terribly inefficient, especially if your tests involve creating expensive objects.

So how can we get small setup methods and small tests?

Advanced TDD with Context Classes

The solution to this problem is recognizing that there are various contexts under which your tests are running. Some contexts may be completely separate from others, while other contexts need to use data that also appears in a different context. The real trick is determining how to arrange the contexts so that you don’t violate the DRY principle and are able to promote re-use in order to keep setup methods small, all the while keeping your tests really small. I got the idea for this concept directly from the Clean Coders video series. (Please, if you hate this idea, don’t misconstrue the fact that because I got this idea from the Clean Coders video series that the series must be junk. It’s not. I just might have a bad idea here. I don’t think so; but hey, I’m entitled to my opinion. :) Of course, I’m always interested in feedback and open discussion.)

I first tried this concept out on some code at my place of employment. But of course, I can’t show you that code. So, the rest of this article is going to demonstrate this concept using a class called Category. While this class is really simple, and you may disagree with my implementation, this is not about the Category class implementation. It’s about how you can structure your tests to keep them SOLID, DRY, and focused.

It should be noted that the method outlined here may not work on Visual Studio 2010. It will work with Visual Studio 2012 and 2013, however. If anyone finds that the methods outlined here work on Visual Studio 2010, too, I’ll update this post accordingly.

Introducing the Category Class

In order to demonstrate the concept, I’m going to build up the Category class incrementally, practicing TDD as I go along. So, without further delay, let’s get started.

First, I want to outline some invariants of the Category class:

A category name cannot be null or the empty string and it cannot be a whitespace only string. If any of these conditions are true, throw an InvalidCategoryNameException exception.
A category can have a single parent. The parent cannot be null—the parent property must always return an object.
A category can have sub-categories. You cannot add a null sub-category. Adding a sub-category must not result in a cycle, e.g. A -> B -> C -> A, where the first and last category A are the same exact category object.

As I go along, I’ll introduce other business rules and/or requirements. So, what test should I write first? Well, I think I'll write a test to make sure that I can create a Category.

using System;
using Microsoft.VisualStudio.TestTools.UnitTesting;

namespace DDDSportsStore.Domain.Tests
{
    [TestClass]
    public class CategoryTests
    {
        [TestMethod]
        public void Can_create_a_category()
        {
            Category c = new Category();
        }
    }
}

Now, of course this test won’t compile because I haven't yet written the Category class. So I'm going to go ahead and create that now.

using System;
using System.Collections.Generic;
using System.Linq;

namespace DDDSportsStore.Domain
{
    public class Category
    {
    
    }
}

There, that's all that's needed in order to make the test above pass. If you haven’t guessed, this category class is implementing a product category that you might find as part of an online e-commerce catalog. I’m trying to practice domain-driven design (DDD) with an example used in the Pro ASP.NET MVC4 book published by APress. Enough about DDD; that’s another story and another blog post (or 10).

Now that I have a passing test and I can indeed create a category object, I'm going to get rid of that first test and replace it with a test that ensures that I cannot create a category with a null name. It would be really hard in a blog format to show the incremental building up of the category class in order to satisfy the test (see episode 24 of Clean Coders on the Transformation Priority Premise), so I'm just going to show you the final implementation of this particular constructor that will pass the test.

[TestMethod]
[ExpectedException(typeof(InvalidCategoryNameException))]
public void Cannot_create_a_Category_with_a_null_string_for_a_name()
{
    Category c = new Category(null);
}

Pay no attention to the ExpectedExceptionAttribute attribute. I'll be replacing that soon enough. Just know that that attribute is a real code smell and could be causing your tests to pass when they shouldn't be. OK, with that said, of course this test should also fail because I have no constructor that takes a parameter. I'm going to implement that constructor now.

public class Category
{
    private string name;

    public Category(string name)
    {
        if (name == null)
            throw new InvalidCategoryNameException();

        Name = name;
    }

    public string Name
    {
        get { return name; }
        set { name = value; }
    }
}

Ok, the next part of the first invariant is that the string cannot be empty. I'll write another test to test this invariant.

[TestMethod]
[ExpectedException(typeof(InvalidCategoryNameException))]
public void Cannot_create_a_Category_with_an_empty_string_for_a_name()
{
    Category c = new Category(string.Empty);
}

Again of course, this test fails because in the constructor, I only checked to see if name is null. So now I'll update the constructor to make this test pass.

public Category(string name)
{
    if (string.IsNullOrEmpty(name))
        throw new InvalidCategoryNameException();

    Name = name;
}

There, that should be enough to make the above test pass. The final invariant regarding a category's name is that it cannot consist entirely of white space. The test for this invariant will closely resemble the other two tests. So I think it's time to refactor these tests to remove code duplication and use composable assertions (again, see the Clean Coders videos). The first thing you'll notice about the tests is that I attempt to assign the newly created category to a variable named c. This isn't strictly necessary—I merely need to call the constructor with an invalid category name and the execption should be thrown. So I'll eliminate that duplication in this refactoring. I'll also create a helper method to carry out the assertion. Finally, I'm testing 3 components of a single logical invariant concerning the name of a category. So I could really check all 3 components in a single test and I would not be violating the "single assertion per test" rule. The new tests are shown below.

[TestClass]
public class CategoryTests
{
    [TestMethod]
    public void Cannot_create_a_Category_with_an_invalid_name()
    {
        AssertCannotCreateCategoryWithName(null);
        AssertCannotCreateCategoryWithName(string.Empty);
        AssertCannotCreateCategoryWithName("\n");
    }

    public void AssertCannotCreateCategoryWithName(string name)
    {
        ExceptionAssert.Throws<InvalidCategoryNameException>(
            () => new Category(name)
        );
    }
}

public static class ExceptionAssert
{
    public static void Throws<T>(Action action) where T : Exception
    {
        try
        {
            action();
            Assert.Fail(
                "Expected '{0}' to be thrown but no exception was thrown.",
                typeof(T).FullName
            );
        }
        catch (T)
        {
            return;
        }
        catch (AssertFailedException)
        {
            throw;
        }
        catch (Exception e)
        {
            Assert.Fail("Expected '{0}' to be thrown, but '{1}' was thrown instead.", 
                        typeof(T).FullName,
                        e.GetType().FullName
            );
        }
    }
}

Remember I told you that I'd be taking care of that ExpectedExceptionAttribute attribute. This is one instance where NUnit and xUnit really has something on MS Test (syntactically), namely the Assert.Throws<T>(...) method. I hate the ExpectedExceptionAttribute now because it messes with the Arrange, Act, and Assert pattern of TDD. Plus, it can mask other problems with your code. So instead, I get rid of the attribute and use a custom static class modeled after the Assert and CollectionAssert classes in the standard MS Test test framework. So, in my test above, I added a call to my new assertion method trying to create a category with a whitespace only name. The constructor currently only looks for null and the empty string, so this test will fail. It's a simple matter of updating the guard clause in the constructor to make this test pass:

public Category(string name)
{
    if (string.IsNullOrWhiteSpace(name))
        throw new InvalidCategoryNameException();

    Name = name;
}

That's it. The test above should now pass and I've ensured that the Category class is enforcing all of the invariants on its name. There are a few more tests I need to write before I get to the concept of creating context classes. I'm going to skip the step-by-step, but I will show you the final tests that I created to enforce some of the category's Subcategory property invariants (the ones that I don't enforce will be enforced later, as I continue to develop this class). I additionally included a test that ensures that any whitespace that appears in a category name is replaced with a single space character. I'll also show you the Category class as it stands after having written the tests.

[TestClass]
public class CategoryTests
{
    private string PARENT;
    private Category parent;

    [TestInitialize]
    public void CategoryTestsSetup()
    {
        // It's important to initialize test state here, because if a test 
        // (in-)advertently changes the variable's state, it could affect 
        // other tests.
        PARENT = "Parent";
        parent = new Category(PARENT);
    }

    // ...

    // Our other tests we wrote previously are up above.

    [TestMethod]
    public void
    A_category_name_is_sanitized_to_contain_only_1_space_character_between_words()
    {
        AssertCategoryNameWhitespaceIsCollapsed(
            "A  category  with  extraneous  whitespace", 
            "A category with extraneous whitespace"
        );
        AssertCategoryNameWhitespaceIsCollapsed(
            "A\r\ncategory\twith\vother\fwhitespace characters", 
            "A category with other whitespace characters"
        );
        AssertCategoryNameWhitespaceIsCollapsed(
            "This category name is ok", 
            "This category name is ok"
        );
    }

    private void
    AssertCategoryNameWhitespaceIsCollapsed(string name, string expectedName)
    {
        Assert.AreEqual(new Category(name).Name, expectedName);
    }

    [TestMethod]
    public void A_top_level_category_returns_its_name_when_ToString_is_called()
    {
        Assert.AreEqual(PARENT, parent.ToString());
    }
}

Now for the Category class as it stands now.

public class Category
{
    public static readonly Category None = new NullCategory();
    private string name;
    private List<Category> subCategories;

    protected Category()
    {
        subCategories = new List<Category>();
    }

    public Category(string name) : this()
    {
        if (string.IsNullOrWhiteSpace(name))
            throw new InvalidCategoryNameException();

        this.name = SanitizeName(name);
    }

    public virtual string Name
    {
        get { return name; }
        set { name = SanitizeName(value); }
    }

    public IReadOnlyCollection<Category> Subcategories 
    {
        get { return subCategories.AsReadOnly(); }
    }

    public virtual void AddSubcategory(Category c) 
    {
        if (this == Category.None)
            throw new InvalidOperationException(
                "Unable to add a subcategory to the 'None' category."
            );

        if (c == null || c == Category.None)
            throw new InvalidSubcategoryException();

        if (subCategories.Any(sc => sc.Name == c.Name))
            throw new DuplicateSubcategoryException();

        subCategories.Add(c);
    }

    private string SanitizeName(string proposedName)
    {
        return Regex.Replace(proposedName, @"\s+", " ");
    }

    #region System.Object overrides

    public override string ToString()
    {
        return Name;
    }

    #endregion

    /// <summary>
    /// This class represents an implementation of the Null Object pattern 
    /// (a/k/a Special Case pattern) and is meant to be used anywhere
    /// where you might otherwise return null.
    /// </summary>
    private sealed class NullCategory : Category
    {
        public override Name
        {
            get { return string.Empty; }
            set { }
        }
    }
}

So ordinarily, I would have written two unit tests for each of the invalid subcategory conditions asserted in the tests above; but instead, I chose to use a custom assertion method and perform one logical assert. You can also see that I have two new private member variables in the test class which are initialized before each test. But only two of the three tests need these private members. Now, ordinarily, this isn't all that bad and I wouldn't bother with factoring out a context class. But what if the tests were much more involved in the setups that are needed? For instance, at my place of employment, I recently had 7 tests, 2 of which required the same 20 or 30 lines of setup code, the other 5 of which required at least another 10 common lines of setup code between them. All of this code would have been repeated in the methods requiring the code. Or worse, all 50 or so lines would have been in a single setup method, with all of that setup occurring before each test, even if a particular test didn't require all that was setup.

You can also see more fleshed out versions of the Category class. I also created a nested, private category class that is an implementation of the Null Object (a/k/a Special Case) Pattern to represent the null category. Implementing this pattern allows programmers to not have to check for null all the time before accessing properties and fields of objects. Because it's a nested, private class, it cannot be instantiated by anything except the Category class. This allows the NullCategory to be exposed as a public static field on the Category class as a Singleton.

Now, I have not addressed setting the parent category of a category. By default, a category's parent is set to the Singleton NullCategory. But before I tackle that, I want to override the System.Object.Equals method. And when I override this method, I also need to override the System.Object.GetHashCode method and the equality and inequality operators.

The Equality Context Test Class

My motivation for overriding the Equals method and the (in)equality operators is for easy comparison of two categories in order to determine whether or not they are the same. Also, the implementation I have in mind will prevent two subcategories with the same name being added to the same parent. I think you'll see how I accomplish this very easily without much further explanation, so let's hop to it.

Of course, before I can write any code to implement equality testing, I'll need to write the tests. In order to test equality, I'll need two categories. But I'll only need them for this set of tests. I don't want to drag these categories around for each and every other test I might have surrounding categories. So, I think it's best at this point to create a context class for testing category equality. (Again, this example is very simplistic and contrived, and probably not worthy of this level of breakdown; but keep in mind the real-life scenario I mentioned above with 50 lines of code needed by some of the various tests throughout a single CUT. The benefits are potentially huge: smaller test setups; faster tests; smaller, easier to read, and maintainable tests.)

Ok, so below are the tests for the Category class I've been working with (somewhat abbreviated), showing the new context class. I'll also show you my implementation of the equality method and operators in the abstract category class.

[TestClass]
public abstract class CategoryTests
{
    private string PARENT;
    private Category parent;

    [TestInitialize]
    public void CategoryTestsSetup()
    {
        // It's important to initialize test state here, because if a test 
        // (in-)advertently changes the variable's state, it could affect 
        // other tests.
        PARENT = "Parent";
        parent = new Category(PARENT);
    }

    // ...

    // Our other tests we wrote previously are up above.
    [TestClass]
    public class CategoryEqualityContext : CategoryTests
    {
        Category categoryA;
        Category categoryB;

        [TestInitialize]
        public void CategoryEqualityContextSetup()
        {
            categoryA = new Category("A");
            categoryB = new Category("B");
        }

        // This method was moved from the outer context because ToString is 
        // used in determining equality, so it makes sense to move it to this
        // context.
        [TestMethod]
        public void A_top_level_category_returns_its_name_when_ToString_is_called()
        {
            Assert.AreEqual("A", categoryA.ToString());
        }

        [TestMethod]
        public void
        Can_determine_whether_or_not_two_categories_are_equal_to_one_another()
        {
            Assert.AreEqual(categoryA, categoryA);
            Assert.IsTrue(categoryA.Equals(categoryA));
            Assert.IsTrue(((object)catgeoryA).Equals((object)categoryA));
            Assert.IsTrue(categoryA.Equals(new Category("A")));
        }

        [TestMethod]
        public void
        Can_use_the_equality_operator_to_determine_whether_two_categories_are_equal_to_one_another()
        {
            Category c = new Category("A");
            Assert.IsTrue(c == categoryA);
        }

        [TestMethod]
        public void
        Can_use_the_inequality_operator_to_determine_whether_two_categories_are_not_equal_to_one_another()
        {
            Assert.IsTrue(categoryA != categoryB);
        }
    }
}

So let's go over these tests before we get to the implementation in Category. The way MS Test works with nested classes like this is that the outer class is instantiated first, then the inner class, just like any other nested class structure in C#. But in addition to that, the outer class's method marked with the TestInitializeAttribute attribute is also run prior to the nested class's method marked with the same attribute. If the nested class doesn't define such a method, the outer class's method still runs before each and every test in the inner class. So what does that mean for these tests? Well, in this instance, it means that the PARENT string and parent category are carried along into the CategoryEqualityContext. While in this trivial example this isn't a big deal, this is not ideal in a situation where you have a lot of setups occurring in the outer class which the inner class methods don't need. Actually, we're going to refactor our tests to remove the outer class setups in just a bit. But I wanted to show you this so I could explain how the nested context classes work.

Secondly, notice that I've made the CategoryTests class abstract. This is very important. The CategoryEqualityContext class inherits from the CategoryTests class. This also means that it inherits all the methods of its base class. So, let's assume that the CategoryTests class isn't abstract and follow the flow of execution. The CategoryTests class is marked with the TestClassAttribute attribute, so MS Test looks for all the test methods in that class and executes them. Then MS Test sees a public, nested class called CategoryEqualityContext and finds all of its test methods and executes them. But because the CategoryEqualityContext class inherits from CategoryTests class, the tests in CatgoryTests run again as part of CategoryEqualityContext. Now you can see why it's very important to make the CategoryTests class abstract. The general rule of thumb, then, is the following:

If you have nested context test classes, make all test classes abstract except the inner-most context class; leave that class concrete. This ensures that your tests execute only once.

There is one more caveat to using nested context classes for scoping your test setups; I'll get to that later in this blog post.

OK, now that you know how nested context classes work, I'm going to show you how I implemented equality checking in the Category class to make the above tests pass.

public class Category
{
    // ...
    // All other methods previously shown are ansumed to exist above.

    public bool Equals(Category other)
    {
        if ((object)other == null)
            return false;

        return this.ToString() == other.ToString();
    }

    public override bool Equals(object obj)
    {
        if (obj == null)
            return false;

        Category c = obj as Category;
        if ((object)c == nul)
            return false;

        return this.ToString() == c.ToString();
    }

    public override int GetHashCode()
    {
        return this.ToString().GetHashCode();
    }

    public static bool operator ==(Category a, Category b)
    {
        if (object.ReferenceEquals(a, b))
            return true;

        if ((object)a == null || (object)b == null)
            return false;

        return a.ToString() == b.ToString();
    }

    public static bool operator !=(Categoriy a, Category b)
    {
        return !(a == b);
    }
}

So there's not too much to be said about my implementation above. It pretty much follows the standard suggested implementation. Equality merely consists of checking whether or not 1) the acutal objects are the same object reference, or 2) the ToString method returns the same string. The only thing to note is that I have no concept of a parent category yet. When I finally add the ability to set a parent category, this will change my implementation of ToString.

Even More Nested Context Classes

So now you have an idea of how to use nested context classes in order to organize your test setups. While the simple example above gave you an at a glance view, let's make this a bit more concrete by implementing the rest of the functionality. To do that, let me tell you some other rules surrounding categories. First, you cannot have two subcategories of a single category that have the same name. You cannot add the None category as a subcategory (we already covered that). A category's parent cannot be null, but it can be None, meaning it's a "top-level" category. In order to make checking for duplicate subcategories really quick and easy, we're going to change the implementation of ToString. The implementation I have in mind will afford a couple of benefits:

Allows very quick determination of whether or not a category can be added as a subcategory
Allows very quick determination of whether or not two categories are the same by checking their path
Disallows cycles, e.g. A -> B -> C -> A does not form a cycle.

A note about the cycle point above: we'll have a method that ensures that the new parent isn't already a descendant of the current category. The method that's used is recursive. Technically, if you have extremely many levels of nested categories (e.g. A -> B -> C -> D -> ... etc.), it's possible to blow out the stack. But generally speaking, a product catalog for instance, will usually only have 2 - 5 levels of nesting; and that's being generous on the high-end. I guess a way to avoid a potential StackOverflowException would be to limit the allowable amount of nesting. But given the general use-case for this object—and mostly because this is just an example for this blog article and not something I'd use in production code—I'm not inclined to do so. I'll leave it to you as an exercise. Also, my current implementation of AddSubcategory will need to change. We'll also add a new constructor to the class.

Again, even though I told you what I'm going to implement in the class, all of the implementation was based on the tests that I wrote. So here are the new (and final) set of tests.

[TestClass]
public class CategoryTests
{
    // ...
    // All the other tests in the outer context are above.
    // The original setup method was moved to another nested 
    // context to be shown below, along with the test that
    // required the setups.

    [TestClass]
    public abstract class CategoryEqualityContext : CategoryTests
    {
        // ...
        // Nothing has changed in this test class from above.
    }

    [TestClass]
    public abstract class ParentCategoryContext : CategoryTests
    {
        // These variables and the setup method were moved from
        // the outer CategoryTests context class
        private string PARENT;
        private Category parent;

        [TestInitialize]
        public void ParentCategoryContextSetup()
        {
            PARENT = "Parent";
            parent = new Category(PARENT);
        }

        [TestMethod]
        public void Can_add_a_subcategory_to_a_category()
        {
            parent.AddSubcategory("subcategory");
            Assert.AreEqual(1, parent.Subcategories.Count);
        }

        [TestMethod]
        public void Cannot_add_a_duplicate_subcategory_to_a_category()
        {
            parent.AddSubcategory("subcategory");
            ExceptionAssert.Throws<DuplicateSubcategoryException>(
                () => parent.AddSubcategory("subcategory")
            );
        }

        [TestMethod]
        public void A_top_level_category_returns_its_name_when_ToString_is_called()
        {
            Assert.AreEqual(PARENT, parent.ToString());
        }

        [TestClass]
        public class ChildCategoryContext : ParentCategoryContext
        {
            private string CHILD;
            privte Category child;

            [TestInitialize]
            public void ChildCategoryContextSetup()
            {
                CHILD = "Child";
                child = parent.AddSubcategory(CHILD);
            }
    
            [TestMethod]
            public void
            A_subcategory_returns_its_parents_name_with_a_path_separator_and_its_own_name_when_ToString_is_called()
            {
                Assert.IsTrue(string.Concat(PARENT, "/", CHILD) == child.ToString(), 
                    string.Format("Expected '{0}/{1}' but got '{2}'", PARENT, CHILD, child.ToString()
                );
            }

            [TestMethod]
            public void
            Cannot_set_category_parent_if_new_parent_is_a_descendant_of_the_category()
            {
                Category grandchild = child.AddSubcategory("Grandchild");

                // Attempt parent/child/grandchild/parent where 'parent' 
                // at both the head and tail of the list are the same object.
                ExceptionAssert.Throws<invalidoperationexception>(() => parent.Parent = grandchild);
            }
        }
    }
}

After implementing the code that ought to make these tests pass, one of the tests above will actually fail. Can you spot which test will fail? Don't try too long to find it. It's really subtle, and is one of a small list of cons when using this style of testing. The test that will fail is A_top_level_category_returns_its_name_when_ToString_is_called(). But why should that fail? It looks just fine. Again, it's really subtle. The good news is that the test fails and doesn't produce a false positive (e.g. a passing test that should fail). Remember the rule I stated above concerning derived test classes. The most derived test class should be concrete while all lesser derived test classes and the base class must be abstract. In the concrete test class in the ChildCategoryContextSetup() method, I call parent.AddSubcategory(CHILD);. So a new subcategory is added to the parent category. So the parent category now contains 1 subcategory (because the setup runs prior to any tests executing). So now when I execute the A_top_level_category_return_its_name_when_ToString_is_called(), an additional subcategory is added to the parent category (for a total of 2 subcategories) and the assertion fails. There are two ways to fix this:

Move the test to the ChildCategoryContext class. I don't like this option because to me, it seems like since it's only using the parent category, it should reside in the ParentCategoryContext class.
Obtain the count of subcategories of the parent category prior to adding a subcategory. Then assert that the count of subcategories is equal to one plus the count obtained before acting on the CUT. To me, this is a much better option. The test is still straight-forward; the class resides where you'd expect it to reside; the test is less fragile.

I think I'll go with option number two and re-write the test as follows:

[TestMethod]
public void A_top_level_category_returns_its_name_when_ToString_is_called()
{
    int numSubcategories = parent.subCategories.Count;
    parent.AddSubcategory("subcategory");
    Assert.AreEqual(numSubcategories + 1, parent.Subcategories.Count);
}

With that done, that's it for the tests. Now for the implementation in the Category class.

public class Category
{
    // ...
    // All the old fields are above

    private Category parentCategory;

    // The constructors are have changed a bit.

    protected Category()
    {
        subCategories = new List<Category>();
    }

    public Category(string name) : this(name, None) { }

    // This constructor is private so that we can enforce not allowing
    // cycles to occur in parent/child/grandchild relationships.
    private Category(string name, Category parent) : this()
    {
        if (string.IsNullOrWhiteSpace(name))
            throw new InvalidCategoryNameException();
        
        // You shouldn't call virtual properties and methods from your constructors,
        // so use the fields directly.
        this.name = SanitizeName(name);

        if (parentCategory == null)
            parentCategory = parent;
        else // Use SetParentCategory(...) to prevent cyclic relationships.
            SetParentCategory(parent);
    }

    // ...
    // The other properties listed before remain the same.

    public virtual Category Parent
    {
        get { return parentCategory; }
        set 
        {
            // Since on creation parentCategory is never left null, 
            // always call this method when setting the parent.
            SetParentCategory(value);
        }
    }

    // The original implementation of AddSubcategory was made private so
    // that external users can no longer pass in an arbitrary category.
    // This prevents cycles in the hierarchy.
    // 
    // The new public method is now a sort of factory method that creates
    // a new category, adding it as a subcategory to the current instance,
    // and returning the newly creatd category.

    private void AddSubcategory(Category c)
    {
        // ...
        // The original method stays the same...it's just private now.
    }

    /// <summary>
    /// Creates a new Category as a subcategory of the current instance.
    /// </summary>
    /// <param name="name">The name of the new subcategory.</param>
    /// <exception cref="InvalidOperationException">
    ///     Thrown if the current instance is <see cref="Category.None"/>.
    /// </exception>
    /// <exception cref="InvalidCategoryNameException">
    ///     Thrown if the <paramref name="name"/> is <c>null</c>,
    ///     the empty string, or consists entirely of whitespace.
    /// </exception>
    public virtual Category AddSubcategory(string name)
    {
        if (this == None)
            throw new InvalidOperationException();
        
        Category subcategory = new Category(name, this);
        AddSubcategory(subcategory);
        return subcategory;
    }

    private void SetParentCategory(Category c)
    {
        if (c != Category.None && this.HasDescendant(c))
            throw new InvalidOperationException();

        parentCategory = c;
        if (parentCategory == Category.None)
            parentCategory.AddSubcategory(this);
    }

    // This method determines whether or not the new parent passed to
    // SetParentCategory is a descendant of the category on which
    // SetParentCategory was called. If so, this method returns true.
    // This prevents cycles in the hierarchy.
    // Again, limiting hierarchy depth can prevent possible stack overflows
    // due to the recursive nature of this function.
    private bool HasDescendant(Category c)
    {
        bool result = false;

        if (this == c)
            result = true;
        else if (c.Parent != Category.None)
            result = this.HasDescendant(c.Parent);

        return result;
    }

    // The implementation of this method changed. Instead of simply returning
    // the name of the category, it returns the category's path from the root:
    // e.g. A/B/C, or Parent/Child/Grandchild.
    public override string ToString()
    {
        return Parent == Category.None ?
            Name : string.Concat(Parent.ToString(), "/", Name);
    }
}

There you go, that wraps up all of the code for the Category class. Let's just take a few seconds to review it. We finally added a Parent property. In addition, we added a private constructor that creates a new category and sets its parent. This constructor is private so that I have control over preventing cycles in the hierarchy. The original constructor that takes a category name defers to this new constructor, setting the parent category to Category.None. We made the original implementation of AddSubcategory private. The original implementation allowed you to pass in any Category instance, which could allow cycles to occur. So a new method was added that acts as a Factory Method, adding the newly created category as a subcategory of the instance on which it was called and returning the newly created subcategory. The SetParentCategory method is also interesting. It checks that if the category passed into it is not Category.None, then that the category is also not a descendant of the current instance—again, preventing cycles in the hierarchy. Finally, the ToString implementation changed to return the full path of the category from the root of its hierarchy, e.g. Parent/Child/Grandchild.

Conclusion

Again, the Category class is fairly small. Having said that, this ended up being a very long blog article. But I think that because of its relative simplicity, it made a good example of how using nested test classes to provide context boundaries for test setup methods can help you keep your setup methods small. Using context classes and setup methods, and keeping your setup methods small promotes the following benefits:

Small setups: Smaller setups mean that less data is being instantiated and configured; and only the data required for the tests in the current context is setup. This has additional benefits:
- Faster execution times (OK, this could be anywhere from negligible to very noticeable)
- Less chance for contamination to occur between tests, e.g. mutated state affecting downstream tests (though with the caveat seen earlier in this post)
Using setup methods allows you to keep your tests DRY
Using context classes in addition to setup methods keeps your tests small and easy to read
Small tests are focused, and usually adhere to the SRP. This means your tests are:
- easy to maintain
- flexible (read, not fragile)
By going one step further and using composable assertions, you make your tests even more understandable, easier to maintain, and less fragile.

There is a corresponding list of cons when it comes to using this style of testing, so to be fair, I'll list out the ones that I can immediately see.

Deep nested classes and the indenting could be annoying
Tests might be hard to find (heck, there's always CTRL+F)
If you're not careful with your assumptions, derived class setups can interfere with base class tests
- This is why it's even more important to not just start writing your tests in this style, but after you've written a few and refactored a bit, you can be more confident about the arrangement of your contexts.
You have to remember to mark all base-class tests abstract and leave the inner-most class concrete.
Not all test runners support abstract base classes (AutoTest.Net for one)

I'm sure you might be able to think of some other pros or cons. Hopefully, though, you'll agree that the benefits listed above may be worth the little bit of extra effort. Before leaving you, I want to touch a little more on the effort that went into making these tests hierarchical.

The effort to make these hierarchical test classes was very small. Granted, this example class is not that complex and not that large. At my current place of employment, I had already used this concept. It did take me a bit of time. But that was the first time ever that I attempted this. This example in this article was the second time I attempted this, and it went much much faster. Why? Because I now know what to look for. There are a few things I want you to keep in mind if you want to try this style of testing:

Don't attempt to start creating context test classes right off the bat. You will most likely fail.
As Robert Martin says, treat your test code as you would your production code.
- This means that you will refactor your tests as you go along in your development effort.
- It's during this refactoring that you will begin to see patterns in usage in the data required for your tests.
- Begin refactoring by simply extracting methods.
Once you begin to see common groupings of functionality, e.g. the same methods being called from various tests or the same data needed by a group of tests, and what not, that's when the creation of context classes will payoff.
Keep these other thoughts in mind when determining the contexts you may need:
- If tests require the same setup, they belong in a single test class
- If tests require the same setup as other tests, and also need a few more things (say, more than two..otherwise, just arrange the items in your tests), consider placing them in a nested context class. Remember to make all base classes abstract and the inner-most derived class concrete.
- If tests require the same setup as other tests, but have additional needed setups different from another nested context classes, create a sibling context class.

I just want to take a minute and explain the last bullet point about sibling contexts. The last point is talking about the same situation we saw even in the small example presented in this post. We had a CategoryTests class that had two nested, sibling context classes: the first nested sibling context class, CategoryEqualityContext required additional setup that CategoryTests did not provide; the second nested sibling context class, ParentCategoryContext, also shared the same setup as CategoryTests but needed additional, yet, different setup than CategoryEqualityContext. Furthermore, the ParentCategoryContext contained yet another nested context class within which required the setups of both CategoryTests and ParentCategoryTest plus additional setup.

Finally, we've come to the end of this very long blog post. I hope that you enjoyed it and that you learned something. If you have a question, feel free to drop me a line and I'll try to get back to you.

Below, find the full, uninterrupted code of the Category class and its corresponding test class(es). Until next time, take care.

using System;
using System.Collections.Generic;
using System.Diagnostices;
using System.Linq;
using System.Text.RegularExpressions;

namespace DDDSportsStore.Domain
{
    [DebuggerDisplay("[Name: {Name}]")]
    public class Category
    {
        private static readonly Category None = new NullCategory();

        private string name;
        private Category parentCategory;
        private List<Category> subCategories;

        protected Category()
        {
            subCategories = new List<Category>();
        }

        public Category(string name) : this(name, Category.None) { }

        private Category(string name Category parent) : this()
        {
            if (string.IsNullOrWhiteSpace(name))
               throw new InvalidCategoryNameException();

            this.name = SanitizeName(name);
            if (parentCategory == null)
                parentCategory = parent;
            else
                SetParentCategory(parent);
        }

        public virtual string Name
        {
            get { return name; }
            set { name = SanitizeName(value); }
        }

        private string SanitizeName(string proposedName)
        {
            return Regex.Replace(proposedName, @"\s+", " ");
        }

        public virtual Category Parent
        {
            get { return parentCategory; }
            set { SetParentCategory(value); }
        }

        private void SetParentCategory(Category c)
        {
            if (c != Category.None && this.HasDescendant(c))
                throw new InvalidOperationException();

            parentCategory = c;
            if (parentCategory == Category.None)
                parentCategory.AddSubcategory(this);
        }

        private bool HasDescendant(Category c)
        {
            bool result = false;

            if (this == c)
                result = true;
            else if (c.Parent != Category.None)
                result = this.HasDescendant(c.Parent);

            return result;
        }

        public IReadOnlyCollection<Category> Subcategories
        {
            get { return subCategories.AsReadOnly(); }
        }

        /// <summary>
        /// Creates a new Category as a subcategory of the current instance.
        /// </summary>
        /// <param name="name">The name of the new subcategory.</param>
        /// <exception cref="InvalidOperationException">
        ///     Thrown if the current instance is <see cref="Category.None"/>.
        /// </exception>
        /// <exception cref="InvalidCategoryNameException">
        ///     Thrown if the <paramref name="name"/> is <c>null</c>,
        ///     the empty string, or consists entirely of whitespace.
        /// </exception>
        public virtual Category AddSubcategory(string name)
        {
            if (this == None)
                throw new InvalidOperationException();
        
            Category subcategory = new Category(name, this);
            AddSubcategory(subcategory);
            return subcategory;
        }

        private void AddSubcategory(Category c) 
        {
            if (this == Category.None)
                throw new InvalidOperationException(
                    "Unable to add a subcategory to the 'None' category."
                 );

            if (c == null || c == Category.None)
                throw new InvalidSubcategoryException();

            if (subCategories.Any(sc => sc.Name == c.Name))
                throw new DuplicateSubcategoryException();

            subCategories.Add(c);
        }

        public bool Equals(Category other)
        {
            if ((object)other == null)
                return false;

            return this.ToString() == other.ToString();
        }


        #region System.Object overrides

        public override bool Equals(object obj)
        {
            if (obj == null)
                return false;

            Category c = obj as Category;
            if ((object)c == nul)
                return false;

            return this.ToString() == c.ToString();
        }

        public override int GetHashCode()
        {
            return this.ToString().GetHashCode();
        }

        public override string ToString()
        {
            return Parent == None ?
                Name : string.Concat(Parent.ToString(), "/", Name);
        }

        #endregion

        #region Operator Overrides

        public static bool operator ==(Category a, Category b)
        {
            if (object.ReferenceEquals(a, b))
                return true;

            if ((object)a == null || (object)b == null)
                return false;

            return a.ToString() == b.ToString();
        }

        public static bool operator !=(Categoriy a, Category b)
        {
            return !(a == b);
        }

        #endregion

        #region NullCategory

        /// <summary>
        /// This class reperesents an implementation of the Null Object
        /// pattern (a/k/a Special Case pattern) and is meant to be used
        /// anywhere where you might otherwise return null.
        /// </summary>
        private sealed class NullCategory : Category
        {
            public override Name
            {
                get { return string.Empty; }
                set { }
            }
        }
    }

    #endregion
}

using Microsoft.VisualStudio.TestTools.UnitTesting;

namespace DDDSportsStore.Domain.Tests
{
    [TestClass]
    public class CategoryTests
    {
        [TestMethod]
        public void Cannot_create_a_Category_with_an_invalid_name()
        {
            AssertCannotCreateCategoryWithName(null);
            AssertCannotCreateCategoryWithName(string.Empty);
            AssertCannotCreateCategoryWithName("\n");
        }

        [TestMethod]
        public void
        A_category_name_is_sanitized_to_contain_only_1_contiguous_whitespace_character_between_words()
        {
            AssertCategoryNameWhitespaceIsCollapsed(
                "A  category  with  extraneous  whitespace",
                "A category with extraneous whitespace"
            );
            AssertCategoryNameWhitespaceIsCollapsed(
                "A\r\ncategory\twith\vother\fwhitespace characters",
                "A category with other whitespace characters"
            );
            AssertCategoryNameWhitespaceIsCollapsed(
                "This category name is ok", 
                "This category name is ok"
            );
        }

        private void AssertCannotCreateCategoryWithName(string name)
        {
            ExceptionAssert.Throws<InvalidCategoryNameException>(
                () => new Category(name)
            );
        }

        private void
        AssertCategoryNameWhitespaceIsCollapsed(string name, string expectedName)
        {
            Assert.AreEqual(new Category(name).Name, expectedName);
        }

        public class CategoryEqualityContext : CategoryTests
        {
            Category categoryA;
            Category categoryB;

            [TestInitialize]
            public void CategoryEqualityContextSetup()
            {
                categoryA = new Category("A");
                categoryB = new Category("B");
            }

            [TestMethod]
            public void
            A_top_level_category_returns_its_name_when_ToString_is_called()
            {
                Assert.AreEqual("A", categoryA.ToString());
            }

            [TestMethod]
            public void
            Can_determine_whether_or_not_two_categories_are_equal_to_one_another()
            {
                Assert.AreEqual(categoryA, categoryA);
                Assert.IsTrue(categoryA.Equals(categoryA));
                Assert.IsTrue(((object)catgeoryA).Equals((object)categoryA));
                Assert.IsTrue(categoryA.Equals(new Category("A")));
            }

            [TestMethod]
            public void
            Can_use_the_equality_operator_to_determine_whether_two_categories_are_equal_to_one_another()
            {
                Category c = new Category("A");
                Assert.IsTrue(c == categoryA);
            }

            [TestMethod]
            public void
            Can_use_the_inequality_operator_to_determine_whether_two_categories_are_not_equal_to_one_another()
            {
                Assert.IsTrue(categoryA != categoryB);
            }
        }

        [TestClass]
        public class ParentCategoryContext : CategoryTests
        {
            private string PARENT;
            private Category parent;

            [TestInitialize]
            public void ParentCategoryContextSetup()
            {
                PARENT = "Parent";
                parent = new Category(PARENT);
            }

            [TestMethod]
            public void Can_add_a_subcategory_to_a_category()
            {
                int numSubcategories = parent.subCategories.Count;
                parent.AddSubcategory("subcategory");
                Assert.AreEqual(numSubcategories + 1, parent.Subcategories.Count);
            }

            [TestMethod]
            public void Cannot_add_a_duplicate_subcategory_to_a_category()
            {
                parent.AddSubcategory("subcategory");
                ExceptionAssert.Throws<DuplicateSubcategoryException>(
                    () => parent.AddSubcategory("subcategory")
                );
            }

            [TestClass]
            public class ChildCategoryContext : ParentCategoryContext
            {
                private string CHILD;
                privte Category child;

                [TestInitialize]
                public void ChildCategoryContextSetup()
                {
                    CHILD = "Child";
                    child = parent.AddSubcategory(CHILD);
                }
    
                [TestMethod]
                public void
                A_subcategory_returns_its_parents_name_with_a_path_separator_and_its_own_name_when_ToString_is_called()
                {
                    Assert.IsTrue(string.Concat(PARENT, "/", CHILD) == child.ToString(),
                        string.Format("Expected '{0}/{1}' but got '{2}'", PARENT, CHILD, child.ToString());
                }

                [TestMethod]
                public void
                Cannot_set_category_parent_if_new_parent_is_a_descendant_of_the_category()
                {
                    Category grandchild = child.AddSubcategory("Grandchild");
                    ExceptionAssert.Throws<Invalidoperationexception>(
                        () => parent.Parent = grandchild
                    );
                }
            }
        }
    }

    public static class ExceptionAssert
    {
        public static void Throws<T>(Action act) where T : Exception
        {
            try
            {
                act();
                Assert.Fail("Expected '{0}' to be thrown but no exception was thrown.");
            }
            catch (T)
            {
                return;
            }
            catch (AssertFailedException)
            {
                throw;
            }
            catch (Exception e)
            {
                Assert.Fail(
                    "Expected '{0}' to be thrown, but '{1}' was thrown instead.",
                    typeof(T).FullName,
                    e.GetType().FullName
                );
            }
        }
    }
}

Mighty Moose a/k/a ContinuousTests

noreply@blogger.com (Craig S.) — Sat, 01 Feb 2014 23:45:00 +0000

Introduction

At my current place of employment, I was introduced to NCrunch, a continuous testing solution for .NET and Visual Studio. It’s a great tool that I really enjoy using at work. However, for at home use, I can’t justify paying their asking price for a personal license. Don’t get me wrong, I really love the tool, and if I were doing some serious development on my own (i.e. creating products for sale as a side job), I’d probably pay for it, because it’s fast and shows exactly where an exception occurred or a test failed.

So I really like this concept of continuous testing and went on an Internet search to see what was available out there for free. I wanted something that would run in Visual Studio 2012/2013. A lot of the “free” tools use external test runners which display their output in either the browser (as an XML/HTML page) or in a console window. I don’t like those tools because they interrupt my context, having to switch between Visual Studio and, say, a console window. Plus, then I have to go digging for the file and line number when a test fails.

Enter Mighty Moose a/k/a Continuous Tests

During my search, I found Mighty Moose a/k/a ContinuousTests, by Greg Young. Mighty Moose has a slightly different philosophy about continuous testing. Instead of a code coverage margin in Visual Studio, they have a risk margin. The risk margin shows a colored circle next to a method under test with a number inside. The number inside tells you how many tests are covering the method. The color: red, green, or yellow, indicates the risk of changing that method.

How is risk calculated? It’s based on how close the method was called from the test. According to Greg, while code coverage tells you whether or not the code was executed by a test, that information alone is not enough to classify how risky it is to change the code. What if the code that’s “covered” was called from a method 10 frames down the call stack? By changing that code, you could be affecting not just the method under test, but all 8 other methods in the call stack.

In addition to the risk margin, Mighty Moose contains graph “overlay” graphics (for those of us who can’t afford Visual Studio Ultimate ;) ) that show the call graph of all methods called during the test. This can help you gauge “how far away” a method was invoked from the test, and in general, just help you see the entire call graph, which in itself, could be enlightening.

Getting Mighty Moose to Work with Visual Studio 2013

Mighty Moose is currently at version 1.0.47. It officially only supports Visual Studio 2008, 2010, and 2012. However, there’s an excellent question over on Stack Overflow that I contributed to which shows you how to get Mighty Moose to work with Visual Studio 2013.

Cool Blog Post Titled "What is a Full Stack Developer?"

noreply@blogger.com (Craig S.) — Thu, 14 Nov 2013 22:52:00 +0000

Hey everyone. I just wanted to share a link to a really cool blog post titled What is a Full Stack Developer?. Hope you enjoy the post.

AllMargins 2012 v2.8.x Releases

noreply@blogger.com (Craig S.) — Thu, 24 Oct 2013 23:54:00 +0000

On 1 September 2013 I released version 2.8 of the AllMargins 2012 Visual Studio extension. Since that release, there have been two additional "dot" releases. Briefly, here's what v2.8.x has to offer:

Visual Studio 2013 RC and RTM support
All the registry value names for the extension's settings have been renamed to prevent naming conflicts with the Productivity Power Tools for Visual Studio 2012 and beyond (more on that below)
Fixed the registry value name for method separator line color
Fixed the StructureAdornment extension so that method separator lines are drawn using the specified color
Added C/C++ union support

Extension Option Registry Value Name Clashes

David Pugh (MSFT) ported a lot (but not all) of the functionality of the original AllMargins extension into the Productivity Power Tools for Visual Studio 2012. The extension option registry value names were left the same. So, when I re-released the AllMargins extension as AllMargins2012, the two extensions would step over each other in terms of their settings for the common extensions. Starting with v2.8, the registry value names have changed to prevent this. As a result, those who installed v2.7 and subsequently customized the extension options by editing the registry, upon installing v2.8, will see that the extension is using the default values for all settings—it appears as though your customizations were changed. They are not. They are still present in the registry. However, new settings are now used by the AllMargins 2012 extension. You need only copy the setting value from the v2.7 registry value to the new v2.8 registry value. I apologize for the inconvenience.

For more details about what the various registry settings are, and their old and new names, see the description tab for the extension at the Visual Studio Gallery.

What to expect in the next major release

Many have spoken, including myself, about what you would like to see in the next major release. Work is underway; here is a quick rundown of what to expect (of course, this is subject to change—nothing is set in stone unless otherwise noted):

The ability to set the extension's options from the Visual Studio Tools|Options dialog. This is a top priority, non-negotiable item for the next major release. I have been wanting this very feature myself since David Pugh originally wrote this extension. Now that I'm maintaining this code base, this task falls on me.
The ability to specify the line widths displayed in the editor for the StructureAdornment extension
Add an option to show/hide the StructureMargin preview tool tip

The items above are what I can reasonably expect to fit into the next major release, though only the first item is guaranteed to make it through. Whatever doesn't make it through will be in a follow-up release. One item that is a planned feature for a future release is the availability to select a color theme for the StructureMargin and StructureAdornment extensions. As many have noted, and I agree, the "default" colors don't work well with Visual Studio 2012's dark theme. In addition, I plan on changing the default color for the class structure adornment from black to some other color, because with the Visual Studio light theme the black line can cause exclamation points to appear to not be present in C# and C/C++ preprocessor statements (e.g. #define !SOME_PREPROCESSOR_VAR), as one user pointed out to me. Black was the original color used by David Pugh—but due to this potential problem, it's best if this color is changed.

If there are any other features you'd like to see, please feel free to leave a comment here on my blog or on the Q AND A tab at Visual Studio Gallery. Thanks again for all of your comments, feedback, suggestions, and ratings!

Announcing the Release of AllMargins for Visual Studio 2012

noreply@blogger.com (Craig S.) — Sun, 20 Jan 2013 03:25:00 +0000

In August of last year, I wrote about upgrading Visual Studio 2010 extensions so that they will work with Visual Studio 2012. In particular, I discussed upgrading the AllMargins Visual Studio extension, which was quite popular.

For some time now, David Pugh of Microsoft has pulled this extension off of Visual Studio Gallery. It is only available if you happened to have downloaded it and saved it to your hard drive or have downloaded the source code (which you can find the link to in the article I wrote back in August). The problem with the source code is that it's a few versions behind the last release that was available on Visual Studio Gallery and contains a few bugs and is missing support for things like C#'s class initializer syntax.

The extension was pulled because David ported most of the functionality into the Visual Studio Productivity Power Tools. However, I'm not a big fan of the particular implementation of the enhanced scrollbar in VSPPT and prefer the AllMargins scrollbar instead.

Today, I'm announcing general availability once again of the AllMargins 2012 extension on Visual Studio Gallery. I modified the available source code, bringing it up to parity with version 2.6, the last available release on Visual Studio Gallery. In addition, I modified the extension so that it will install in Visual Studio 2012. The extension is now at version 2.7.

Thanks to David Pugh at Microsoft for giving the Visual Studio community this wonderful extension and releasing the source code for it a while back!

As I have time, I hope to make a few additions to the extension. Some planned enhancements include providing the ability to change various colors used for drawing the lines in code files delineating various code blocks or for drawing various markers in the overview margin (e.g. drawing a mark for all occurrences in a document of a word under the cursor in the overview margin) right from the Visual Studio Options dialog.

A few notes about AllMargins 2012. First, because the original extension is linked to David Pugh's Windows Live ID, I had to change the identifier of the extension. (This is good, afterall, you wouldn't want Microsoft to allow people to hijack author's extensions possibly replacing them with malicious code, now would you?!) Since the ID, well, identifies the extension, it's essentially a different extension. So I renamed it AllMargins 2012 while I was at it. What this means is that if you want to use this extension in Visual Studio 2010, you must uninstall David Pugh's original AllMargins extension before installing this extension. I don't know what would happen if you have both installed (Double overview scrollbars? Crash Visual Studio?)

I hope that you will continue to find this extension as useful as I have! The Read Me for the top-level AllMargins 2012 extension is presented below.

AllMargins 2012

Introduction:
    This is a compilation of the OverviewMargin and several other extensions that use the OverviewMargin. The OverviewMargin shows
    a margin on the right side of the editor that logically maps to the entire file (similar the the vertical scroll bar). Unlike
    the scroll bar, it maps to the entire file and can contain other margins that provide more information about the file.


Included extensions:
        CaretMargin
        ErrorsToMarks
        MarkersToMarks
        OverviewMarginImpl
        StructureAdornment
        StructureMargin 

        BlockTagger         The definition of an API to get the structure of a code file.
        BlockTaggerImpl     An implementation of the BlockTaggerAPI for C/C# and VB files.

        OverviewMargin      The definition of an API for creating margins that map to the entire file.

        SettingsStore       The definition of an API to load and save editor options across sessions.
        SettingsStoreImpl   An implementation of the SettingStore API that uses IVsSettingsStore to access the system registry.

Usage:
    See other extensions.

Options:
    None.

Notes:

~~The full source for this extension is at http://code.msdn.microsoft.com/OverviewMargin/Release/ProjectReleases.aspx?ReleaseId=3957~~

The source code is not yet available for download.

History:
v1.0 David Pugh 2/26/2010
Initial release
V1.1 David Pugh 3/4/2010
Updated included extensions.
V1.2 David Pugh 4/19/2010
Updated included extensions.
V1.3 David Pugh 4/20/2010
Updated included extensions.
V1.4 David Pugh 4/22/2010
Updated included extensions.
V1.5 David Pugh 4/27/2010
Updated included extensions.
V1.6 David Pugh 4/28/2010
Updated included extensions to fix VB parser error.
V1.7 David Pugh 4/28/2010
Updated version number to work around install issue.
V1.8 David Pugh 4/28/2010
More VB parse fixes (Public, REM, Interface, Structure).
V1.9 David Pugh 4/28/2010
Updated CaretMargin, VB, C# and C parsers.
V2.0 David Pugh 5/03/2010
Bumped version number to fix installation problem.
V2.1 David Pugh 6/10/2010
Updated OverviewMargin, BlockTagger, StructureAdornment & StructureMargin.
Changed namespaces and DLL names to Microsoft.VisualStudio.Extensions.....
V2.2 David Pugh 6/29/2010
Updated StructureAdornment.
V2.3 David Pugh 6/30/2010
Picked up fix for VB parser, tweaks for structure adornment & margin.
V2.4 David Pugh 7/08/2010
Updated StructureAdornment.
V2.5 David Pugh 7/12/2010
Updated included BlockTaggerImpl to handle C/C# array initializers.
V2.6 David Pugh 7/31/2010
Updated included CaretMargin to fix problem with margin not updating correctly.
Updated included OverviewMarginImpl to fix scrollbar mapping problem.
V2.7 Craig E. Shea 1/16/2013
Added Visual Studio 2012 support.
Removed the attribute MaxVersion="4.0" on the SupportedFrameworkRuntimeEdition element.
Changed the author and description to indicate who is now responsible for the extension and that it is a re-release of a previously available extension.

Generics and Implicit Conversion Operators Create an Identity Crisis

noreply@blogger.com (Craig S.) — Sat, 25 Aug 2012 03:53:00 +0000

I keep running into problems with my Unit Tests for a project I'm working on at work, in particular, when I execute Assert.AreEqual(expected, actual).

Some Background Information

Currently, I'm working on some software that will integrate an accounting system with some online banking web services. This is so that instead of manually entering transactions in both the accounting system and then again up at the bank's website, firms can enter them once into the accounting system and the integration software I'm writing will handle making the appropriate web service calls to initiate the actual transactions at the bank.

There is a consortium out there known as the Interactive Financial eXchange Forum, usually known simply as IFX. They're an industry group that writes specifications for the transfer of financial data using XML and web services. Many financial instutions and software packages use specifications from the IFX, such as Intuit, the makers of Quicken software.

Some of these specifications are available for download for free. The most recent versions (and the most useful, e.g. XSD schemas) are often available to members only (and that pricetag is quite steep). I'm using version 1.7. Within the version 1.7 schemas, there is a type known as NC, which stands for "narrow-character" string. A narrow-character string is basically all 7-bit ASCII characters below 0x7F.

My first thought was to write an extension method to perform the conversion:

public static string UTF8ToLatin1(this string value);

This worked well until I discovered that I had to constantly remember that if a string variable needed to be a narrow-character string, I needed to call that extension method anytime I changed its value. Needless to say, I found occassions where I forgot to call the method. So while cool, this was not a good long-term solution.

A New Class is Born

So then I decided to get "cute"; but hopefully not too cute. It turns out that string is a sealed class. This is unfortunate, but there's probably a good reason for that. So I decided to write my own wrapper class that wraps a string value that provides all the necessary validation while delegating much of its behavior to string and all the while making it inheritable (there are several specializations of a narrow-character string used throughout the IFX specification schemas). I called it NCString.

Everything was going pretty well until I realized that I couldn't just simply assign a string to a NCString object and vice versa without using some sort of property or method accessor. Well I don't know about you, but that just smelled to me.

I then went researching to see if there was any way to create some sort of overloaded casting operator (sort of like C++'s static_cast and dynamic_cast operators, and what-not). It turns out, .NET has what they call conversion operators. I had forgotten all about these, mainly because they look a lot different since CLR 2.0 than from CLR 1.0, and honestly, I never had the need to implement one before (except for the occasional ToXXXX/FromXXXX methods).

Conversion Operators

In CLR 1.0, conversion operators were merely method calls in the form of ToXXX(...)/FromXXX(...) for languages that don't support operator overloading, and named operators called op_Explicit and op_Implicit for those languages that do support operator overloading.

In CLR 2.0, conversion operators got some syntactic sugar (at least, in C#). Explicit conversion operators, when used, look like regular casts from one type to another (much like how you can create a constructor in C++ that takes the type to convert from, which then allows you to use the C++ cast convention instead of calling the constructor directly). Implicit operators are even cooler in that the syntactic sugar allows you to directly assign the object to convert from directly to the object being converted to, as if both objects were of the same type. Obviously, there's much room for abuse here, so there are some compiler-enforced rules as well as general guidelines on their (as well as explicit conversion operator's) use, which can be found here and here.

So in my NCString class, I created the required constructors, implemented the requisite object.Equals methods, overloaded the equality operators, and finally created implicit conversion operators, both to and from string. Now, if you took the time to read the guidelines I linked to above, you will notice that I may have violated one of the guidelines:

Do not provide an implicit conversion operator if the conversion is potentially lossy.

This is sort of a judgement call. On the one hand, you could consider the conversion from string to NCString as "lossy", because potentially, a string can hold a wider range of characters than what is allowed in a NCString. However, if you try to assign a string with characters that fall outside the allowable range for a NCString, a System.ArgumentException is thrown—from the constructor of NCString, which curiously, is shown as an example in the Framework Design Guidelines documentation, and yet, which also seems to violate the following guideline:

Do not throw exceptions from implicit casts.

(If anyone has anything to say about the examples shown in the Framework Design Guidelines versus the guidelines themselves, I'd be interested to hear; leave a comment.)

As I was saying, on the one hand, the implicit conversion from string to NCString could be considered lossy. On the other hand, the two are strings, it's just that one has a more restrictive character set (e.g. it's not like I'm trying to convert from a double to an int, the conversion of which could result in actual data loss). So, in light of that, it would make it much simpler to work with the NCString class if I could convert between instances of NCString and string without needing to explicitly write a cast all the time.

Unit Testing Problems Begin

About this time is when some unit testing problems began to rear their ugly head when it came to calls to Assert.AreEqual(expected, actual). I initially began writing this blog post thinking that the generic version of this method was not properly inferring the parameter types or that the non-generic version was being called instead of the generic version. Well, it turns out to be the latter rather than the former.

When I began writing unit tests, I would have code similar to the following:

// Assert
NCString nc = "Hello World";

// Act
target = new SomeObject(nc);

// Assert
Assert.AreEqual(nc, target.NarrowString);

/* Results of assertion:
 *
 * Assert.AreEqual failed: Expected<MyNamespace.NCString>  Actual<System.String>
 *
 */

Identity Crisis

I expected that, 1) with the method having a generic method signature overload, 2) .NET's ability to infer generic method type parameters, and 3) since the parameters I passed were two different types with conversions from one to another, that actual would attempt to be casted into the type of expected, after which, they would then be tested for equality.

As I just mentioned above, in .NET, generic methods can most often infer their generic parameters, so you don't need to explicitly tell .NET what the type of the generic parameter is. This is precisely what's causing me issues. I'm used to letting .NET infer my generic parameter types (especially when it comes to LINQ statements). But in this case, it's not being inferred. Why not?

The answer is rather simple; but throw in some implicit conversion operators and the answer becomes more complex. So here's the not-so-simple answer. What was happening was that the compiler did (probably) attempt to use the generic method. But, because I didn't specify the type of the generic parameter T, instead, letting .NET (try to) infer the type, .NET was unable to infer the type. Why? Because of the implicit conversion operators. What type should .NET infer for the parameters? string? NCString? Both parameters are implicitly convertible to one another. Furthermore, even if .NET did choose one type over another, there really isn't a way to dynamically cast one type to the other through reflection. Indeed, in the end, the compiler had to choose to use the overload that takes two object parameters. And, of course, object has an Equals method that does little more than test for type equality and referential equality.

Finding Myself

There are two solutions to this problem. One easy, the other somewhat easy.

First, the somewhat easy one (my first approach, mostly because I didn't look to see what else was available in the Assert class). Explicitly tell the compiler what the generic type parameter should be so that the generic method signature is used: Assert.AreEqual<NCString>(expected, actual);. Because the two types are implicitly convertible to/from one another, and I've explicitly specified the generic type parameter to be a NCString, the actual parameter will be converted to a NCString and NCString's implementation of Equals will be used.

The really easy solution (for my case) is to use the overload that takes two string parameters and a bool (indicating whether or not the assertion should be handled case-insensitively). Using this overload, I'd have to use the third boolean parameter (in my case, always set to false) and no explicit type casting/conversion would need to be performed. (Note however, that an implicit type conversion would still be performed from NCString to string.)

Which is better? Hard to say and it mostly depends on what you're trying to test for equality. In my case, both types were strings (one more specialized than another), so there's not much of a diffirence one way or another and not much more in the way of typing for one way or the other.

Some Final Questions and Concluding Remarks

So, I wonder, does the .NET Unit Test Framework always use the Assert.AreEquals(expected, actual) overload that takes two object parameters whenever the two parameters are of different types, or just in the case when the two parameters are not the primitives for which an overload exists and a generic type parameter was not specified?

Anyway, I just wanted to post this, because this has been bothering me for a while. I didn't expect this behavior, but now that I've worked through it, I understand it. I hope that I can save you many hours of troubleshooting your unit tests.

.NET Regular Expressions and XML NAME tokens

noreply@blogger.com (Craig S.) — Fri, 24 Aug 2012 21:01:00 +0000

Hello everyone. I'm back again. Before we get started, I just kind of wanted to put out a notice. I'm working on my blog template. So if you come here and see that stuff doesn't look exactly the way it should, well, you've been warned. This includes the mobile template (so far, I'm not impressed with blogger's mobile templates).

Wow, so many articles in such a short amount of time! Yes, I'm being facetious ;). Let's hope I can continue this pattern. Afterall, I started this blog 3 years ago to start writing down things I learn and which I'd like not to forget.

Well, this blog post certainly fits the bill. I know I've done some research on this once before, but I failed to write it down. So I wasted some more time re-researching this problem. What a waste. So, to help you not waste your time, I hope that you find this blog post helpful. Enough already, let's dive in!

Extensible Markup Language `NAME` Tokens

I first learned eXtensible Markup Language (XML) back in 2000-something-or-other and haven't used it much. A lot of people use XML everywhere for anything. I'm not a big believer in that, actually. It's a great tool and it makes sense to use it where and when it needs to be used.

Having said that, there have been 3 occassions over the last eight months where I had to brush up on my XML skills and really know it well. I'll put a shameless plug in for a book that, while old, has helped me tremendously (I haven't seen its equal): XML Primer Plus by Nicholas Chase.

Like I said, the book is a bit dated now, but it still has very valuable information in it and not much has changed. Having said that, one thing that has changed are the allowable characters in NMTOKENs. I recently needed to validate values I read from user input to ensure that they were in fact valid an id attribute values. I naïvely assumed the following regular expression:

if ( ... && Regex.IsMatch(id, @"^\\d.*|\\w*[\\p{P}-[_]]+.*$") { ... }

So, basically, a XML NMTOKEN can have anything in it except punctuation characters (except for the underscore). I just realized as I'm typing this that I completely forgot to check if the NMTOKEN started with a number, which also isn't valid.

This might have been fine back in 1999, but the XML standard has changed since then. It's still version 1.0 (well, there is a version 1.1, but let's not go there), but it's the 5^th edition.

The current XML specification defines a NAME token (to which ID tokens must adhere and which is a specialized form of a NMTOKEN as follows:

[Definition: A Name is an Nmtoken with a restricted set of initial characters.] Disallowed initial characters for Names include digits, diacritics, the full stop and the hyphen.
Names beginning with the string "xml", or with any string which would match (('X'|'x') ('M'|'m') ('L'|'l')), are reserved for standardization in this or future versions of this specification.
Note:
The Namespaces in XML Recommendation [XML Names] assigns a meaning to names containing colon characters. Therefore, authors should not use the colon in XML names except for namespace purposes, but XML processors must accept the colon as a name character.
The first character of a Name MUST be a NameStartChar, and any other characters MUST be NameChars; this mechanism is used to prevent names from beginning with European (ASCII) digits or with basic combining characters. Almost all characters are permitted in names, except those which either are or reasonably could be used as delimiters. The intention is to be inclusive rather than exclusive, so that writing systems not yet encoded in Unicode can be used in XML names. See J Suggestions for XML Names for suggestions on the creation of names.
Document authors are encouraged to use names which are meaningful words or combinations of words in natural languages, and to avoid symbolic or white space characters in names. Note that COLON, HYPHEN-MINUS, FULL STOP (period), LOW LINE (underscore), and MIDDLE DOT are explicitly permitted.
The ASCII symbols and punctuation marks, along with a fairly large group of Unicode symbol characters, are excluded from names because they are more useful as delimiters in contexts where XML names are used outside XML documents; providing this group gives those contexts hard guarantees about what cannot be part of an XML name. The character #x037E, GREEK QUESTION MARK, is excluded because when normalized it becomes a semicolon, which could change the meaning of entity references.
Names and Tokens
Rule Production
[4]
NameStartChar
::=
":" | [A-Z] | "_" | [a-z] | [#xC0-#xD6] | [#xD8-#xF6] | [#xF8-#x2FF] | [#x370-#x37D] | [#x37F-#x1FFF] | [#x200C-#x200D] | [#x2070-#x218F] | [#x2C00-#x2FEF] | [#x3001-#xD7FF] | [#xF900-#xFDCF] | [#xFDF0-#xFFFD] | [#x10000-#xEFFFF]
[4a]
NameChar
::=
NameStartChar | "-" | "." | [0-9] | #xB7 | [#x0300-#x036F] | [#x203F-#x2040]
[5]
Name
::=
NameStartChar (NameChar)*

	Rule		Production
[4]	NameStartChar	::=	`":" \| [A-Z] \| "_" \| [a-z] \| [#xC0-#xD6] \| [#xD8-#xF6] \| [#xF8-#x2FF] \| [#x370-#x37D] \| [#x37F-#x1FFF] \| [#x200C-#x200D] \| [#x2070-#x218F] \| [#x2C00-#x2FEF] \| [#x3001-#xD7FF] \| [#xF900-#xFDCF] \| [#xFDF0-#xFFFD] \| [#x10000-#xEFFFF]`
[4a]	NameChar	::=	`NameStartChar \| "-" \| "." \| [0-9] \| #xB7 \| [#x0300-#x036F] \| [#x203F-#x2040]`
[5]	Name	::=	`NameStartChar (NameChar)*`

At this point, I thought, "No problem," I'll just use those productions in a Regular Expression while making sure the token doesn't start with xml or some form of that thereof and that'll be that. During unit testing, I discovered that out of 29 invalid sequences that I tried (which were all in the ASCII portion, so this unit test was not comprehensive in any way for the time being), only 7 were flagged. What's going on here?

Well, I read the MSDN documentation for .NET Regular Expressions. Here was the expression I used that was failing the unit test:

@"^(?i:(?!xml))(?inx:[a-z]|_|:|[\u00C0-\u00D6]|[\u00D8-\u00F6]|[\u00F8-\u02FF]|[\u0370-\u037D]|[\u037F-\u1FFF]|[\u200C-\u200D]|[\u2070-\u218F]|[\u2C00-\u2FEF]|[\u3001-\uD7FF]|[\uF900-\uFDCF]|[\uFDF0-\uFFFD]|[\u10000-\uEFFFF])(?inx:[a-z]|_|:|[\u00C0-\u00D6]|[\u00D8-\u00F6]|[\u00F8-\u02FF]|[\u0370-\u037D]|[\u037F-\u1FFF]|[\u200C-\u200D]|[\u2070-\u218F]|[\u2C00-\u2FEF]|[\u3001-\uD7FF]|[\uF900-\uFDCF]|[\uFDF0-\uFFFD]|[\u10000-\uEFFFF]|-|\.|\d|\u00B7|[\u0300-\u036F]|[\u203F-\u2040])*$"

Now, I must admit, .NET's Regular Expression syntax is a bit funky. Anyway, the (?i:(?!xml)) says if the string case-insensitively starts with XML, then it doesn't match. Otherwise, use the production rules as shown above from the W3C.

The catch is, .NET strings are encoded in UTF-16 (and therefore, the escape sequence \u can only be followed by 4 hexadecimal digits), but according to the production for a NameStartChar I need to detect some characters outside of this range (the [\u10000-\uEFFFF] character class inside of the Regular Expression). Now, I had done some research on internationalization and Unicode, but I never really had to pay much attention to it. I'm the one who's mostly using my software. However, this is not the case this time. This software may be used by firms doing banking all over the country and aronud the world. So I definitely need to check that the ID string I'm getting is valid. During my research, I came across Joel Spolsky's blog on Unicode and character encoding. This was a good start (and you should read this if you haven't already), but I needed to know more. Specifically, how can I encode a Unicode character that falls outside of the range 0 - 65535 into a 16-bit value?

UTF-16 Surrogate Pairs

The answer is UTF-16 surrogate pairs. I had heard of these, but I didn't know how to generate them. This article helped me out. In the UTF-16 character encoding, there are no UTF character code points defined in the range 0xD800 - 0xDFFF. This range is used in an algorithm to generate the UTF-16 surrogate pairs that represent Unicode character code points above 65535. The algorithm is really simple and is outlined below..

Take the hex value of the Unicode character to encode as UTF-16 and subtract 0x10000 from it.
Take the result from step 1 above and shift it right 10 bits (0xA).
Take the result from step 2 and add 0xD800. This gives you the first surrogate of the surrogate pair.
Again, taking the result from step 1, AND the value with 0x3FF to mask off the upper 10 bits.
Add 0xDC00 to the result from step 4 above. This represents the second surrogate of the UTF-16 surrogate pair.

The resulting 16-bit surrogates from above properly encode Unicode character code points above 65535 in UTF-16. Let's run through a quick examlpe.

Enocding a Unicode Character Code Point Above 65535 into UTF-16

Let's start with the Unicode character code point U+18657. (I don't know what this character is, I just chose something at random.) Following our algorithm above:

0x18657 - 0x10000 = 0x8657
0x8657 >> 0xA = 0x21
0x21 + 0xD800 = 0xD821 (This is the first surrogate of the surrogate pair.)
0x8657 & 0x3FF = 0x257
0x257 + 0xDC00 = 0xDE57 (And this is the second surrogate of the surrogate pair.)

So, from the algorithm above, the Unicode character code point U+18657 can be encoded into UTF-16 using the surrogate pair U+D821 U+DE57.

Putting it All Together

Finally, we come to the end. I needed to replace the character class [\u10000-\uEFFFF] with a valid \u escape sequence construct. That involves calculating the range of the surrogate pairs for the character class. I used the algorithm above to calculate the range of surrogate pairs which results in the following pattern that should be used to replace the invalid character class: ([\uD800-\uDB7F][\uDC00-\uDFFF]). This pattern will match all UTF-16 encoded Unicode character code points between the range of U+10000 - U+EFFFF, which is exactly what we want. Here's the final Regular Expression that will validate an XML ID token:

@"^(?i:(?!xml))(?inx:[a-z]|_|:|[\u00C0-\u00D6]|[\u00D8-\u00F6]|[\u00F8-\u02FF]|[\u0370-\u037D]|[\u037F-\u1FFF]|[\u200C-\u200D]|[\u2070-\u218F]|[\u2C00-\u2FEF]|[\u3001-\uD7FF]|[\uF900-\uFDCF]|[\uFDF0-\uFFFD]|([\uD800-\uDB7F][\uDC00-\uDFFF]))(?inx:[a-z]|_|:|[\u00C0-\u00D6]|[\u00D8-\u00F6]|[\u00F8-\u02FF]|[\u0370-\u037D]|[\u037F-\u1FFF]|[\u200C-\u200D]|[\u2070-\u218F]|[\u2C00-\u2FEF]|[\u3001-\uD7FF]|[\uF900-\uFDCF]|[\uFDF0-\uFFFD]|([\uD800-\uDB7F][\UDC00-\uDFFF])|-|\.|\d|\u00B7|[\u0300-\u036F]|[\u203F-\u2040])*$"

A Few Closing Remarks

Firstly, the second and third Regular Expressions shown in this article could be simplified (e.g. getting rid of all the alternation (|) constructs between character classes and creating one big character class). Second, and most important, this probably isn't exactly what you should normally do. The productions given by the W3C are meant to be inclusive, as they noted for their justification of the productions. But it would probably be more efficient to write a Regular Expression that matches on what should not be present in a XML ID token (though, the Regular Expression would be almost as long and complex).

I did test my final Regular Expression as shown above, and it did pass (again, my unit test was not comprehensive with regards to characters outside the 7-bit ASCII character set). However, since I used the production shown in the XML specification, I have no reason to think that this Regular Expression would not let an invalid ID token "slip" through.

Updating a Visual Studio 2010 Extension for Visual Studio 2012

noreply@blogger.com (Craig S.) — Wed, 22 Aug 2012 20:13:00 +0000

UPDATE - 16 January 2013

The contents of this article have been updated to correct a problem that existed at the time of publication. In addition, I have uploaded this updated Visual Studio extension to the Visual Studio Gallery.

Hello everyone. It's been way too long. It seems I'm always doing this and that and never have time to write down anything, anywhere—whether that be on this blog, or on Facebook. But today, I have something special for those of you who have that favorite Visual Studio 2010 Extension that they just can't live without, but it hasn't been updated for Visual Studio 2012.

In order to update the extension, you will need access to the extension's source code; so these instructions will have limited impact for most of you out there unless you can get your hands on the source code for that favorite extension.

Fortunately for me, the author of my favorite extension, AllMargins, did post his source code, especially since this extension is no longer available from the Visual Studio Gallery.

Install the Visual Studio 2012 and 2012 SDKs

In order to author extensions for Visual Studio, one must have the Visual Studio SDK installed. The same is true for modifying them. If you don't already have it installed, go out and download it and install it.

Prepare the Source Code for Visual Studio 2012

If you want to maintain backward compatibility for the extension, it would be best not to open the original Visual Studio 2010 solution in Visual Studio 2012. That's because Visual Studio Extension projects for Visual Studio 2010 are not compatible with Visual Studio 2012. Well, that's not exactly true. The real truth is that the VSIX manifest XML schema has changed between Visual Studio 2010 and Visual Studio 2012. The old schema still works for Visual Studio 2012, but Microsoft would have you use the new schema going forward. The problem is, if you use the new schema, you won't be able to use the extension in Visual Studio 2010. Don't worry though, Visual Studio 2012 will not upgrade the schema, just the project file(s); but in doing so, the projects will no longer open in Visual Studio 2010.

Why should you care? Well, for one, testing. You can't simply instruct VsixInstaller to install the extension to an experimental instance of Visual Studio, unfortunately. That really makes it hard to test the extension for more than one version of Visual Studio. Even so, you really should be testing your extension on a virtual machine with the installed version of Visual Studio to test it with and which does not have the Visual Studio SDK installed. If the Visual Studio SDK is installed on your test machine, your extension will always work but, you may find that it doesn't work users who don't have the Visual Studio SDK installed. Your extension should not explicitly require the Visual Studio SDK be installed (unless you're writing a Visual Studio Extension project template! Lol...).

If you want to be able to develop and test in both Visual Studio 2010 and Visual Studio 2012 on the same machine, here's my suggestion.

Create a new empty solution called <Your Extension>.2012 in the same place as the original solution.
Open Windows Explorer to the location of one of the projects that are in the Visual Studio 2010 solution.
1. Select the project file and copy and paste it into the same folder. The file will be renamed 'Copy of <Your Project File>.csproj' (or .vbproj, if you use Visual Basic). Rename the file to <Your Project File>.2012.csproj.
2. Back in Visual Studio 2012, add <Your Project File>.csproj to your solution.
Add all the files that are part of the Visual Studio 2010 project to the newly created Visual Studio 2012 project.
Repeat these steps for each of the other projects that were part of the original Visual Studio 2010 solution.

Now you can work on the source code in both Visual Studio 2010 and Visual Studio 2012, opening the respective solution for the version of Visual Studio you're using to make changes. When you build the Visual Studio 2012 solution, it will be deployed to the Visual Studio 2012 experimental instance. The same is true for 2010, the extension will be deployed to the Visual Studio 2010 experimental instance. Also, it allows you to work on a single code-base that should work in both environments so long as you don't use features exclusive to Visual Studio 2012.

While upgrading this extension to work with Visual Studio 2012, I discovered that there is an enumeration value in the VSIX XML schema for specifying the Express editions of Visual Studio. However, the only "extensions" that Express SKUs support are project/item template extensions.

We're now ready to start modifying the various files to make this extension compatible with Visual Studio 2012!

Update the `*.vsixmanifest` file

The first order of business in updating the extension is to modify the *.vsixmanifest file. Here's an example of one of the files from the AllMargins.vsix extension:

<?xml version="1.0" encoding="utf-8"?>
<Vsix xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" Version="1.0.0" xmlns="http://schemas.microsoft.com/developer/vsx-schema/2010">
    <Identifier Id="SettingsStore.dpugh.ce3ce74a-4966-4a66-b9ad-a3adf4f9e940">
        <Name>SettingsStore</Name>
        <Author>dpugh</Author>
        <Version>1.2</Version>
        <Description xml:space="preserve">This defines an API for persisting IEditorOptions across sessions.</Description>
        <Locale>1033</Locale>
        <MoreInfoUrl>http://code.msdn.microsoft.com/OverviewMargin/Release/ProjectReleases.aspx?ReleaseId=3957</MoreInfoUrl>
        <SupportedProducts>
            <VisualStudio Version="10.0">
                <Edition>Ultimate</Edition>
                <Edition>Premium</Edition>
                <Edition>Pro</Edition>
            </VisualStudio>
        </SupportedProducts>
        <SupportedFrameworkRuntimeEdition MinVersion="4.0" MaxVersion="4.0" />
    </Identifier>
    <References />
    <Content>
        <MefComponent>|%CurrentProject%|

    </Content>
</Vsix>

You need to update the SupportedProducts and SupportedFrameworkRuntimeEdition elements as follows:

<SupportedProducts>
  <VisualStudio Version="10.0">
    <Edition>Utimate</Edition>
    <Edition>Premium</Edition>
    <Edition>Pro</Edition>
  </VisualStudio>
  <VisualStudio Version="11.0">
    <Edition>Utimate</Edition>
    <Edition>Premium</Edition>
    <Edition>Pro</Edition>
  </VisualStudio>
</SupportedProducts>
<SupportedFrameworkRuntimeEdition MinVersion="4.0" />

By removing the MaxVersion attribute for the SupportedFrameworkRuntimeEdition element, we're telling Visual Studio that so long as the machine supports the .NET Framework 4.0, the extension can be used.

Also for good measure, I updated the Version value (e.g. 1.3) and updated the Description element noting that I changed the VSIX package and it is not the original. As an aside, every time you make a change to the extension that you wish to distribute, you must increment the value for the Version element.

Now I ran across a tricky problem with updating the AllMargins extension. This extension has several "sub-extensions" that are contained within the AllMargins extension itself. And some of these "sub-extensions" have yet other "sub-extensions". The long and short is, during testing, Visual Studio had a problem locating some of the required DLLs.

What I found out is that some of the sub-extension projects contained an additional file—a *.pkgdef file. This is an older file that was used with VSPackages back in the VSI days of Visual Studio 2005/2008. This file is not much unlike a *.reg file, though with a slightly different syntax.

This file for the SettingsStore sub-extension (for which the VSIX manifest file was shown above) looks like this:

[$RootKey$\BindingPaths\{8ADD56CC-E512-4CB0-AF58-33ECCC0B4912}]
"$PackageFolder$"=""

This creates the GUID under HKCU\Software\Microsoft\VisualStudio\<Maj. Version Num>_Config\BindingPaths key. $PackageFolder$ expands to the folder where the extension was installed by VSIXInstaller.

Apparently, in Visual Studio 2010, just placing this file within your VSIX package was enough for Visual Studio to go ahead and create the requisite registry keys and values. However, this does not work with Visual Studio 2012 and attempts to use extensions relying on this extension result in a System.IO.FileNotFoundException. In order to resolve this issue, you must place some additional content in your VSIX manifest file as shown below.

<References>
    <Reference Id="Microsoft.VisualStudio.MPF" MinVersion="10.0" />
        <Name>Visual Studio MPF</Name>
    </Reference>
    <!-- Any other references you may have -->
</References>
<Content>
    <MefComponent>|%CurrentProject%|</MefComponent><!-- Expands to the assembly name -->
    <VsPackage>SettingsStore.pkgdef</VsPackage><!-- Not required by VS2010, but is required by VS2012 in order for the file to be processed -->
</Content>

With all of that out of the way, save the file and we're done with the *.vsixmanifest file. If there are several VSIX extensions that make up the extension you're updating (as is the case for AllMargins.vsix), you will need to do this for each *.vsixmanifest file in the solution.

At this point, at the original date of publication (22 August 2012), I had you retarget the projects in the solution and replace some DLL references. If you want to maintain compatibility with Visual Studio 2010, this is not necessary. So I have removed that section of the original blog entry.

Recompile a Debug Build

You should now recompile the solution using a Debug build. This will automatically install the extension(s) into the Visual Studio experimental instance(i.e. it won't muck up your Visual Studio that you use for everyday coding). Make sure that everything works correctly. If all is well, you're ready for the final step.

Recompile in Release Mode

If your testing above went OK, then change the build mode from Debug to Release and recompile. Then simply navigate to the bin\Release directory under the project folder for the extension and double-click the VSIX file to install it.

Now, in this case, I was not required to change a single line of code. This may not be the case for every extension you wist to upgrade. YMMV.

Enjoy using Visual Studio 2012

That's it! Enjoy using Visual Studio 2012 with your beloved extension.

Sample Title Marked up Using x-hTitle Microformat Proposal

noreply@blogger.com (Craig S.) — Wed, 21 Jul 2010 00:34:00 +0000

This blog entry will demonstrate using the proposed x-hTitle microformat to mark up a title. Since this is a sample for a microformat proposal, what better title to use than the one that I first read regarding the subject. So, without further adieu, here's a sample. One other quick note: I may edit this blog entry from time-to-time, adding more samples. Eventually, they will all be moved to the microformats.org site if this proposal becomes a draft specification.

Sample `x-hTitle` Formatted Title

Microformats: Empowering Your Markup for Web 2.0

Author: John Allsopp

Publisher: friends of ED

Edition: First Edition

Abstract

Microformats burst onto the scene a couple of years ago and are fast becoming an essential tool for all professional web designers and developers. Imagine being able to integrate all of yourr web-based contact details, tagged articles, and geographical information seamlessly in web and desktop applications, without having to add anything extra to your websites except a little specialized HTML markup.

Microformats provide a more formalized technology for adding commonly used semantics (such as contact details, locations, and reviews) to today's Web. Unlike XML or the Semantic Web, microformats use ubiquitous technologies like HTML and XHTML, existing developer skills and current web tools, and, perhaps most important, they all work in today's web browsers.

This book is a comprehensive guide to microformats. It explores why, in Bill Gates' words, We need microformats; how microformats work; and the kinds of problems microformats help solve. The book covers every current microformat, with complete details of the syntax, semantics, and uses of each, along with real-world examples and a comprehensive survey of the tools available for working with them. The book also features case studies detailing how major web content publishers such as Yahoo! put microformats to work in their web applications.

Written by one of the Web's best-known educators, John Allsopp, Microformats: Empowering Your Markup for Web 2.0 will help you painlessly get up to speed with this exciting technology.

In this Book You'll Learn...

How to take best advantage of the built-in semantics of XHTML and HTML.
How to extend the semantics of HTML using microformats and open up a world of new possibilities with web applications.
Every aspect of all the common microformats currently in use.
How microformats help your websites and applications easily integrate with web applications like Google Maps, as well as desktop applications like iCal, Outlook, and Entourage.
What innovative publishers and services, big and small, are doing right now with microformats.

Summary of Contents

Part One: Introducing Microformats
- Chapter 1: What are Microformats?
- Chapter 2: The State of the Art in Microformats
Part Two: Using Microformats
- Chapter 3: Structural and Semantic HTML
- Chapter 4: Link-Based Microformats: rel-license, rel-tag, rel-nofollow, and VoteLinks.
- Chapter 5: Microformat to Describe Relationships Between People: XFN
- Chapter 6: Location Microformats: geo and adr
- Chapter 7: Contact Information Microformat: hCard
- Chapter 8: Event Microformat: hCalendar
- Chapter 9: Review and Resume Microformats: hReview and hResume
- Chapter 10: Syndicated Content Microformat: hAtom.
Part Three: Case Studies
- Chapter 11: Case Study: Cork'd
- Chapter 12: Case Study: Yahoo!
Part Four: Developing Microformats
- Chapter 13: The Process of Developing Microformats
Part Five: Appendixes
- Appendix A: Microformat Specification Reference
- Appendix B: Microformat Design Patterns
- Appendix C: People, Tools, Services, and Publishers

A New Microformat Propoal: x-hTitle

noreply@blogger.com (Craig S.) — Wed, 21 Jul 2010 00:32:00 +0000

Comments Regarding the Proposed `x-hTitle` Pre-Draft Specification

This blog post is meant to document my vision of a microformat for semantically marking up information about titles. On the microformats.org process page, it is recommended that you not name your new proposed format hsomething. But, since this is a proposed pre-draft specification, I need to be able to reference something throughout this specification. Therefore, I am naming this proposed format x-hTitle, where x stands for experimental. If there is interest in developing this microformat further, the x in the name could be removed. In addition, the name of the proposed microformat could change according to community consensus during the specification process.

The `x-hTitle` Proposed Pre-Draft Specification

Editor/Author

Craig S

Contributors

None yet. If you would like to contribute, please register on the microformats.org's microformats-new mailing list and read posts regarding this proposal and contribute your thoughts and suggestions. If this proposal gets the green light to become a draft specification, you can contribute to the specification at the microformats.org's website and your name will be listed in this section of the specification.

Introduction

It is difficult for a browser to extract semantic information about a book title described on a web page. Metadata such as author, cover image, and book genres/categories provide relevant content for titles.

In order to keep this microformat as generic as possible, I want to make a distinction between titles and books. A title is something than an author writes. A book is a published representation of a title. There may be more than one book for a given title, for example, a hardcover book, a paperback book, a large-print or illustrated book, etc. Each of these books will have a different ISBN even though they are the same title.

This microformat aims to codify the semantic structured markup of titles. Since a title can describe (possibly) many books, semantically marking up title information has one very important implication: a title which contains reviews (using the hReview or the hReview-aggregate microformat) may have all reviews for it aggregated in one place. This aggregation may then be used to display this information for several books (e.g. the same reviews would be shown for a hardcover, softcover, or other formats of a title) because they are all for the same title.

Having such information marked up can provide many benefits to the viewer of such a page. If a web browser understands that a particular web page contains a title, it can provide rich interactions for the user—for example, specific searches for titles via search services such as Google, Amazon, Yahoo!, Bing, etc. While Amazon already does a good job of returning search results for titles (since that is its primary business) and searches for titles on major search engines usually yield a link to Amazon, marking up titles using a microformat can make indexing title information easier while making this information more accessible to users. In addition, classification of titles by search engines (and crawlers) can be made more accurate. Also, if a page contains many titles by the same author(s), then the web page is not only a list of titles, but also about a particular author(s).

In order to enable and encourage the sharing, distribution, syndication, and aggregation of title content and information, the author proposes a pre-draft specification of a x-hTitle microformat, an open standard for distributed metadata about titles. The author has researched numerous sites which contain titles for sale or advertisement and has designed the x-hTitle microformat around a simple, minimal schema for information regarding a particular title. Feedback is encouraged on this blog entry. If there is enough interest in this pre-draft specification to warrant making a sanctioned draft specification of this microformat, future feedback will be moved to the official microformats.org website.

Inspiration and Acknowledgements

This proposal came about because of reading the book Microformats: Empowering Your Markup for web 2.0 by John Allsopp (note: the book's title has been marked up using this very proposed microformat) and my need to create an inventory system for all media that I own, including CDs, DVDs, books (again, a specific representation of a title), magazines, and anything else media related. As there already exists a hAudio and hMedia microformat, titles are notably left out and most likely relegated to another microformat such as hProduct or hListing which are not the most suitable microformats for this information given the distinction between a title and a particular publication of that title—a book (which is a product and which can be listed, whereas a title in and of itself, is not and can not).

Scope

Information about titles consistently share several common fields. Where possible, this proposed microformat has been based on this minimum common subset.

Out of Scope

This microformat does not aim to be a means of publishing a title online (such as the proposed book microformat boom). Instead, it is a means of marking up information about a title suitable for searching, viewing, and aggregating on sites such as Amazon and Google Books. This microformat, therefore, is not a competitor to boom, rather, it serves a much different purpose.

Format

Abstract

The proposed x-hTitle microformat is based on a set of fields common to many Internet web sites and formats in use today that provide information about titles (in the form of books), whether for sale, advertisement, or promotional or informational purposes. Where possible, field names have been chosen based on those defined by many related microformat standards.

Schema Key

Table 1. Schema Key
Field Format	Description
bold{1}	must be present exactly once.
italic*	optional, and may occur more than once
+	must be present, and may occur more than once.
?	optional, but must not occur more than once.
[square brackets]	A list of common values
(paretheses)	Data format
#	A comment.
!	Awaiting documentation

Schema

The proposed x-hTitle microformat schema consists of the following:

x-hTitle{1}.
- version ?. Using text.
- fn{1}. Reused from hCard
- edition ?. Using text.
- volume ?. Using text.
- contributor*. Reused from hMedia.
- description ?. Using any valid XHTML markup.
- review*. Using hReview or hReview-aggregate .
- category* Using text.

Property Details

version

This optional property permits title publishers to specify a particular version of the x-hTitle microformat that their content uses. By omitting this property, the publisher is stating that implementations may interpret titles marked up using this microformat according to the schema version <to be decided> or later. In practice, the author of this specification is committed to maintaining backward compatability with content produced using earlier versions of the specification. This property is syntax compatible with, and thus reuses semantics of VERSION as defined in the vCard RFC2426 section 3.6.9 VERSION Type Definition. The value of this property for this specification is <to be decided>.

The element is identified by the class name version
x-hTitle may include only one version property.

fn

The full name of the title, including any subtitle.

x-hTitle must include one fn element.
The element is identified by the class name fn.
If the title being marked up with this microformat has its own website (for example, for forum discussions related to the title, source code, or other content), then hCard may be used to provide that information with the title.
This element is reused from hCard.

edition

This property specifies the specific edition of a title.

The element is identified by the class name edition.
x-hTitle may include one instance of this property.
This property may use the abbr-design-pattern .
Since the content of a title from one edition to a next can differ significantly, this information should be included if applicable and available.

volume

This property specifies that the title is a particular volume of a larger collection of works which share a main title.

This element is identified by the class name volume.
x-hTitle may include one volume element.
This information should be included if applicable and available.
This property may use the abbr-design-pattern .

contributor

A contributor is any entity that takes part in the creation and distribution of a title. Examples include: author, illustrator, publisher, editor, technical reviewer, etc.

This element is identified by the class name contributor.
x-hTitle may include one or more contributors.
The contents of the element should include a valid hCard.
- The role element of hCard should be used to specify the contributor's responsibility related to the title.

description

An abstract or explanation of the contents of the title being marked up. for example, this field could be used to contain the text on the back of a technical book that summarizes the content of the title. Or, such as with fiction hardcover books, the content that appears on the inside flaps of the dust jacket.

This element is identified by the class name description.
The element's contents may include any valid XHTML.
x-hTitle may include more than one description.
- If more than one description is defined, the full description is the concatenation, in order, of these elements.

review

The existence of this property identifies review(s) for the title.

The element is identified by the class name review.
Reviews should use the hReview microformat.
If many reviews are to be listed for a title, consider using the hReview-aggregate microformat, instead.

category

The category property can be used to classify the genre, style, or keywords and subject matter associated with the title. Examples could include: fiction, horror, mystery, computer, technical, programming, instructional, biography, etc.

The element is identified by the class name category.
x-hTitle may include one or more category elements.
This element may be expressed using the rel-tag elemental microformat. When a category is expressed using rel-tag, the content of this element is used as the text for the category. For example: <a class="category" rel="tag" href="/tags/romance">Romance</a> would have "Romance" as the text for the category.

Wow, it's been a long while!

noreply@blogger.com (Craig S.) — Sun, 11 Jul 2010 21:30:00 +0000

We Thought You Fell Off the Face of the Earth!

Hello everyone. I'm still around. Well, I warned you, I may not write often. I hope, though, that there are still some readers out there (or new ones will find this blog).

First, a very quick update in fast-forward. I moved because my wife got laid off about a year and a quarter ago. She got a new job fairly quickly given the economy, so that's that. In addition, I've completed two more semesters at Kutztown University and I will be entering my last semester this Fall. I've also been taking two Summer courses.

The main reason for not writing in so long has been three-fold:

The last two semesters have been extremely difficult—on the flip side, I managed to pull off very good grades; so I'm very pleased about that.
I've been trying to work whenever I can to get all those computers installed at Thermocouple Technology, Inc., but it's been really slow going.
Making things even more slow going at TTEC is the fact that I decided to get a different Summer job that would be involved with coding. It is to a certain extent (if you call writing SQL programming), plus, the job is about an hour away from where I live.

My coursework at school over the last two semesters included taking Compiler Design I and II using the famous Dragon Book. I tried to implement a language that could replace SQL. Well, being I wrote the language in academia for academia, it didn't quite turn out the way I would've liked. I spent every waking minute last semester writing code for that class. Anyway, the idea is that the language could be used not only for relational databases, but also XML data, structured textual data (e.g. CSV files, tab-delimited files, etc.), or any other structured data (possibly using some kind of schema definition). As the semester wore on, I whittled the language down to just working with relational databases for the start. However, I didn't have time to learn another database technology with an open API where I could directly access the query engine, so I ended up translating my language to SQL anyway, which didn't work out quite so well. Having said that, my ideas are completely valid and workable, given enough time and resources to develop it properly, and it very well could replace SQL using a much more human-readable/writable syntax. In fact, part of my coursework this Summer is writing a paper on this language and its goals.

Anyway, enough of that. So in a nutshell (which is a first for me, believe me!), that's what's happened over the last year and a half or so.

Why write now?

Well, I'm glad you asked. As mentioned, it's my last semester coming up this Fall at Kutztown University. As such, I'm required to take a course colloquially called Senior Sem, the cap-stone course that's supposed to tie together everything we learned into a final project.

Being who I am, I plan on making the best of it. My idea: an inventory system for all the different types of media I own—books, CDs, DVDs, magazines, sheet music, etc. It will be web-based using the new ASP.net MVC 2.0 framework. I will also be investigating technologies such as jQuery, and AJAX. In addition, I plan on proposing two new microformats to microformats.org to use with my project. I will be writing a few more blog posts over the next couple of days/weeks that contain pre-pre-draft specifications of the proposed microformats, as well as samples of how they could be used alone or along with other existing microformats.

I'm very excited about my project and hope to learn a lot of real-world skills and create a usable application. Whether anyone else would find it useful, I don't particularly care, I've been wanting a comprehensive application like this for years.

More on Microformats

If you don't know what microformats are, I'd encourage you to visit the website I linked to above. In addition, there's also RDFa. The two technologies are complementary. RDFa, as I understand it, is for machines first, whereas microformats are for humans first. Both can be used together to make the web a much more meaningful place for humans and machines.

To make the most of this embedded information, you can use various browser plug-ins to access the information. For example, there is Oomph for Internet Explorer, and Operator for Firefox. When microformats are available on the page, these tools will let you export contact information, calendar events, product information, RSS/Atom feeds, etc. There's a lot of information that can be encoded in semantic XHTML. If you haven't noticed, this blog post has tons of microformats embedded within it.

Conclusion

So, stay tuned, as I begin "the process" of proposing new microformats. I hope to write again in a few days.

The Good Old Days

noreply@blogger.com (Craig S.) — Sun, 17 May 2009 03:13:00 +0000

Just read an entry on Scott Hanselman's blog called 10 Awesome Things I Remember About Computers. The comments on the entry closed May 1, so I thought I'd write my own entry and sort of chain off his. Feel free to leave your own memories!

10 Awesome Things I Remember About Computers (give or take...)

Using my S100 CP/M based computer with CP/M DOS
Using the same computer above, typing my school reports in WordStar (how I miss WordStar)
Typing up BASIC (in that day, I used A-Basic, M-Basic, GW-Basic, and in the '90s, QBasic) game listings
Upgraded to an IBM XT with a 40MB HDD (that was HUGE, and the largest available consumer HDD)
DOS 3.x was out, and sub-directories were new. I didn't know about them/understand them (I was 11!). Anyway, I watched my dad type a command: del *.* and it deleted some files. Pretty cool. I accidentally wrote a file in the wrong spot. I couldn't get it deleted, so I tried this (not understanding directories, they didn't exist in DOS 2.0!): C:\> del *.*. Rebooted, nothing happened. Hmmm... "DAD! My computer won't boot." He said, "What did you do to it?" To which I said, "I don't know, it just wouldn't start." He wasn't too happy. ;) Luckily, it was only my computer, so none of his stuff was on it. Whew!
Playing Tie Fighter on my 486 (this is now about 5 years later, about 1992 I'd say).
Using DriveSpace on Windows95 to compress my 810MB HDD to get 2.4GB space. Boy was that a bad idea!
Buying my first computer from scratch and putting it together myself (1997) for $2400: PII 350MHz w/ ABIT BX6 mobo, 256MB RAM, 12GB HDD (yeah baby!) and a LS-120 FDD (that was a total waste).
One year later, bought another computer for $1100: PII 400MHz w/ 512MB RAM, ABIT BX6 Rev 2 mobo, Acer 40x CD-ROM, Yamaha 24/8/4 CD-RW drive and another 12GB HDD
Windows 2000. Finally, a true 32-bit OS that worked well.
Windows XP—so much better!
One more for good kicks (though this is recent history)—Microsoft releases their second-most horrible OS (after ME), Vista. Can't wait for Windows 7!

Though I have some recent stuff on my list, I've been using computers since I was 8 (so just shy 25 years). I'd like to hear from you, too. What are some of your memories?

Book Review: Microformats: Empowering Your Markup for Web 2.0

noreply@blogger.com (Craig S.) — Thu, 14 May 2009 19:42:00 +0000

Microformats: giving birth to the semantic web

I just finished reading Microformats: Empowering Your Markup for Web 2.0. I've heard of microformats here and there over the last 3 or 4 years, but until now, I haven't really looked into them. I saw this book for sale on Amazon.com at a price I couldn't resist. It was high about time that I read about what this semantic web thing is all about.

I thought the semantic web was simply about using the appropriate XHTML when creating your web pages and being sure that you were meeting various other standards along the way, such as WCAG. The semantic web is that and much more.

Microformats give web content designers and developers a way to use existing XHTML to markup their content so that it can be easily read by humans but also easily read by machines. This has the advantage that, obviously, humans can read it, but that the content can be aggregated by various web services.

This book is one of the best organized books I have ever read and I highly recommend reading this book for a detailed, but quick introduction to microformats. In fact, microformats are so easy to use, an introduction is all you really need to begin using them. If you need more information, just check out microformats.org.

This review is written using the hReview format as discussed in the book. Since this is my first attempt at using this microformat, if there's anything wrong with it, please leave a comment. In any event, I give this book 5 stars out of 5.

FireFox 3.0.10 and IE8

noreply@blogger.com (Craig S.) — Thu, 14 May 2009 13:30:00 +0000

Time for another, though much shorter, rant.

My Headaches with Firefox 3

I've had it with Firefox. I was late to jump on the Firefox bandwagon. I jumped on around 2.08 or so and upgraded all the way up to 3.0.10 as recently as two weeks ago. I upgrade Firefox as soon as I can, though I admit, I waited a bit to upgrade to Firefox 3; and it seems for good reason. At first, I was very impressed with Firefox 3. It provided better tab scrolling and seemed much more stable than Firefox 2. That is, until I "upgraded" to Firefox 3.0.9. Then everything came to a screeching halt.

You have to understand that I'm a power browser user. Some would say I'm just crazy. But I have so many things going on that I have a ton of tabs open (at current count, about 344) so that I can quickly get back to whatever else I was doing/researching within the past few weeks (ok, months). As Firefox has continued to release updates, its memory footprint continues to grow, rivaling Internet Explorer with it's famed JavaScript memory leak. At first, Firefox was crashing because I actually had 360+ tabs open and during loading all of the tabs, the process size reached 1.5GB, which is apparently the maximum process size on Windows even though each process has 3GB of memory space (go figure?). Ok, so that's my fault. But since then, I've closed unneeded tabs and had gotten as low as 320. My Firefox process size was around 600MB - 700MB. However, I experienced browser crashes 2 or 3 times a day.

Yay, Firefox came out with an update, 3.0.10. So I upgraded to that seeing that they fixed (yet another) memory corruption issue (how many of those things do they have??). I hoped that it would solve my problem. Nope. Firefox routinely continues to crash at least once a day, if not twice. I tried things like turning off Google Desktop Search (which is a huge memory waster anyway and should be uninstalled from every computer on earth because it puts its hooks into every single program that's opened on your computer). But to no avail. I've done some searching on this issue and have found that many are experiencing the same problem (I hear it can be much worse on Linux). This leads me into my next segment.

Enter Internet Explorer 8

OK, so Microsoft copies folks, but so far as I can tell, IE8 was in the works before Google Chrome hit (though, I can't be absolutely sure about this). Whatever the case may be, Chrome and IE8 use the same "memory model". Each browser tab is a separate process. This has advantages, and disadvantages. However, today, the disadvantages are smaller than they used to be.

When I first heard that Chrome used separate processes for tabs, I was not impressed. Sure, you have tab isolation, but at what price? Processes are heavy in terms of memory and creation time. However, what I didn't realize (and I was very surprised I had missed this fact!) was that in Windows 2000, a new type of process was created—called a job process. A job process is a new process, but it is related to some parent process. It's almost like a Unix fork, but not quite. In any event, these processes, while providing isolation, don't have as steep memory requirements or creation time. IE8 makes heavy use of the job process (as I'm sure Chrome does).

So I started playing around with IE8 last week. I must say I'm pretty impressed. It's stable, and if a tab crashes, it will attempt to reopen the tab. With IE8, you don't have to explicitly save your browsing session, just close the browser and all your tabs are remembered. Personally, I don't care for that. In fact, that's one thing I'm going to miss from Firefox, the Session Manager plug-in. I think one could be written for IE8, but I haven't seen one yet and I don't have time to write one. Anyway, IE8 only lets you save the last browsing session (since it's explicitly saved). You can't save multiple browsing sessions to open one up again at some later point. Too bad. That's a real short-sight. Another plus about IE8 is that it renders much better than it ever used to. I still have to put it through its paces though (and check out how much of ACID2 it passes). Overall, I'm very pleased with it and can't wait to ditch Firefox.

An Open Call (and Mind) to Mozilla

If you're going to release patches for a browser, especially a build update (e.g. 3.0.xxxx), you better do thorough regression testing to make sure you don't break the browser. That's what happened between 3.0.8 and 3.0.9. It just completely broke. 3.0.10 is better, but it's still broken. I think Firefox needs to get back to its roots as a browser: a low memory footprint, extensibility, and stability, and frankly, more cool features that just kill the browser market (tabbing was definitely a killer feature). I'm going to keep my eye on Firefox, but for now, I need stability, speed, and something that just plain works.

P.S.

To the Microsoft haters and open source lovers and the passionate (or even fanatic) people out there: this post is meant as an open honest discussion of my findings in regards to the latest Firefox 3.0.10 browser, and not about the quality of FOSS software, in general. This is particular to Firefox. Also, note that I did not say that I hate Firefox, only that it has become unusable to me. I'm disappointed with it. I hope that the next major (or minor, 3.5, is it?) release will resolve many of the issues I and others have been having. I'm willing to give Firefox another shot, but until I can actually use it to work (without it freezing up every 30 seconds for 10 seconds at a time), I will have to stick with IE8.

ATI Catalyst 9.4 Is No Good for Business

noreply@blogger.com (Craig S.) — Thu, 14 May 2009 01:40:00 +0000

Today's post is a bit of a rant. Also, it took me so long to write, that I didn't want to spend much more time formatting it. So, if it looks a bit messy, I'll try to get back and clean it up a bit later. If you've been reading my blog, you know that I'm in the process of a network deployment. Recently, we qualified for a (basically, free) computer form UPS. Unfortunately, all they had to offer were machines with AMD processors and chipsets. If you haven't guessed it by now, I'm an Intel guy. And now, I know why.

The Problem with AMD

Apparently, AMD doesn't want to make it easy for (particularly small) business to install their software. This is evidenced by the fact that they have completely non-standard Windows installers. They probably use InstallShield for some of their software (which, arguably, makes horrible installers, in my opinion, after having looked at just a few InstallShield MSIs with ORCA from Microsoft). However, their Catalyst Display Driver package uses something called Monet, which until last week, I've never heard of before. And let me say that I hope I never hear of it again, as it caused me nothing but trouble this week.

The idea is that I'm using the Microsoft Deployment Toolkit 2008 to deploy my clients. This driver comes with software that I would like to have installed on the machine, so I decided to go ahead and install the whole package (minus a few items that I really don't need). But it turned out to be a real chore. To start, there is the lack of documentation. Here's the help documentation from Setup.exe and InstallManagerApp.exe, which are responsible for the GUI installation:

-INSTALL[-Use /package path] - This will install packages in silent mode.
 -Use /package path is optional.
 E.g.
 1)-INSTALL:will install the whole packages in silent mode.
 2)-INSTALL -Use c:\packages\Drivers\:will install the defined packages in 
                                             silent mode
-UNINSTALL - This will uninstall all packages in silent mode.

/FORCE_FIRST_RUN - forces the first run wizard each time(good if you’re debugging or
                   showing a demo of the initialization wizard and need it to appear 
                   on every run).

/FORCE_HIDE_FIRST_RUN - forces the first run wizard to hide even if it is the first 
                        run.

/INSTALL - run in install mode (this is what a CD autorun could use to run Monet)

/UPDATE - run in uninstall mode (this is what a toolbar or tooltray could use to 
          launch Monet UI)

/UNINSTALL - run in uninstall mode (this is what a toolbar or tooltray could use to 
             launch Monet UI)

/PACKAGE_SELECTION_LISTBOX - a listbox is shown for package selection, instead of 
                             toggling throughicons (this is more useful in debugging 
                             because in the past I have sometimes encountered 
                             multiple installed versions of the same package).

/VERBOSE_TRACE - This is absolutely necessary to always be in command line if you 
                 want tohave "/TRACE_RM" and "/FORCE_CORECOM_TRACE". The intention 
                 of this option was that we should always trace a minimum on an end 
                 system due to performance issues.... if you're at all interested in 
                 tracing UI or UI<-->Core commmunication, then make sure this is 
                 always in the command line

/FORCE_CORECOM_TRACE:<path> - Traces all communication between core and UI use this 
                              with a target file e.g. with <path> equal to 
                              "C:\my_directory\core_ui_log.txt"

/TRACE_RM - Trace all messages relevent to risk mitigation.

/DISPLAY_FULL_VERSION - Display the full version and timestamp

/PASS_TO_CORE - Will pass any command line in quotes into the core for processing. 
                Example usage /PASS_TO_CORE:"-a -b -c -d -e -f -g" will pass the 
                command line:"-a -b -c -d -e -f -g" to the core. (Note: if you need 
                to pass " character, then use a ' and it willbe converted to " 
                before being passed to the core.

/UNATTENDED_INSTALL<:><files/path><;><file/path> - This puts InstallManagerApp into 
                                                   unattended install mode by using 
                                                   the comma-separated list of 
                                                   files/paths.
 E.g.
 1)/UNATTENDED_INSTALL:"c:\direc1;c:\direc2\filea.msi;c:\direc3"
 2)/UNATTENDED_INSTALL:"c:\drivers"
 3)/UNATTENDED_INSTALL:"c:\drivers\graphics_driver.msi"

/UNATTENDED_UNINSTALL - This will uninstall all packages in unattended mode.

/AUTOACCEPT_ALL - This will autoaccept all legal agreements (for internal use only). 
                  If you don’t use this command line, you’ll have to stick around, 
                  read and accept/deny EULA’s. This option won’t be published.

/ON_REBOOT_MESSAGE:<value> - This takes the answer in advance from the user as to 
                             whether s/he needs to reboot once complete. Valid 
                             <value>s are "YES" or "NO".

/FORCE_REBOOT - On completion of an install/update/uninstall, force a reboot request 
                to OS. Note that the reboot request will only be issued after the 
                application is closed.

/FORCE_CLOSE_WHEN_DONE - This will automatically close the last wizard page on 
                         completion.

/OEM:<value> - Change the OEM look and feel.  Valid <values> must have an entry in 
               the OEM folder the the same folder name

/NO_CUSTOM_UI:<value> - Ignore UI color setting changes from configuration files.

/HELP - Display this message and exit.

Figure 1. Setup.exe/InstalManagerApp.exe command-line switches

Well, I'm confused already. But here's what happens. If you use the slash (/) switches, you can get an unattended GUI install. What do I mean? What I mean is, if you use the right combination of switches, you can achieve an unattended install that still shows a GUI. Ok, that's not so bad. Let's step through these switches a bit. By specifying /UNATTENDED_INSTALL, you would think that would be all I have to do to achieve my goal. Well, you would be wrong. Even when using this switch, the installer stops on the very first wizard page to ask what language you want. Why do I need to choose a language if I'm doing an unattended install? (More precisely, if no language is specified on the command line, English ought to be the default and installation should proceed unattended.) So, in order to get around this, we need to pass the /FORCE_HIDE_FIRST_RUN switch, which does just that—it skips the language selection step. So you run the new command and now the wizard appears to stop in its tracks on the last page and just sits there. That's because even during an "unattended" install, the setup program expects you to click the Finish button. Stupid. So we need to pass the /FORCE_CLOSE_WHEN_DONE switch. Just to be extra cautious, I pass the /AUTOACCEPT_ALL switch, which automatically accepts all EULAs (which according to AMD is supposed to be unpublished, hehe). I also pass the /ON_REBOOT_MESSAGE:NO switch to make sure the installer doesn't tell the operating system to reboot, a big no-no when using the Microsoft Deployment Toolkit. So our final command looks like this: setup.exe /UNATTENDED_INSTALL /FORCE_HIDE_FIRST_RUN /FORCE_CLOSE_WHEN_DONE /AUTOACCEPT_ALL /ON_REBOOT_MESSAGE:NO.

Well now there are three problems. In older releases of the Catalyst Display Driver package, HydraVision was installed with everything else and the Windows Vista Experience Index score was also updated so that the Aero user interface would be enabled. This no longer happens in the 9.4 release of the package. It turns out they have a few errors in their new install routine. The lack of installation of HydraVision (a multi-desktop or even desktop spitting application) can be gotten around by replacing /UNATTENDED_INSTALL with /UNATTENDED_INSTALL:"\Packaes\Apps\CCC\HydraVision-Full\ccc-hv-full.msi;<driver_folder>\Packgaes".

Enabling the Aero user interface (in an unattended manner) is also similarly easy. In previous releases, there was an MSI called EnableAero.msi. At first, I was including this in the installation, but I soon realized that all the MSI was doing is running the following command: ~~C:\Windows\System32\WinSat features~~ C:\Windows\System32\WinSAT formal. So, ~~number one~~, the EnableAero.msi installer is completely unnecessary. Secondly, the way they are running the command is also unnecessary. Instead, there is a command line switch that enables you to only update the graphics and restart the Display Window Manager: C:\Windows\System32\WinSAT dwm.

Now we have achieved the following: an unattended installation (though, still showing a GUI) that installs HydraVision and enables the Aero user interface in Vista. But what if we want a truly silent install? Is this possible? Yes, it is. There are two ways of doing this.

First, there is a file called ATISetup.exe in the Bin{64} folder of the Catalyst Display Driver package. If you run this file without any command line options, you will see the following command line options (there are more, but for brevity, which it's already too late for, I'll omit the unimportant ones):

-install: Performs a silent install
-uninstall [all]: Performs a silent uninstall ([all] uninstalls all hidden packages)
-output screen [detail]: Screen outputs basic information to the console while including detail will output more verbose information. Useful for debugging.
-h #### -v #### -b ## -j ###[ddc]: Sets the horizontal resolution, vertical resolution, color depth (or bits per pixel (a/k/a bits per pel)), and vertical refresh rate. Using DDC for the vertical refresh rate tells the driver to get the information from the monitor via DDC or EDID, if the monitor supports it. Most LCDs in use do, as do most CRTs that are left in use. Also, be aware that the documentation for these switches is incorrect: -b only takes 2 digits, and -j can take 3. They have this reversed on their display of the help options (and thus, you can specify 120Hz refresh rate for your CRT if it supports it).

Here's the kicker: you try to run the following command: ATISetup -install -h 1280 -v 1024 -b 32 -j ddc, and it doesn't work. The install occurs, but again, HydraVision is not installed, and when you reboot, the display defaults to a resolution of 800 x 600 @ 32-bits. Again, the problem with HydraVision can be fixed and the installer used, but not the screen resolution. For me, this is back to square one. Why did I go through all of this? To save you the trouble—and to pick on AMD.

So how do I get the driver to install, with all the companion applications, and have the screen resolution set to the desired size and enable the Aero user interface? It comes down to two lowly batch files (or in Vista world, a .cmd file).

First, we need to write the batch (or command) file that will install the driver and companion applications. Apparently, what really happens when you run the Setup.exe file in the root driver package with the -install switch, it just passes it onto the .\Bin{64}\ATISetup.exe installer. If you use the slash (/) switches, then the GUI installer is used (e.g. the GUI installer is shown, but is unattended if you use the switches I outlined above).

Here's the install batch file (I named it install.cmd):

NOTE: You may freely copy and use the batch file source code contained in Figures 2 and 3 of this blog entry without needing to give attribution. I hope someone may find it useful.

Figure 2. Install.cmd source code.

This will (more or less) silently install the driver and all accompanying software that you chose. (NOTE: I removed the following folders from the \Packages\Apps directory: CatalystRegistration (a registration nag-ware) and Blizzard (an Internet shortcut to download a trial version of the game World of Warcraft.) Once this batch file has been executed, you need to restart the computer. (NOTE: if you are using the Microsoft Deployment Toolkit to deploy your operating system, you must tell MDT that the application requires a reboot and let MDT reboot the computer or you will mess up the automated deployment.)

Once the computer has rebooted, your video resolution will be 800x600 @ 32-bit. Unfortunately, Windows still does not have a way to "script" the video resolution through an API. No Windows Script interface, no WMI, no PowerShell. So we are left to "hacking" the Windows registry. Please note that the batch file below has only been tested on Windows Vista. For any other operating system, verify the keys that need to be set (perhaps the resolution switches only work for Windows XP and below?).

@ECHO OFF
ECHO Changing desktop resolution...
FOR /F "tokens=2 delims={}" %%a in ('REG QUERY HKLM\SYSTEM\CurrentControlSet\Control\Video /s /f VolatileSettings') DO SET VIDEOCARD=%%a
ECHO Video Card GUID is: %VIDEOCARD%
ECHO.

REG ADD "HKLM\SYSTEM\CurrentControlSet\Hardware Profiles\Current\System\CurrentControlSet\Control\Video\{%VIDEOCARD%}\0000" /v Attach.RelativeX /t REG_DWORD /d 0 > nul
REG ADD "HKLM\SYSTEM\CurrentControlSet\Hardware Profiles\Current\System\CurrentControlSet\Control\Video\{%VIDEOCARD%}\0000" /v Attach.RelativeY /t REG_DWORD /d 0 > nul
REG ADD "HKLM\SYSTEM\CurrentControlSet\Hardware Profiles\Current\System\CurrentControlSet\Control\Video\{%VIDEOCARD%}\0000" /v DefaultSettings.BitsPerPel /t REG_DWORD /d 32 > nul
REG ADD "HKLM\SYSTEM\CurrentControlSet\Hardware Profiles\Current\System\CurrentControlSet\Control\Video\{%VIDEOCARD%}\0000" /v DefaultSettings.FixedOutput /t REG_DWORD /d 0 > nul
REG ADD "HKLM\SYSTEM\CurrentControlSet\Hardware Profiles\Current\System\CurrentControlSet\Control\Video\{%VIDEOCARD%}\0000" /v DefaultSettings.Flags /t REG_DWORD /d 0 > nul
REG ADD "HKLM\SYSTEM\CurrentControlSet\Hardware Profiles\Current\System\CurrentControlSet\Control\Video\{%VIDEOCARD%}\0000" /v DefaultSettings.Orientation /t REG_DWORD /d 0 > nul
REG ADD "HKLM\SYSTEM\CurrentControlSet\Hardware Profiles\Current\System\CurrentControlSet\Control\Video\{%VIDEOCARD%}\0000" /v DefaultSettings.VRefresh /t REG_DWORD /d 75 > nul
REG ADD "HKLM\SYSTEM\CurrentControlSet\Hardware Profiles\Current\System\CurrentControlSet\Control\Video\{%VIDEOCARD%}\0000" /v DefaultSettings.XPanning /t REG_DWORD /d 0 > nul
REG ADD "HKLM\SYSTEM\CurrentControlSet\Hardware Profiles\Current\System\CurrentControlSet\Control\Video\{%VIDEOCARD%}\0000" /v DefaultSettings.XResolution /t REG_DWORD /d 1280 > nul
REG ADD "HKLM\SYSTEM\CurrentControlSet\Hardware Profiles\Current\System\CurrentControlSet\Control\Video\{%VIDEOCARD%}\0000" /v DefaultSettings.YPanning /t REG_DWORD /d 0 > nul
REG ADD "HKLM\SYSTEM\CurrentControlSet\Hardware Profiles\Current\System\CurrentControlSet\Control\Video\{%VIDEOCARD%}\0000" /v DefaultSettings.YResolution /t REG_DWORD /d 1024 > nul

ECHO Done.
ECHO.
ECHO.
ECHO Enabling Windows Vista Aero User Interface...
REM This command was wrong. It will enable Aero, but will not update the system score.
REM WinSAT dwm > nul
WinSAT formal > nul
ECHO.
ECHO Done.
ECHO.
ECHO.
ECHO ATi Radeon 3100 Graphics card successfully installed and configured!
EXIT

Figure 3. SetVideoRes.cmd source code.

The > nul makes the batch script not output anything to the screen since REG.exe and WinSAT probably use stdout or stderr bypassing the @ECHO OFF command in the batch file. I called this batch file SetVideoRes.cmd. It first uses REG QUERY to determine the GUID of the video card and stores it in a variable. Then it creates several registry entries in the registry pertaining to the display resolution. Finally, it runs the Windows System Assessment Tool to enable the Aero user interface. Once this script has run, the computer needs to be rebooted again so that Windows picks up the new display resolution settings. And finally, there you have it, a completely unattended installation of the Catalyst Display Driver package. Too much work. For Intel, this would have been as easy as calling setup /s /v/qn if it's an InstallShield installer or <driver_installer>.msi /qn /norestart if it were an actual Windows MSI.

I hope this helps someone out there. It took me a whole week, installing the operating system about 25 times to figure this all out. What a pain! I did contact AMD Customer Care, but they basically told me that they provided limited unattended install support and that they only supported unattended installs on Windows Vista for particular ATi products. Poor business practice, in my opinion. Not everyone is a Hewlett-Packard or a Microsoft.

One final note, I just finished a book on microformats on the web. This blog entry is long enough, so suffice it to say, I've tried my hand at a few hCard entries in this post. Not every company mentioned has an hCard entry. I may go back and update this entry later. I mention this only for those who may be looking. I'm going to write more about that in another post.

That's it for now. Sorry it was so long. Take care.

Updates

2009-05-14 - Fixed code in SetVideoRes.cmd in figure 3: Added quotes around the registry key because the keyname has a space. Also removed the warning about testing on Vista. I have tested the code and it does work. However, it should go without saying that anything you take off the Internet should be tested in a secure, isolated environment before being put into production. Also fixed my SetVideoRes.cmd batch file to call C:\Windows\System32\WinSAT formal to make sure that the experience score actually gets updated in the System display window.

It's been a while...

noreply@blogger.com (Craig S.) — Sat, 09 May 2009 19:55:00 +0000

Hello everyone. Well, don't say I didn't give you fair warning about the frequency of posting on this blog.

Anyway, call it bad timing, but I started this blog about 8 weeks before the end of the semester. Four weeks later, of course, all the professors are cramming assignments down our throat trying to get in as much as they can because they realized that the semester is nearly over! To their credit, this semester was extremely compressed, partly due to the way the calendar fell this year and partly due to other reasons which I'm not going to expound upon at this time.

So the last five weeks were really busy and this was my first week back at work in a while as well. In addition, I've been meaning to continue my series of blog posts on the network infrastructure upgrade at work, but issues with VMware have kept me from making any progress on that front as well. I think I have those issues worked out now so that I can document the process.

Coming up...

I don't know how long it's going to take me before I post my next entry (hopefully no longer than a week) nor how long it may be in between posts, but, I hope to keep them coming. Here's what I plan on writing about in the near-term.

Installation of Windows 2003 SBS R2 Premium with SP2

I plan on detailing my implementation of Windows SBS 2003 Premium R2. Why SBS 2003? Well, a couple of reasons:

This is my first ever ground-up network infrastructure deployment. This means that it's taking me a lot longer than it would for an experienced network engineer, especially since I'm figuring this stuff out all for myself. However, I have plenty of networking experience and feel confident in my ability. But if you should see anything that I'm doing wrong or feel I should do differently, I would love to hear from you.
I started with Windows 2003 SBS R2 and have it installed in a testing environment right now. I can't very well just throw everything away to start over with Windows 2008 SBS, even though I would love to. Luckily, my hardware is 64-bit (Pentium D).
I'm writing this blog on a 64-bit Toshiba laptop, but dumb Toshiba only installs 32-bit Vista OSes on their machines (as of late 2008). What gives?? Don't get me wrong, I love this laptop, I just wish I would have had a choice. In addition, the processor in this laptop does not have Intel's VMI, so I can't run a 64-bit guest OS on a 32-bit host. You know how it is, you load up a machine with all your apps (Visual Studio, Office, every other development/networking tool on the planet) and it would take you months to get your machine back to the way it is now if you have to reload (the only way to "upgrade" to a 64-bit OS).

So, I'm stuck with Windows SBS 2003. However, in a later series of posts, I may detail the installation of Windows 2008 SBS when/if I reload. Having said that, at this point, I think I'm going to wait for Windows 7 to come out to upgrade to that. So, then I might as well detail Windows 7 SBS. But that's at least a year out, and by then, I may not be doing anything regarding networking because I'm more of a coder.

Installing/Using Microsoft Deployment Toolkit 2008 (or 2010)

Once I detail my implementation of the core installation of Windows 2003 SBS, I'm going to delve into using the MDT 2008 (formerly BDD 2007) or MDT 2010, if it's out by then, for deploying Microsoft Windows Vista with SP1.

So that's it in a nutshell. That's what you can look forward to over the next few posts.

Re-engineering the Network—from the Ground, Up

noreply@blogger.com (Craig S.) — Thu, 05 Mar 2009 01:05:00 +0000

This post is a continuation of my series of posts related to the network re-engineering project I've undertaken at work. A lot of work has already been done, but there is still a lot that has yet to be done. If you need to get a quality, professional network in place, but don’t want to spend the money (or don’t have the money) to buy the requisite hardware, eBay is a great place to shop. I found much of the hardware that we required at up to 50% off, or more, most of it brand new.

Here’s the hardware that was bought for this project:

3 Dell Dimension 2400 Desktop Mid-Towers (2004)
2 Dell Inspiron 700 Laptops (2004)
2 Custom PC Towers with FoxConn motherboards (Intel 865A chipset) (2004)
1 Dell PowerEdge 860 1U Rack-mount Server (2006)
1 Dell Dimension E520 Desktop Mid-Tower (2007)
1 25U 19in. server rack
1 Dell PowerConnect 5324 1U Rack-mount 24-port Gigabit Managed Ethernet Switch
1 Gruber 48-port CAT 6 Patch Panel
1 3U Rack-mount APC Smart-UPS 3000R
1 Dell 110T PowerVault LTO Backup Tape Drive
1 1U Rack-mount Belkin 8-Port KVM
1 TalkSwitch VoIP PBX Phone System and 12 IP phones of various models
1 Hewlett-Packard AMD-based x64 SFF Desktop (2009)
1 Hewlett-Packard 7650n ScanJet Color Network Scanner w/ ADF

All of the client computers have been upgraded such that the machines contain no less than 1.5GB of RAM (most of the machine’s video cards are so old that they preclude using the Windows Vista Aero user interface anyway, so we won’t need as much memory). The 64-bit machine, however, was upgraded to have 4GB of RAM, as well as the PowerEdge 860 server (since I only have the 32-bit version of Windows SBS 2003).

The software we’ll be implementing is as follows:

Microsoft Windows Small Business Server (SBS) 2003 R2 Premium, which includes:

Microsoft Windows Server 2003
Microsoft Exchange Server 2003
Internet Security and Acceleration (ISA) Server 2004
Windows SharePoint Services 2.0 (which we'll be upgrading to 3.0 SP1
Windows Software Update Services (WSUS) 2.0 (which we'll be ugrading to 3.0)
Microsoft SQL Server 2005, Workgroup Edition (we'll be upgrading to Standard Edition, courtesy of Microsoft Volume Licensing)

Microsoft Office 2007 Professional Plus
Microsoft Windows Vista Business/Enterprise (with SP1)
Microsoft Desktop Optimization Pack (MDOP, from which we'll be using:

Microsoft SoftGrid Application Virtualization
Advanced Group Policy Management (AGPM)
Microsoft System Center Desktop Error Monitoring
Asset Inventory Service
Diagnostics and Recovery Toolset

Trend Micro Worry Free Business Security
Symantec BackupExec 12.5 (soon to be Acronis, too many problems with Symantec, more on that later)
ACT! by Sage 2008
UPS WorldShip 2009
Possibly Adobe CreativeSuite4

There are probably some items I forgot about, but you get the gist.

Where We’ve Been, Where We Are

At this point, we have laid down a new cable plant consisting of CAT 5e cable. We ran two different sets of wires for each drop location, one for data, one for voice.

This was done for a number of reasons. One, VoIP is still not quite there. I can recall on numerous occasions getting a phone call at work from someone who was (most likely) overseas, trying to peddle some wares. The call was so broken up and choppy that I simply told the caller, "Your call is breaking up. Try calling me back on a real landline and we can talk," at which point, I hung up. I don’t have time to waste constantly telling someone to please repeat themselves when I’m probably not going to be interested to begin with. (Usually it’s people calling trying to get me to outsource our IT—for what? Ten client workstations? Please.) Two, after doing other research, I came to the conclusion that while VoIP has made great strides over the last 4 years, it’s not ready for prime time and I don’t want to trust that it’ll work ok over the same network over which data travels. What if someone is downloading a 600MB CD (which would probably be me)? Will the call be dropped, or broken and chopped up? We can’t afford to have that poor of a level of service for our customers since a majority of our business is still conducted over the phone. So, for all of those reasons, we will have VoIP traffic running over its own network, internally. Once the voice traffic leaves the premises, it’ll be traveling over the POTS.

I’m fortunate that our Clydesdale is still running and functioning. That means that I can mess around with the PowerEdge 860 all I want. I have installed and configured Windows SBS 2003 R2 Premium. Perhaps, in a later post, I’ll go through the configuration process. Right now, this is an "experimental" setup. Basically, because I’m installing and uninstalling software, I plan on reinstalling the server when I’m ready to go to production so it is a clean and error free system. But since I have the process pretty much down, this should only take a few hours.

I had only one desktop computer left which is not in production. I really needed another machine. Here’s the problem: Windows Vista cannot be completely managed from Windows Server 2003. Mostly, this has to do with GP administration and management. Luckily, we qualified for a new desktop computer through UPS's Customer Technology Program. So we acquired a Hewlett-Packard small form factor (SFF) desktop machine sporting an AMD 64-bit processor (dual core). So this is becoming my management workstation, for now, and the remaining client that is left will be the test production client whose configuration will be that of all desktops in the organization (less specific drivers for each of the different machines we'll have in use).

Where We’re Going

My company is small, but that doesn’t mean that it can’t benefit from automation, especially when it comes to IT. So I have set the following goals:

An Active Directory-based domain
An internal e-mail server (Exchange Server 2003). Our ISP e-mail is showing its inadequacies.
Central Management and Administration

Group Policy
Application Virtualization

Implementation of a Secure, Managed Desktop
A lightweight helpdesk system (included with SharePoint Services)
Implementation of VPN access (if needed) and/or remote access via Terminal Services, mainly for remote administration

I feel these goals will accomplish a few things for me. I won’t always need to be in my office in order to work. This is important since I am currently only working part time while attending Kutztown University. The users can expect a consistent desktop experience. I can expect a consistent desktop experience—this means I know exactly what’s installed on the desktop, what the security topology is, and therefore, I know better how to diagnose and repair problems when they arrive.

Next Steps

I’ve been using the Microsoft Deployment Toolkit (MDT) 2008 to develop the deployment process. It’s been working quite well. Unfortunately, the documentation is geared more toward large corporate users (even though they say even small corporations will find the tool useful). The toolkit is useful, just there’s not much help. And when you first begin to use it, it’s quite overwhelming. However, over the last few weeks, I’ve really learned the ins and outs of this toolkit, some of which I’ll be sharing over the next few posts. So keep checking back for information on using the MDT 2008.

The State of My Company's Network Infrastruture

noreply@blogger.com (Craig S.) — Wed, 04 Mar 2009 01:37:00 +0000

Ok, so I can’t blame my company for the state of their network. We are a very small company with limited resources. But, our network is getting ridiculously old. Let’s give a quick rundown of what this network is like.

A Compaq Proliant 5000 series server with:

4 x 200 MHz, 256KB Cache, PentiumPro processors
256MB ECC, Registered, Bufferd SD-RAM

CAT 3 cable plant
Microsoft Windows^® 2000 Professional clients (one is still running Windows 98^®!)
Microsoft Office 2000/2003
Trend Micro OfficeScan, Corporate Edition antivirus software
8-port 10Mbit Hub
4-port LinkSys Cable/DSL Router (one of the old ones)
4-port LinkSys WRT54G Wireless Cable/DSL Router

That about sums it up. So this is a pretty old setup. But hey, it was pieced together from about 1992 until about 1999. We only recently (about two years ago) "upgraded" to Windows 2000 on the desktops. For some reason, Windows XP is not liked. I think it’s because it looks radically different from Windows NT/2000. But no matter the case, it’s a moot point now.

A Bit of Momentum

Well, we bought 5 new machines a few years back. I was trying to automate the installation of the client desktops, but it’s so difficult with Windows 2000 (without having Microsoft^® SMS, which is too much for our size company anyway). Since it's nearly impossible to completely automate Windows 2000 (from the installation to client applications) without something like Microsoft^® SMS, I didn’t get very far before the older client machines started dying, one by one. Eventually, all but one of the new machines were put into production loaded with Windows 2000 Professional (manually).

Now, as you can imagine, this has caused lots of problems:

Each system’s operating system configuration is slightly different (thankfully, the hardware is all the same)
The machine is locked down with Local GPOs since we do not have a Windows 2000 Server Active Directory domain.

The disadvantage here is that even local administrators have the GPO applied to their account, locking me out of the system (unless I undo the GPO while I work on the machine and then put it back on).

As alluded to above, there is no real central administration and management of the workstations, making my job 10 times harder.
I no longer have enough computers to have a good test network for the new infrastructure being planned (more on this later).

As for our Compaq Proliant server, we call it the Clydesdale. It’s a big old horse that just keeps going and going, even though it’s battered, bruised, and broken. It’s quite a worrisome thing, actually. Recently, we had to invest in some new (well, not new, but procured from eBay) fans since most of the fans on the server are shot. If the server loses power, sometimes it doesn’t start back up because of a missing (read, not working) fan. Next time it goes down, some new fans are going in that sucker. With those spare parts in hand, we’ll be ok until the migration is complete.

So it’s obvious that that server has got to go, and so it will. About three years ago this coming October, we bought a new Dell PowerEdge 860 server.

The Tipping Point

So the last critical client machine died and I replaced it with one of the new boxes with Windows 2000 Professional. No more than two months later, one of the executives says, "I'd like to run the new version of ACT!" Not only on his desktop, but also on the inside sales desktops. I thought, no problem. So I did my research. Turns out, after getting most everyone upgraded to Windows 2000, the latest version of ACT! does not run on Windows 2000. It requires at least Windows XP. And by this time (late 2007), Windows XP was going to be no longer supported by Microsoft^® in 2009. This was the tipping point.

Up until this time, software was acquired as needed, paying full retail price (or finding legal copies on eBay or at computer shows). After doing some math, I proposed that now is the time we go all in. I learned that you have to play by their rules, or you end up losing big time.

A Philosophical Break

I prefer Microsoft^® products. I don’t love Microsoft^®—I’ve had my share of headaches when it comes to their products. But by and large, they work well. However, I don’t dislike Linux. I think it’s a great and viable OS, just not right for our company. I believe in using the right tool for the right job, and evaluate these criteria on a case-by-case basis.

There are studies that show that even with licensing costs, Microsoft^® software has a lower TCO than Linux (because of having to find someone with the technical acumen to administrate it, and despite claims to the contrary, at some point in time, it will need administration and management). But more importantly, we have software in use that can only run on Microsoft^® platforms that is critical to our business.

Not to belabor the point, but if you have the technical expertise and the system does what you need it to do, who can argue with free software? So I am not against Linux, it’s just not right for us in this instance.

Back to the Story

So after evaluating our options (Linux included), I decided it was best if we entered into a Volume License agreement with Microsoft^®. A new project was born. More on that in my next post.

A Little More About Me

noreply@blogger.com (Craig S.) — Tue, 03 Mar 2009 21:24:00 +0000

If you read my first post, you know that I am currently a student at Kutztown University. I have been fortunate in that my schedule has allowed me to take a full course load while still working two full days a week.

My Professional Life

First, I need to start with the legal stuff. Please read my disclaimer, to which a link can be found at the bottom of this blog in the footer. To summarize for purposes of this post, anything I write here are my own views and opinions and do not reflect the views and opinions of my employer. Again, click the link to read my whole disclaimer. It's sad—the state of this world, that we can't even do anything without having to cover our butts—but I digress.

Now that that’s out of the way, let’s get started. I work for a small manufacturer of temperature sensors used for industrial process control. The company was founded in 1985 and produces thermocouples and Resistor Temperature Devices (RTDs). Perhaps in another post I’ll explain all about thermocouples and RTDs and how they work.

Suffice it to say, the company was started well before the Internet that we know today became popular, even before computer networking became what it is today. Computers were at use since the very beginning. But, throughout the early and mid-1990’s, the computing infrastructure grew and eventually became networked.

In 1994, Microsoft^® Windows NT 4.0 was released, and this is the network operating system still in use today. As you might have guessed, my company has no need to be on the bleeding edge of technology. Having said that, this network is quite old and no longer suits our purposes. That’s where I come in.

My Role

Since my company is a small company, I wear many hats, and not all of them have to deal with IT. I’ve served in the following roles at one time or another (sometimes all at the same time) over the last 5 years:

Inventory Control
Shipping/Receiving
Production Manager
Purchasing
Information Technology

So I’ve been quite busy. These days, however, my focus has been squarely on IT.

I am basically the CTO and/or CIO, but I settle for the title IT Manager. I am responsible for anything that has something to do with computers. That means that I maintain the website (I did not create it, but I maintain it since I don’t have time to redesign it—which it sorely needs.), maintain the network, and write software when it is needed. I am also the in-house desktop publisher. So as you can see, I have a lot on my plate.

Looking Ahead…

So looking ahead, I will be writing about exactly what’s going on with our network infrastructure. I will be making periodic posts on my progress. I won’t only blog about work, however, but until at least June or July, expect a lot of my posts to center around that. Besides, I will have some valuable information to share with others—I promise. So for the sake of trying to keep these posts somewhat short, I’ll be ending this one. The next one will give more information on the network re-engineering effort. Until then, so long.

Biting the Bullet

noreply@blogger.com (Craig S.) — Mon, 02 Mar 2009 19:17:00 +0000

Why I'm starting a blog

I've finally bitten the bullet. Unlike many people, I don't belong to any social networking sites, and until now, I haven't blogged. I never got into MySpace, or Facebook, or any of the others that are out there simply because I don't have time. By the time I got around to thinking about social networking, it has become quite obvious how dangerous social networking can be: from you yourself posting inappropriate content, to your "friends" doing that for you. Many employers now look for you on social networking sites trying to gain a glimpse of who you really are. No thanks. I've got nothing to hide, but I don't want a reason to have something to hide either. Blogging has been around for quite a few years as well. Blogging could be almost as dangerous with all the comment spam, not to mention flippantly posting something that you might otherwis think better of later. But, comment spam can be controlled by not allowing comments (but then, what's the point of blogging?). As for inadvertantly (or regretfully) posting something? Well,you could delete the entry (as long as its whithin a few hours). But the better advice is to simply think before you post. So with that in mind, I've started tihs blog.

I'm so busy, however, that I never have time just to sit down and write for my own desire, let alone anyone else's reading pleasure, which is another reason I never really started a blog prior to now. Not that I have any more time now than I did before, but if you never make the time, you never will. Having said that, blogging is an important endeavor. It enables me to allow my voice to be heard by anyone who wishes to listen. I hope that even if you don't agree with everything I write, you will at least approach what I write with an open mind. I'm willing to listen to other perspectives as well. And if I'm wrong, please be gracious and let me know, as I love to learn as opposed to stumble in ignorance.

But, more importantly, my blog will act simply as an information repository. In today's world where we are constantly bombarded by information, it is becoming increasingly more difficult to remember all those snippets of interesting things I read or hear about without writing them down somewhere. So this blog is as much (if not more so) for my benefit as it is for anyone else's—to help me remember those things I would otherwise forget. If anyone finds some useful information in what I have to write, that's great! I'm glad I could help.

Why is your blog called Discovering Code?

This blog will not have one central topic or theme. This is a blog about discovery, and then trying to remember those things I have discovered. Not everything I blog about will necessarily be related to programming, though much of it will be, as that is my passion. My interests are wide and varying, however—from software engineering to computer engineering, to new hardware arriving on the scene, as well as topics related to science in general. I'm an avid Popular Science reader. In short, there may be many things of interest here to many different readers.

What can you expect from me?

While I would like to say, "Check back often for my latest entries," I can't guarantee how often I will actually post articles on my blog. So please, do check back, but don't expect something new everyday or even every week. I would like to at least write something here once a month.

Who are you anyway?

That's a very good question, and I'm glad you asked. I am currently a student at Kutztown University, enrolled in the Computer Science Software Engineering program. The goal is to (finally) complete my Bachelor's Degree with a Minor in Mathematics, and then continue on to obtain my Master's Degree. My favorite programming language is C#. I have an interest in extending my knowledge in the arena of ASP.NET. Another interest I have, related to programming, is that of compiler theory and construction as well as computer engineering and operating system design (Kutztown University does not have a computer engineering program). I also have a keen interest in most sciences, especially astrophysics, astronomy, and chemistry.

Anyway, that's a little about me and why I'm starting this blog. Like I said, please check back from time-to-time, hopefully I will have posted something useful, if not interesting at the very least.

Discovering Code

Code Contracts and Test-Driven Development

Introduction

An Introduction to Code Contracts

Microsoft & Code Contracts

Using Code Contracts with the Category Class

Code Contract Violations

Code Contracts and Test-Driven Development

You Don’t Write Unit Tests that Exercise Debug Asserts—Why Write Tests That Exercise Your Contracts?

Testing Code Contracts Pre-Conditions is Akin to Testing the BCL

Test-Driven Development with Code Contracts

Code Contracts and Inheritance

Code Contracts and Abstract Class Methods and Interfaces

Keeping Your Contracts DRY

Code Contract Helper Methods

Giving the Analyzer a Helping Hand

Conclusion

Mighty Moose and Contextual (a/k/a Hierarchical) TDD

Introduction

The Test Runner Behind Mighty Moose

AutoTest.Net is Broken

Conclusion

Advanced Test-Driven Development

Introduction

Traditional TDD

Advanced TDD with Context Classes

Introducing the Category Class

The Equality Context Test Class

Even More Nested Context Classes

Conclusion

Mighty Moose a/k/a ContinuousTests

Introduction

Enter Mighty Moose a/k/a Continuous Tests

Getting Mighty Moose to Work with Visual Studio 2013

Cool Blog Post Titled "What is a Full Stack Developer?"

AllMargins 2012 v2.8.x Releases

Extension Option Registry Value Name Clashes

What to expect in the next major release

Announcing the Release of AllMargins for Visual Studio 2012

Generics and Implicit Conversion Operators Create an Identity Crisis

Some Background Information

A New Class is Born

Conversion Operators

Unit Testing Problems Begin

Identity Crisis

Finding Myself

Some Final Questions and Concluding Remarks

.NET Regular Expressions and XML NAME tokens

Extensible Markup Language NAME Tokens

UTF-16 Surrogate Pairs

Enocding a Unicode Character Code Point Above 65535 into UTF-16

Putting it All Together

A Few Closing Remarks

Updating a Visual Studio 2010 Extension for Visual Studio 2012

UPDATE - 16 January 2013

Install the Visual Studio 2012 and 2012 SDKs

Prepare the Source Code for Visual Studio 2012

Update the *.vsixmanifest file

Recompile a Debug Build

Recompile in Release Mode

Enjoy using Visual Studio 2012

Sample Title Marked up Using x-hTitle Microformat Proposal

Sample x-hTitle Formatted Title

Microformats: Empowering Your Markup for Web 2.0

Abstract

In this Book You'll Learn...

Summary of Contents

A New Microformat Propoal: x-hTitle

Comments Regarding the Proposed x-hTitle Pre-Draft Specification

The x-hTitle Proposed Pre-Draft Specification

Editor/Author

Contributors

Introduction

Inspiration and Acknowledgements

Scope

Out of Scope

Format

Abstract

Schema Key

Schema

Extensible Markup Language `NAME` Tokens

Update the `*.vsixmanifest` file

Sample `x-hTitle` Formatted Title

Comments Regarding the Proposed `x-hTitle` Pre-Draft Specification

The `x-hTitle` Proposed Pre-Draft Specification