Murray on .NET

Anagram Code Kata Part 5 – Domain Objects Over Language Primitives

2010-02-20T17:55:00.001-07:00

This post is part of a series on coding Kata, BDD, MSpec, and SOLID principles. Feel free to visit the above link which points to the introductory post, also containing an index of all posts in the series.

In this post, we will discuss some reasons why you might want to avoid using language primitives directly in place of domain objects. Specifically, I have been using String variables and objects to represent words up to this point. Esteban suggested I create a Word class for a few good reasons which I’ll layout for you. Out of sheer luck and good timing, Dru Sellers of CodeBetter.com also wrote on this subject shortly afterward and confirmed Esteban’s reasoning.

Use String Class or Create Word Domain Object?

I mentioned in the previous post that Esteban had suggested creating a Word class instead of just passing around strings everywhere through my application. One good reason is that we don’t own the String class and so further modification to our string-based implementation is difficult because the logic is scattered throughout the application, instead of centralized under the responsibility and definition of one domain class. It is much more difficult to refactor the word-specific logic with its behaviors and attributes spread throughout the code. Even if your Word class doesn’t grow any more beyond a seemingly unnecessary wrapper of the String class, the code is more cohesive and ready for change should the need arise.

But more importantly, you designed the code thinking in a true object-oriented mindset. You have to keep in mind that the String class is someone else’s implementation, and is hardly ever sufficient in and of itself as a domain object within your solution. Think about it, the behaviors that a string object performs are so generic and multipurpose that you likely don’t need two-thirds of the class as defined (and there’s likely a few behaviors you really need that aren’t there). Of course nearly every application on earth makes use of the String class; but because of this fact, it has no meaning in and of itself within any given application. You would have to look at how the stings are actually used within the code in order to understand its unique application within the app’s context. Of course that task of research is much easier for everyone (including the original author of the code) if it’s all encapsulated within a dedicated domain object class. True object-orientation means describing in code form the properties, behaviors, and interactions/relationships of real world objects within your problem domain.

Esteban gave me a great example to illustrate these points. He said that you can always represent money as a decimal (and even when you use a domain object, it’s got to have a decimal language primitive underneath the covers). However, what happens when you need to attach metadata to the amount (like currency denomination), or if you need to change decimal precision? You would have to go through all of the code and make sure your use of decimal language primitives is modified uniformly in order to retain consistency. Also, mathematic operations involving money are hardly ever the same as their counterparts involving standard decimals, because currency deals with discrete values to a certain decimal precision. Typically when the behaviors and properties within our system begin to get complex, we are cognizant enough to create domain objects in order to bring it all under one class. We definitely don’t want to over-architect features and interactions before we need them, but I think there is power in this principle of abstracting away language primitives and instead encapsulating their use within domain objects located in just one place in your codebase. I believe it is one thing we can keep in mind to help guide us to better object-oriented thinking, and avoid language-oriented coding.

As mentioned above, Esteban’s thoughts were confirmed nearly verbatim by Dru Sellers of CodeBetter.com in his blog post that he wrote just a few days after I had the conversation with Esteban. A great coincidence no doubt, and worth a read; here’s the link:

Business Primitives (1/2)

Word Class Implementation

So basically I created the following class implementation and then replaced string with a reference to this new class, Word:

public class Word
{
    private string wordStr = string.Empty;

    public Word(string wordStr)
    {
        this.wordStr = wordStr;
    }

    public override string ToString()
    {
        return wordStr;
    }

    public override bool Equals(object obj)
    {
        return wordStr == ((Word)obj).ToString();
    }

    public override int GetHashCode()
    {
        return base.GetHashCode();
    }

    public int GetCanonicalHashCode()
    {
        char[] letters = wordStr.ToCharArray();
        Array.Sort<char>(letters);
        return new string(letters).GetHashCode();
    }
}

I have defined an overridden implementation for Equals(object) (so that the test assertions and other IEnumerable.Contains() queries work) and GetHashCode() (solely to satisfy a compiler warning). I also moved the GetCanoncialHashCode() method from AnagramGrouper, in order to better encapsulate it as a behavior a Word knows how to do innately.

One other change I had to make was to convert strings into Word objects in our NewlineFileParser, which I accomplished by using an IEnumberable.Select() call as shown below:

return File.ReadAllLines(filePath).Select<string, Word>(x => new Word(x));

Let’s Revisit AssertWasCalled One More Time

Trust me, I am groaning with you, even as I wrote that heading text. The last thing we need is for me to rehash the topic again and flip flop my stance yet another time. Yes, that’s right I’ve changed my mind again. First I couldn’t understand what utility asserting methods were called would have under normal test scenarios. Then I changed my mind that perhaps using it would help my test specifications have clearer intent of what I am asserting. After an email conversation with David Tchepak, I think I’m now back to my original stance. Here is what Dave said that had me reconsidering, and I think it’s pretty sound reasoning (emphasis added by me):

…

“But seeing as you asked for it, here goes. :)

“I try and avoid AssertWasCalled like the plague. Generally I don't care that some method was called, I care that my class does the work it needs to. If that involves calling a dependency then great, but that is not my class' reason for existence.

“I prefer your original approach of stubbing out everything in the setup and having that tested indirectly. One reason I prefer this is I find it makes it easier to refactor: the assertions in my test don't change, the class still does the same thing. However I can add or change dependencies by changing some wiring in the setup, and then make sure I haven't stuffed anything up as my assertions still pass. I prefer that my tests specify what I want, not how it does it. To me, AssertWasCalled reeks of over-specification. The one exception is where I hit the external boundaries of my code, so where I want to send an email or something without side effects that I can test. Then the core of the behaviour is the call itself, so I'm happy to assert on that then.”

And with that I’ll promise to never bring this up again…unless of course I get swayed by someone else. :) In all seriousness, I think this is an interesting discussion and so if you have insight, please share via comment below.

Summary

Please leave your thoughts in the comments below in regard to creating domain objects over using language primitives (or heaven forbid, the AssertWasCalled debate). As far as this coding kata exercise, I need to take a high-level look at where this should go next. Perhaps the next post will tie up loose ends and see how our code performs on large text files as input. It may be that we will need to refactor our architecture to achieve better runtimes. If not, maybe we can still discuss where would could have headed if it had been necessary.

Anagram Code Kata Part 4 – Will it Write My Code for Me?

2010-01-26T22:27:00.001-07:00

In this post, we work on implementing the other main dependency, IAnagramsFinder. In doing so, you will discover that I have been a little naïve with this BDD methodology. Apparently I expected a different experience than what I ran into doing the exercise. In gathering feedback, I had a very interesting discussion about Object-Oriented Programming with Esteban that I will summarize and ask for further discussion from all of you. I’ll also show you one way to debug your code when running the MSpec tests via the console test runner.

New Thoughts on Mocks vs. Stubs

During Part 2 of this series, Tobias left a comment about using mocks and AssertWasCalled, rather than stubs and defining fake responses. I didn’t understand how it would help, as it appeared they would accomplish roughly the same thing. With stubs and fake responses, if you don’t get back the return you are looking for, then you can infer that the dependencies weren’t called since you had previously hard-coded their return values when called. With mocks and asserting methods were called, you directly assert that the manager class did in fact call it’s dependencies.

When I looked more closely into using the AssertWasCalled method in Rhino.Mocks, I noticed that my strategy of using stubs and faked return values wasn’t very explicit in signifying that the ultimate responsibility of the manager class was to delegate to its dependencies. I mean the test context does rigorously stub out the dependencies, but the actual assertions weren’t clear what we were testing. Therefore, I decided to pop in a pair of AssertWasCalled statements (as found below), leaving the rest of the test the same as it was back in Part 2.

It should_result_in_list_of_anagram_sets_and_both_dependencies_should_have_been_called = () =>
{
    fileParser.AssertWasCalled(x => x.ExtractWordListFromFile(filePath));
    anagramGrouper.AssertWasCalled(x => x.FindAnagramSets(wordListFromFile));

    result.ShouldEqual(expected);
};

However, when I thought to simplify the test code by removing most of stubbing setup, it appeared I had to leave most of the stub logic in tact in order to test if anagramGrouper.FindAnagramSets() was called with parameter wordListFromFile, which was one of the stubbed fake responses. The one dependency (the file parser) needed to pass it’s return value to the next dependency (the anagrams finder). I could not think of a way to accomplish testing that the manager class facilitated that without the stubbing logic (fake responses) that I created.

It would be great if someone could enlighten me since I’m such a newbie to mocking and stubbing. Otherwise, I feel the intent of the test is now more clear with the AssertWasCalled checks that I added, even if that I means I’m needlessly mixing stubbing and mocking. But one last question: should I try to stick more closely to the rule of thumb guiding me to stick to one all-encompassing assertion per test if possible? Let me know your thoughts.

Implementing the AnagramGrouper Dependency

So let’s continue onward with some more actual design and code. We are tackling the AnagramGrouper dependency, whose sole responsibility is to take in the parsed collection of words and find anagram sets. Here is the test spec (one thing to note is that in some of my earlier tests for the AnagramsFinder manager class and IFileParser, I had used string arrays liberally; I decided to go with IList<string> collections instead):

public class AnagramGrouperSpecs
{
    [Subject(typeof(AnagramGrouperSpecs))]
    public class when_given_word_list_collection
    {
        static AnagramGrouper sut;
        static IEnumerable<IList<string>> result;
        static IEnumerable<string> wordList = new[] { "wordA", "wordB", "Aword", "wordC" };

        Establish context = () =>
        {
            sut = new AnagramGrouper();
        };

        Because of = () =>
        {
            result = sut.FindAnagramSets(wordList);
        };

        It should_result_in_anagram_sets_collection_of_length_1 = () =>
        {
            result.Count().ShouldEqual(1);
        };

        It should_contain_2_specific_words_in_the_anagram_set = () =>
        {
            result.First().ShouldContain("wordA", "Aword");
        };
    }
}

Here too I have basically two assertions (but split it up differently than last time); should I also try harder to avoid this as well?

When contemplating how to further breakdown this responsibility of finding anagram sets into subtasks, I figure we would need one piece of code that would compare two words and answer whether they are anagrams of each other, and another piece of code that would keep track of the various anagram sets (perhaps a collection or dictionary of string arrays). With what BDD has revealed to me thus far, I figure this means we are going to see two more dependencies (and interfaces, and spec tests) added to the codebase.

So I start with the word comparison task, thinking I could perhaps leverage the String.GetHashCode() method for assigning meaningful value to the list of characters in the string. However, string hash codes give importance to letter casing and order of characters, so a modified strategy would have to be utilized, even though GetHashCode() seems quite close to filling our need.

Now I probably should have come up with this ingenious algorithm all by myself, but…it is what it is and this is the best, most concise solution that I can put together to solve the problem. With that said, I ended up doing some internet searching in order to proof-of-concept my GetHashCode() idea. I came across pure genius in the form of Brian Mullen’s blog post entitled LINQ group by and GroupBy, specifically the second-to-last code snippet. Just String.ToCharArray() the word and then Array.Sort() the resultant array; now turn it back into a string and do GetHashCode() now. (As a side note, we can worry about case-insensitivity later if desired by simply doing a String.ToLower() on the word before getting the hash code.) Now anagrams will have the same hash code (Brian uses the term “canonical”, which I think is very fitting); it’s literally perfect in every way!

So now for the other dependency, I figure we could use a Dictionary<int, IList<string>>, where the key is the canonical hash code and the value is a string list collection representing an anagram set of words. These two dependency implementations are so simple and straight forward that I have a hard time seeing a reason to continue breaking out full-fledged object dependencies with interfaces and Dependency Injection. However, I will make a case for moving the canonical hash code logic outside this AnagramsGrouper class, but that will come later.

So let’s write some code to pass our test/spec:

public class AnagramGrouper : IAnagramGrouper
{
    public IEnumerable<IList<string>> FindAnagramSets(IEnumerable<string> wordList)
    {
        Dictionary<int, IList<string>> results = new Dictionary<int, IList<string>>();

        foreach (string word in wordList)
        {
            int canonicalHashCode = GetCanonicalHashCode(word);

            if (results.ContainsKey(canonicalHashCode))
            {
                results[canonicalHashCode].Add(word);
            }
            else
            {
                results.Add(canonicalHashCode, new List<string>(new[] { word }));
            }
        }

        return results.Values;
    }

    public static int GetCanonicalHashCode(string word)
    {
        char[] letters = word.ToCharArray();
        Array.Sort<char>(letters);

        return new string(letters).GetHashCode();
    }
}

Maybe you noticed already, but there is a bug in my logic. At that time, I didn’t see it and needed to debug the code while running. Setting a debug break point in your code doesn’t work like you’re probably used to, and this is because we’re running the MSpec tests via its console test runner. I had to do some searching to figure this one out, and that’s what we’ll cover next.

How to Debug MSpec Specifications and the Code They Test

After a short ride on the Google super highway, I found a blog post containing a November 2009 comment from Aaron Jensen, author of MSpec, that gave a few possible solutions. I opted to go with the Debugger.Break() solution, which I put at the very top of my FindAnagramSets method. It is a tad awkward because it will show a Windows error dialog box that says the program encountered a problem and Windows is searching the web for a solution. If you wait through that, it will give you an option to debug the program via a Visual Studio dialog where you select the currently running instance of Visual Studio as your debugger instance. You just remove the statement when you’re done (and you’ll really want to remember to remove it from your production code). Does the trick, though it is a bit obtrusive to your code base.

If you haven’t already figured it out, the bug is that my FindAnagramSets method is returning all anagram sets found in the dictionary. An anagram set of just one word is not really an anagram set, which is why our test specification which is based on that assumption failed. The fix is to filter out anagram word sets with less than two words before returning, like this:

// Return anagram sets with more than one word in it
return results.Values.Where(x => x.Count > 1);

That will make the code pass the tests now. Remember to remove the debugger statement we added.

BDD, OOP…WTH?!

Just kidding. But I do want to discuss a reaction I had to BDD after implementing this anagram finding solution. After I completed the code and finished the tests, I was feeling pretty great. But then I started thinking about how I didn’t really go down the path that I felt BDD was originally trying to lead me down with AnagramGrouper, which was to create two more dependencies, just as I had done for the first managing class AnagramsFinder. I mean I felt pretty frustrated because I was digging BDD to this point. I’m not quite sure what my original expectations were, but I might have thought BDD was magically going to right my algorithms for me as well.

I decided to discuss the whole thing with Esteban to get some perspective on the issue. He told me he didn’t know a thing about BDD and how it’s supposed to work, but he figured BDD would lead me to decoupled, cohesive code design, but he couldn’t see how it would aide with algorithmic solutions to the problems at hand. I’m not sure why I was so naïve, but it makes complete sense. I mean these methodologies are designed to keep you disciplined to some proven, guiding principles, but you still need to use your brain and creativity to actually solve the problem. I guess it would help to get some feedback and suggestions from you all in regard to knowing when it is time to switch from BDD architecture design mode to algorithm design mode within the broken down dependencies that handle the very specific sub-responsibilities. Please let me know if you have found some guiding concept or question you’ve come up with that you put to the test in order to lead you into the right coding mindset for that particular context (design or algorithm; or do I even have the right categories?).

Perhaps it’s just that this design process feels so new to me. Maybe I have solely been in the coding, algorithm mindset this whole time throughout my career. Perhaps it will become more natural with practice and experience. I guess it just feels like I’m learning to drive a manual, stick-shift car or something, and I am a little rough with the clutch when transitioning between gears.

To take this discussion further, Esteban made a comment in our conversation about his personal thoughts on these methodologies (like BDD) and Object-Oriented Programming. He has come to believe that we invent these methodologies like flavors of the week “because as programmers we don’t really get OOP.” Perhaps OOP just comes more naturally to his thought process that most people (or he admits it’s possible he could just be completely ignorant), but he feels that there’s really just a few simple rules and guidelines to keep in mind at all times in order to keep your objects behaving like real life objects and not acting like data constructs. I encouraged him to give his theory some additional thought and make it a little more formal by writing it down. He did this and the following is a link to the resultant blog post:

3 Simple Rules to Good Object Oriented Code

Please read through that post and comment on it. His idea needs to be criticized and/or validated. He admits he may have no clue what he’s talking about, but I said that’s why it needs to be put to the test by posting it in the open. We both think it’s an interesting theory, but we’re unsure if it even holds any water. Perhaps Esteban’s theory is too simplistic to be practical for many programmers. Provide feedback and lots of it.

Summary

So I think I need to wrap this post up about now. I think I have raised enough discussion points to write a book, but please do take the time to comment on what I’m doing wrong, what I’m doing right, or how to make the BDD mentality more flowing and natural. I promised to talk about having a Word class as opposed to using primitive strings everywhere, and that will definitely be in the next post. Also, I think our AnagramGrouper class may need some more testing and flushing out of how it should handle spaces, punctuation, casing, and so on.

Thanks for sticking with me thus far.

Anagram Code Kata Part 3 – Use Common Sense

2009-12-18T18:10:00.001-07:00

In this post, we will discuss how far to take the idea of creating mockable contracts via interfaces for testing purposes and to keep responsibilities modular. As I solicited feedback from commenters, I was getting hung up on applying this concept to every object and dependency. We’ll talk about how I’m now thinking that overly strict adherence to the practice can drive you nuts and decrease productivity. It is meant to help guide your design process along rather than hinder it. We’ll finish this post off with one of our two dependencies implemented in an extremely simple manner.

IFileParser Dependency

When we left off last time, we had defined two separate responsibilities that AnagramsFinder was going to push down into its dependencies. As I started to write a specification test for the newly created NewlineFileParser, I realized it would be difficult to stub based on providing a file path to a text file as the only parameter. I began having thoughts that maybe I could break up another pair of dependencies for file parsing, namely obtaining a file stream (or file contents string) from a path and then parsing the file contents into a list of multiple lines. But then again, my first of the two dependencies is still dependent on the physical file system and I cannot get away from this unless I somehow mock up an in-memory file system. This began to feel silly to me as I was hoping I would just use the built-in .NET APIs for file systems and string parsing.

After emailing Dave and Esteban asking for guidance, the revelation I received via these two fine gentlemen is that file parsing is not an essential purpose of this application nor exercise (at least not yet; we won’t be focusing on performance unless it appears to be grossly deficient as we go along). What we could do is write integration tests instead, where we have a set of simple test files sitting in a folder that we run our NewlineFileParser against to ensure it working as we expect. But I don’t think I’m even going to do this at this point. I really do want to get to the core of the application. Plus, I feel certain that I can trust the implementation of File.ReadAllLines() from the .NET Framework.

Unless it needs to be changed further down the road, the following code implementation will likely be sufficient for the remainder of this coding exercise:

public class NewlineFileParser : IFileParser
{
    public IEnumerable<string> ExtractWordListFromFile(string filePath)
    {
        return File.ReadAllLines(filePath);
    }
}

I feel great about this because I haven’t gone insane trying to mock and test everything in sight, nor have I broken up every single responsibility in such small chunks that it becomes tedious. Instead, I have broken up the two core responsibilities of AnagramsFinder which means I can change and test the two dependencies independent of each other and from their manager class. Even though I haven’t written a ton of code yet, I feel the tests specs have driven my design into a cohesive, decoupled design that should prove flexible if requirements change or if I encounter friction later on and need to rethink my design. A flexible architecture for the application is being flushed out based on a “top-to-bottom” design view of the requirements.

Create Stubs or Assert Methods were Called

Tobias Walter left a comment on my last post with some suggestions that I would like to get clarification on and discuss further with my growing audience of three now. He compared some of my implementation to Dave’s implementation on his Favour test driving logic over data post, but the comparison was lost on me. It seemed Tobias was saying that I had gone too far breaking up the responsibilities into such small dependencies. I am unsure what his argument was, but as far as I could tell both Dave and I broke up a managing class into two separate responsibilities so that the more crucial of the two could be tested independently. Also in doing so, we both created stubs that were given specific dummy responses to method calls using Rhino.Mocks. One more comment I would like to say is that I broke the file parsing responsibility away into its own dependency more because of the need to isolate the anagrams grouping than because file parsing is of itself a difficult task. If Tobias or anyone else could try to clarify his argument, that would really help me understand the merits of his suggestions.

Another suggestion that Tobias brought up that I would like to petition feedback on is to use the mocking feature of testing whether a method was called instead of creating a stub programmed with a dummy response. I have to admit, I’m not sure when to use one method over another. I guess I’ve felt in the past that testing whether a method was called seems silly, since it seems odd to have your test know the implementation and inner method calls of the subject under test. But I am now realizing that my stubs appear to be doing the same thing, but with dummy input and output programmed in. If you have an opinion or experience on this subject, please leave some feedback in the comments of this post.

What’s Next?

In my next post I hope to summarize this mocking debate brought up above regarding two differing methods of verifying my manager class is correctly managing its dependencies. I also hope to begin driving out the design and implementation of the AnagramGrouper dependency via behavior specification tests. Thanks and any feedback is greatly appreciated.

Anagram Code Kata Part 2 – Mocking and SRP

2009-11-17T00:59:00.000-07:00

In this post, we will rewrite our first specification/test from the previous post, where we didn’t feel very confident about the direction we were heading. We got some great feedback and will now better focus on test driving logic and not just data; we will also be more careful in extracting the requirements from problem statement and in giving our classes a Single Responsibility (the first of the SOLID principles of Object-Oriented Design). As we are test driving our design from a “top-down” perspective, we will encounter the need for dependencies not yet implemented while creating the higher level classes. Instead of halting our rhythm and progress, we will utilize a mocking framework to stub out non-existent implementations according to interfaces. This also encourages us to use Dependency Inversion (last of the SOLID principles; same link as above) and we can prove the validity of our modules by testing them in complete isolation from their dependencies.

Don’t Focus on Data (Yet) and SRP (Single Responsibility Principle)

I had a feeling I was focusing too much on testing data, and I also knew it seemed to odd to be writing my very first test to be dependent on solving a specific instance of the problem (especially a test case with thousands of words in it), instead of working on solving the problem generally. After some terrific feedback from David Tchepak in the comments of my last post, I now understand that wasn’t my only mistake. I was also trying to give my AnagramsFinder class too many responsibilities (especially with just one ParseTextFile method), namely extracting the words out of the text file and then grouping the anagrams together. Not only that, I also was returning a count of anagram sets when the problem statement specifically asked for output of the anagram sets themselves. Even though this is a simple problem scenario, it can be foolish to make assumptions or simplifications like I did that are not part of the requirements.

Let us first focus on the responsibilities required of our AnagramsFinder class. It needs to parse a list of words out of a text file given the file path and it also needs to group words together into sets that are anagrams of each other. However, we just named two responsibilities; implementing both in the same class would make it less cohesive and therefore less maintainable. This is because our class would have more than one responsibility that could change in the future, and because these responsibilities are in the same class, they could be considered coupled and one could be affected by modifications to the other. All of this train of thought falls under the Single Responsibility Principle from the SOLID principles (see links at the beginning of the post).

To solve this predicament, we will make AnagramsFinder a managing class of dependencies that individually solve these separate concerns. Each of these dependencies will adhere to the Single Responsibility principle, as does this higher abstraction manager class. Its responsibility can be summarized as managing the inputs, outputs, and execution order of its dependencies. We shall name the dependencies directly after each of their responsibilities, namely FileParser and AnagramGrouper. However, I don’t want to go implement these dependencies and throw off the flow of fleshing out the design and logic of my manager class. We are trying to design from a more “top-down” approach, instead of focusing on the lower level data concerns of the solution too early in the design process. To accomplish completing the design of our manager class without actually implementing the dependencies, we will code to interfaces (namely IFileParser and IAnagramGrouper).

DIP (Dependency Inversion Principle)

The advantages of using interfaces are that we abstract out the actual implementation of the dependencies, allowing us to be more modular and less coupled between dependencies. One class is not strongly tied to a specific implementation of its dependency, but rather the general contracts made available by the interface’s defined method signatures. What this really means is that we can swap out actual implementations of the dependency without the consuming class being modified in the least bit. This makes for truly maintainable code, especially when requirements change down the road after version one of the application is up and running. This is what the Dependency Inversion Principle (again, from SOLID) is all about.

We can take this a step further by passing the necessary dependencies into our consuming class at construction. This allows for us to “inject” into the object any implementation of the interface we see fit; this technique is aptly named Dependency Injection (DI). Our manager class doesn’t have to fret about any concrete details regarding its dependencies’ actual implementations, nor about any of the construction ceremony associated with “newing” up and initializing said dependencies. We won’t be using any DI containers (as our dependency needs are very light in this exercise), but the use of the Dependency Inversion Principle does set us up nicely to use a mocking framework so that we can finish fleshing out our tests without implementing any of the dependencies yet.

Mocking Dependencies

We would like to finish the design of our top level AnagramsFinder manager class, but not fully commit to how its dependencies will be implemented yet. We have a general idea of how we want our consuming class to interact with its dependencies via interfaces. Let’s go ahead and look at our interfaces we named earlier:

public interface IFileParser
{
    IEnumerable<string> ExtractWordListFromFile(string filePath);
}

public interface IAnagramGrouper
{
    IEnumerable<string[]> FindAnagramSets(IEnumerable wordList);
}

Now, we could create concrete implementations of the interfaces to be used in our tests that return simple dummy results. An example could look like this:

public class TestFileParser : IFileParser
{
    public IEnumerable<string> ExtractWordListFromFile(string filePath)
    {
        return new[] { "wordA", "wordB", "Aword", "wordC" };;
    }
}

This is helpful because it keeps the one class we are interested in from being dependent on any real logic in its dependencies. We want to be able to test our modules in isolation from any dependencies, so that no secondary or outside influences skew the test results. We are basically providing dummy dependencies to our tests that have no logic that could cause side effects.

However, the software development community has provided tools called mocking frameworks that can create these dependency stubs for you. This can save you from creating concrete interface implementations that have no use except for in testing. The mocking framework I will try out is Rhino.Mocks from Ayende. To get set up, you merely need to download the latest build zip archive, extract out the Rhino.Mocks.dll library to our Libraries folder created in the last blog post, and add a reference to the DLL in our Visual Studio solution. I will next show you how to use Rhino.Mocks as we rewrite our first specification test.

Rewrite of Our First Specification/Test

Armed with SRP, DIP, mocking, a more strict adherence to the actual problem statement, and a renewed focus on “favoring test driving logic over just testing data,” we now rewrite our first specification as follows:

[Subject(typeof(AnagramsFinder), "Finding Anagrams")]
public class when_given_text_file_with_word_on_each_line
{
    static AnagramsFinder sut;
    static IEnumerable<string[]> result;
    static string filePath = "dummy_file_path.txt";
    static IEnumerable<string> wordListFromFile = new[] { "wordA", "wordB", "Aword", "wordC" };
    static IEnumerable<string[]> expected = new[] { new[] { "anagram", "gramana" } };

    Establish context = () =>
    {
        var fileParser = MockRepository.GenerateStub<IFileParser>();
        fileParser.Stub(x => x.ExtractWordListFromFile(filePath)).Return(wordListFromFile);

        var anagramGrouper = MockRepository.GenerateStub<IAnagramGrouper>();
        anagramGrouper.Stub(x => x.FindAnagramSets(wordListFromFile)).Return(expected);

        sut = new AnagramsFinder(fileParser, anagramGrouper);
    };

    Because of = () =>
    {
        result = sut.ExtractAnagramSets(filePath);
    };

    It should_result_in_list_of_anagram_sets = () =>
    {
        result.ShouldEqual(expected);
    };
}

I should mention a few notes about the code. First, we need to add a using Rhino.Mocks statement at the top of our specification class file. Second, our AnagramsFinder instance variable named sut stands for the “Subject Under Test,” a mannerism I picked up from David Tchepak, whom I’ve mentioned several times throughout this post series.

Our use of Rhino.Mocks is found when we call the MockRepository.GenerateStub method against an interface. We then proceed to tell the stubbed object how to behave by specifying dummy return values when given methods of the object are called with given parameters. The last line of our “context” setup is to then inject these two newly generated, stubbed dependencies into our manager class for testing. It’s also interesting to note that none of my parameters and expected outputs really make much sense. This is done on purpose to show that the data really doesn’t matter to this class, as we are not testing the logic of any data processing by the dependencies (remember, test in isolation). It is true that this test really isn’t testing any real logic at this point, and it may even never evolve into testing any real logic either. However, I think the important point is that it aided us in fleshing out the design, which we previously didn’t know how we were going to implement. Not all tests will created equal in regard to validating our logic, but they all will play a part in driving the design of our code. Hopefully these statements are true, and I would love to hear feedback on this topic in the comments.

I also want to touch on the Specification pattern of Behavior Driven Design and testing. Specification tests are commonly set up into a workflow of context establishing, behavior performing, and results asserting. The MSpec framework is designed to encourage this test organization.

Red, Green, Refactor and MSpec Test Runner Output

To make our first test run, we need to create the basic outline of our AnagramsFinder class as outlined in our test. This includes a constructor that takes our two dependencies and an ExtractAnagramSets method:

public class AnagramsFinder
{
    private IFileParser fileParser;
    private IAnagramGrouper anagramGrouper;

    public AnagramsFinder(IFileParser fileParser, IAnagramGrouper anagramGrouper)
    {
        this.fileParser = fileParser;
        this.anagramGrouper = anagramGrouper;
    }

    public IEnumerable<string[]> ExtractAnagramSets(string filePath)
    {
        throw new NotImplementedException();
    }
}

I am using the ConsoleRunner according to the method described in Rob Conery’s introductory MSpec and BDD post, including output to an HTML report. After running our specifications, we get the following output:

Specs in AnagramCodeKata:

AnagramsFinder Finding Anagrams, when given text file with word on each line
¯ should result in list of anagram sets (FAIL)
System.NotImplementedException: The method or operation is not implemented.
   ... Stack Trace here ...

Contexts: 1, Specifications: 1
  0 passed, 1 failed

…and the HTML report:

A highly encouraged tenet of Test Driven Development is the practice of “Red, Green, Refactor.” It is meant to denote the evolution of the results and state of your tests. You are encouraged to write the test and then do the minimum work necessary to get the code base to compile and run. You are first running your test in a control state where you know it should fail. Most test runners will show the color Red in regard to failed tests, and thus the name of the first step. Your next stage is to implement the code to make the test pass and turn the output color to Green, commonly indicating passing tests. The Refactor stage is a time to pause and see if any code can be reorganized or simplified. Then “rinse and repeat as necessary”, an applicable instruction from shampoo bottles.

To make our test pass, we implement real logic to coordinate the calls into our dependencies, like so:

public IEnumerable<string[]> ExtractAnagramSets(string filePath)
{
    var wordList = fileParser.ExtractWordListFromFile(filePath);
    return anagramGrouper.FindAnagramSets(wordList);
}

…and the successful outputs of our test runner:

Specs in AnagramCodeKata:

AnagramsFinder Finding Anagrams, when given text file with word on each line
¯ should result in list of anagram sets

Contexts: 1, Specifications: 1

Final Thoughts and Questions

So what do you think of the new test? Are we better able to see the Single Responsibility of the AnagramsFinder manager class? Are we more inline with solving the actual problem statement? Your feedback would be much appreciated.

In the next post, we will begin work on test driving the design and implementation of the dependencies…unless of course I get feedback that I should be focusing on a different area first or that this last rewrite still needs more help.

Anagram Code Kata Part 1 – Getting Started

2009-11-12T15:03:00.001-07:00

This post will provide resources that serve as an introduction to the MSpec BDD testing framework. We will also set up our Visual Studio solution, explain the Anagram Code Kata problem statement, and write our first specification and test.

Machine.Specifications (MSpec)

The author of this BDD testing framework is Aaron Jensen of CodeBetter.com. Probably the best introduction to the framework (and lightly touching on general principles of BDD) is Rob Conery’s post entitled Make BDD Your BFF. MSpec is hosted on GitHub using the Git source control software (and here is the link for the repository again). Download the code and build it to get the necessary libraries that you need into a Bin folder. My MSpec libraries are a few months old, as I haven’t upgraded my source since my initial download back then. I have not set up TestDriven.NET and am not sure it will be necessary for this simple coding exercise. I am using NUnit for the actual testing framework underneath MSpec; the following article may be of interest to you if you would like to use a newer version of NUnit than what MSpec targets:

Using Latest NUnit Version with MSpec

MSpec helps you organize your code into Specifications, a core BDD concept. It is inspired by early BDD testing frameworks like Ruby’s RSpec. The syntax and arrangement can be a little odd for a static language like C#, but I think I like the direction it is heading. Again, the best way to get familiar with the syntax, set up the MSpec Test Runner, and configure HTML reporting output is to read Rob’s introductory post on BDD and MSpec.

Setting Up the Visual Studio Solution

Let’s begin by creating a C# console application named AnagramCodeKata targeting .NET Framework 3.5. The solution name (and solution folder) will be the same. For our dependencies on MSpec (and NUnit), I have created a physical file system folder named Libraries and made it a sibling folder to the project’s physical folder (same level as the solution file). That folder contains the following DLL libraries from the Bin folder of the compiled MSpec source code:

CommandLine.dll
Machine.Specifications.ConsoleRunner.exe
Machine.Specifications.dll
Machine.Specifications.NUnit.dll
Machine.Specifications.Reporting.dll
nunit.framework.dll

Then within our Solution Explorer, we only need to make references to 3 of these libraries (namely Machine.Specifications.dll, Machine.Specifications.NUnit.dll, and nunit.framework.dll). I have also created two folders within our project in Solution Explorer, naming them Reports and Specifications. The Reports folder will contain the HTML-generated report of running our tests every time. The Specifications folder will hold our specifications and tests. This is what our current Solution Explorer looks like now:

Also notice the MSpecRunner button at the top, which I’ve created to execute a custom External Tool that points to Machine.Specifications.ConsoleRunner.exe and passes in the appropriate parameters. This helpful setup was put forth by Rob Conery in the link to his introductory blog post that I provided above.

Anagram Problem Statement

So let’s go ahead and look at the Anagram problem we are trying to solve. Here’s a quick summary of what we are trying to accomplish:

“The challenge is fairly simple: given a file containing one word per line, print out all the combinations of words that are anagrams; each line in the output contains all the words from the input that are anagrams of each other.”

Unfortunately, Dave Thomas’ wordlist.txt link is broken on his blog post, and when responding to commenters asking for a fixed link to the text file, he pointed us all to some website that aggregates links to several word lists from around the Web. Many of us readers wanted to know the exact word list file he used so that we could compare our results to his. In his post, he states that there should be 2,530 sets of anagrams and 5,680 total words participating in those anagram sets. The tough part about this is that we’ve got to have the same word list text file. I searched the web and found a few, but I only found one that might be the same list. It is from some guy’s personal GitHub repository:

http://github.com/krist0ff/code_kata/tree/ba975c3a64f11a81db2f3716b40de046f1ca7ef4/kata6

If you’re visiting this blog post, months or years after it was originally written, I obviously can’t guarantee this file will still be out there. You can try emailing me or commenting here and I can hopefully send it to you via email if I still have it. But more importantly, as we progress with this series, we’ll find out if it’s even the right word list or not.

Lastly, I’d like to look at the objectives for the coding kata that Dave Thomas outlines:

“Apart from having some fun with words, this kata should make you think somewhat about algorithms. The simplest algorithms to find all the anagram combinations may take inordinate amounts of time to do the job. Working though alternatives should help bring the time down by orders of magnitude. To give you a possible point of comparison, I hacked a solution together in 25 lines of Ruby. It runs on the word list from my web site in 1.5s on a 1GHz PPC. It’s also an interesting exercise in testing: can you write unit tests to verify that your code is working correctly before setting it to work on the full dictionary.”

I don’t think we’ll focus on runtime as much, but we’ll certainly revisit our algorithm as necessary if we have unacceptable wait times for the code to finish. To complete this section, let’s go ahead and add the wordlist.txt to our solution at the root of of our Project node.

How About Some Actual Code?!

So let’s now start off by creating our first specification. I have created a new C# file named AnagramsFinderSpecs.cs under our Specifications folder in our solution. I attempted to write our first test, but already feel like I’m not inline with “favoring test driving logic over just testing data.”

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

using Machine.Specifications;

namespace AnagramCodeKata.Specifications
{
    [Subject(typeof(AnagramsFinder), "Finding Anagrams")]
    public class when_given_text_file_with_word_on_each_line
    {
        static int result;
        static AnagramsFinder sut;

        Establish context = () =>
        {
            sut = new AnagramsFinder();
        };

        Because of = () =>
        {
            result = sut.ParseTextFile("wordslist.txt");
        };

        It should_result_in_count_of_2530_anagram_sets = () =>
        {
            result.ShouldEqual(2530);
        };
    }
}

If you can’t make out the funky structure and syntax, again refer back to Rob Conery’s introductory post to all of this stuff that I link to at the top. He does a great job of explaining what’s going on here.

Also, please remember that I have no clue what I’m doing and I’m just trying to copy people who know what they are doing. I am hoping that I’ll be corrected by those who have a better idea of how to approach all of this. This is a good stopping point because of my desire for feedback and the feeling of uncertainty I’m already getting.

Seriously, please guide me in the right direction or validate where I’m headed, because even I’m not sure where that is yet. I will say this, I’m pretty sure I shouldn’t be reading in wordslist.txt yet, and that this might be where I need to start using a mocking framework.

Stay tuned, there’s more to come. I just can’t tell what it will be about yet. It’ll still be fun though, I promise.

Custom Setup Bootstrappers

2009-11-11T15:03:00.001-07:00

At work, we have a line of desktop products for one of clients installed on the user’s Windows machine via MSI installers. We use Visual Studio Setup Projects to create the MSI installers. Visual Studio also provides the ability to create setup bootstrappers to make sure the user has all the prerequisites needed for the MSI install technology and any dependencies required by your desktop product. These bootstrappers are unmanaged code, because you can’t always depend on the .NET framework already being there (at least not until everyone is off of XP and lower). I have developed a solution that has worked for the last year or more, but has felt clumsy and slapped together. Recently I found the open source project called dotNetInstaller which has better provided me with the control and flexibility I need for custom logic during bootstrap and install time. I’ll first introduce you to my “hack” solution.

It has been difficult for me to find ways to tie into the bootstrapper logic workflow to add in custom logic during installs, and Visual Studio is very rigid in its flexibility and basic in its configuration options in this regard. Until recently, I had settled on writing managed, C# code for this custom logic meant to run before or after the MSI installer, and then creating another unmanaged setup.exe bootstrapper to ensure the .NET framework was installed just so that executable could run. So the user would run this new unmanaged setup.exe bootstrapper (making sure .NET framework was installed), which would then call my managed custom logic executable, which would then call the MSI installer’s unmanaged, Visual Studio-generated setup.exe bootstrapper (ensuring more prerequisites were installed), which would then finally install the MSI, and which would then lastly return to my managed custom logic executable for any post-install, clean up logic. I describe this solution in full (and how to generate the same bootstrappers that Visual Studio creates using MSBuild outside the IDE) in a StackOverflow.com answer that I submitted:

http://stackoverflow.com/questions/1106768/how-can-i-reverse-engineer-an-installer-that-was-written-with-ghost-installer/1121846#1121846

Well, recently I found the dotNetInstaller project on CodePlex.com and have found it to be the control and flexibility I need for custom logic when bootstrapping installers. Not only does it give you great control over prerequisite install order, it also gives you the ability to run code after MSI install and to also filter on CPU architecture types, OS versions, and other registry or file system conditions. I have currently setup branching scenarios for the prerequisites based on if the user has a 32-bit (x86) or 64-bit (x64) OS. This utility will even let you brand the bootstrapper with a banner and icon, which is a change of pace from the plain and unlabeled bootstrapper that Visual Studio and MSBuild produce.

If you have custom bootstrapping needs, I have to highly recommend you give dotNetInstaller a look. Hopefully it will prove as flexible and powerful for your needs as it has for mine.

Anagram Code Kata – BDD & MSpec

2009-11-10T21:32:00.003-07:00

Many forms of martial arts utilize the kata as a means for detailed, focused practice and training. The power of this practice comes from repetition and focus on simple fundamentals, “while attempting to maintain perfect form.” The principle goal is to “try out different combinations of techniques in a safe, practice environment to ultimately find out how to defeat your opponent”. In the last few years, this concept has taken hold within the software development world in the form of Code Kata, a phrase coined by Pragmatic Programmer Dave Thomas (and here is his blog dedicated to the Code Kata).

My inspiration for all of this is David Tchepak’s Calculator Kata series of posts. Hopefully he will stop by and provide some helpful guidance and advice. I have selected the Anagram Kata (code kata number 6) for me to practice. My goals for this series of posts are:

To practice coding and share my learning experience with you, while also soliciting feedback and suggestions.
To more fully understand the concepts driving Behavior Driven Development (BDD) via a testing framework designed for such a practice, namely MSpec.
To keep to the SOLID principles of Object-Oriented Design, especially in favor of test driving logic over just testing data.

Below I will keep an updated list of blog posts in this series. Hope you enjoy it!

Trying Out SyntaxHighlighter

2009-10-23T19:54:00.006-06:00

This is just a test post to see if I'm smart enough to add the javascript SyntaxHighlighter to my blog. ;)

public int ScoreDice(int[] selectedDice)
{
    int score = 0;

    foreach (IScoringCombo scoreCombo in ScoringCombos)
    {
        IEnumerable<int> satisfyingIndices = scoreCombo.SatisfiedBy(selectedDice);

        if (satisfyingIndices.Count() > 0)
        {
            score += scoreCombo.ScoreDice(selectedDice);

            // Remove the dice at satisfyingIndices from selectedDice collection so not double-scored
            selectedDice = selectedDice
                .Select((value, index) => index)
                .Except(satisfyingIndices)
                .ToArray();
        }
    }

    return score;
}

Web Deployment Tool

2009-09-29T17:45:00.001-06:00

It appears that the IIS team at Microsoft has officially completed a 1.0 version of the deployment utility I mentioned at the end of my previous post about Visual Studio Web Deployment Projects almost two years ago. It includes a command-line tool named MSDeploy that helps with deploying and syncing web projects across all of the web servers in your server farm. The installation also includes all kinds of packaging and deployment features that seem really handy. You can even do migrations from IIS 6 to IIS 7 or package your apps to be distributed via the Microsoft Web Platform Installer.

I thought that maybe the tool creates MSI installers, but it appears the package may actually just be a ZIP file that you can import and export through the IIS Manager or various other command-line tools or PowerShell Cmdlets.

Here is the page where you can read more about the toolset and download the installer: http://www.iis.net/extensions/WebDeploymentTool

Variable Declaration Restrictions

2009-09-23T16:09:00.000-06:00

I came across a surprising restriction on variable declarations that I thought I would share.

My own investigation into C# was prompted by an answer given to a Stack Overflow question regarding an odd Objective-C compiler error. The answer seemed to allude to a language specification somewhere that doesn’t allow variable declarations in one-liner embedded statements of control structures (loops, switch statements, if-else statements, etc.). Not only that, Objective-C wasn’t unique in this restriction; it appears Java and even C itself have had this restriction for quite a while as well.

Naturally this got my curiosity going and I decided to see if C# had also carried over such a restriction. The answer is yes; it appears that Java, C#, and Objective-C have all kept this language restriction from their common ancestor C. Let’s get right to what it looks like:

The red-underlined errors read “embedded statement cannot be a declaration or labeled statement” and the green-underlined warnings read “the variable ‘i’ is assigned but its value is never used.” You’ve probably seen the warning quite a few times before, but the compiler error really caught me by surprise. I mean it makes sense that declaring a variable in the one-line body of a control structure is pointless, as it would immediately go out of scope (and usefulness) after declared. But I thought it odd for the compiler to actually deny such a program statement, as if it put the compiler in an invalid state or maybe it was somehow dangerous.

One thing I do want to point out that appears to be different from the other languages (or at the very least Objective-C) is that the variable declaration is allowed in the switch statement, as illustrated in the image above.

To figure out why this isn’t allowed, I decided to actually look into the C# 3.0 Language Specification to see if there were any comments or explanations regarding this issue. I ended up finding the C# language grammar in Appendix B. I was able to parse through the grammar and find this restriction in the grammar itself. Take a look:

B.2.5 Statements

statement:

labeled-statement
declaration-statement
embedded-statement

embedded-statement:

block
empty-statement
expression-statement
selection-statement
iteration-statement
jump-statement
try-statement
checked-statement
unchecked-statement
lock-statement
using-statement
yield-statement

block:

{ statement-list_optional }

statement-list:

statement
statement-list statement

...

selection-statement:

if-statement
switch-statement

if-statement:

if ( boolean-expression ) embedded-statement
if ( boolean-expression ) embedded-statement else embedded-statement

switch-statement:

switch ( expression ) switch-block

switch-block:

{ switch-sections_optional }

switch-sections:

switch-section
switch-sections switch-section

switch-section:

switch-labels statement-list

switch-labels:

switch-label
switch-labels switch-label

switch-label:

case constant-expression :
default :

...

You’ll notice that there is the concept of a statement and an embedded-statement; also note that statement is a superset of embedded-statement, adding two other types of statements: labeled-statement and declaration-statement. If a particular grammar rule requires an embedded-statement, then those two latter types of statements are not allowed in that context. If we wanted to allow those two statement types, our grammar rule should specify the generic statement category instead.

Also noteworthy is that an embedded-statement can resolve to a block, which includes braces around a statement-list. A statement-list is one or more statement entities, which would now allow us to use the two statement types excluded from embedded-statement.

Something interesting that is not included in the grammar snippet above, the following statement constructs (and language keywords) require the block statement construct, bypassing the option of a grammar resolution to embedded-statement directly and allowing you to leave off surrounding braces: try, catch, finally, checked, and unchecked.

Almost all of the other statement constructs allow you the option of a one-liner embedded-statement (or which can be resolved into a block), including if, if-else, while, do-while, for, and foreach. The one surprising exception is the switch construct, which allows for a statement-list after each switch-label. As a side note, this allows you to put useless braces (via block) around your statement-list (or anywhere inside it) after any of your switch-label statements if you wanted. But back to the point, these facts explain the existence of (and in one case, lack of) compiler errors regarding embedded statements in the code screenshot near the top.

Now you will know exactly what the compiler means when it gives you the error that an “embedded statement cannot be a declaration or labeled statement.”

BeginInvoke Methods and OneWay Attribute

2009-05-21T16:29:00.001-06:00

In a previous post I talked about Windows Forms UI Threading using delegates. Recently I needed to replicate what I had learned, and I happened to do so without reviewing my notes in the former blog post. Apparently I didn’t remember everything I had learned and became confused over thread invocation techniques, introducing a bug into my thread messaging. The UI thread was blocking while the background worker thread was processing.

The cause was related to figuring out which BeginInvoke method to call when kicking off the worker thread, the BeginInvoke of the Form object or the BeginInvoke of the delegate. The answer is the BeginInvoke method of the delegate. All of the examples linked to in the previous post had it right, but I got it mixed up with making Invoke or BeginInvoke calls from the background thread using the Form object’s version of these methods. If you don’t care whether your messaging from the background thread is synchronous or asynchronous, then you can use either methods and you can use the ones from the Form object.

The problem is using these Form object methods in order to kick off your background worker thread. The description of the BeginInvoke method on the Form object states that it “executes the specified delegate asynchronously on the thread that the control’s underlying handle was created on.” I translate this to mean that calling your Form object’s BeginInvoke will process on your UI thread. Apparently the delegate BeginInvoke method has no such wording in its description.

Rereading this MSDN article from the former post and reading the Form object’s BeginInvoke method description which I quoted above set me straight and got rid of my blocking UI problem (again).

During this research session, I came across another informative resource when trying to figure out what was meant by potential resource leaks when using BeginInvoke with out later calling EndInvoke. From reading the article, I gather you can substitute the EndInvoke call with the OneWay attribute on the method being invoked, as long as it has a void return signature and no ref nor out parameters. Please let me know if my interpretation is wrong. I added the attribute to my code in the applicable spots and have seen no side effects of doing so. Here is the article on read mentioning this attribute:

Defensive Event Publishing in .NET – Part I

PowerShell 1.0 for Windows XP

2009-03-24T14:08:00.001-06:00

I just noticed in today's Tuesday round of Microsoft Updates that there is an optional software download for PowerShell 1.0 on Windows XP. PowerShell has been one of those things that I really want to learn, but just haven't devoted the time. I desperately would like to replace my use of the Command Prompt with Windows PowerShell.

PowerShell really is more than just your regular Command Line Interpreter that you have been used to, especially compared to the Windows Command Prompt. You get the power of the command line shells that you may have tried out in Linux environments, but it really does go beyond those as well. PowerShell is (from Wikipedia) "Microsoft's new extensible command line shell and task-based scripting technology." Here is a quote from an MSDN document that better explains the advantages PowerShell brings:

"Unlike most shells, which accept and return text, Windows PowerShell is built on top of the .NET common language runtime (CLR) and the .NET Framework, and accepts and returns .NET objects. This fundamental change in the environment brings entirely new tools and methods to the management and configuration of Windows.

"Windows PowerShell introduces the concept of a cmdlet (pronounced "command-let"), a simple, single-function command-line tool built into the shell. You can use each cmdlet separately, but their power is realized when you use these simple tools in combination to perform complex tasks. Windows PowerShell includes more than one hundred basic core cmdlets, and you can write your own cmdlets and share them with other users.

"Like many shells, Windows PowerShell gives you access to the file system on the computer. In addition, Windows PowerShell providers enable you to access other data stores, such as the registry and the digital signature certificate stores, as easily as you access the file system."

If you want to know more about PowerShell, I would suggest the following readings:

Also, James Kovacs from CodeBetter.com has been doing a series of posts on the basics of PowerShell that is a great light introduction to how a developer would find the tool most useful. Here are two of the starting posts from that series:

The "Yield" Keyword in C# (AKA Execution Control Hot Potato)

2009-03-02T17:51:00.000-07:00

I actually read about this topic a while back when I saw a C# code sample containing an unfamiliar keyword -- yield. Well just today I saw another code sample using this keyword again, and had since forgotten everything I had learned. As I Googled the topic again, I happened across the same article I read back then, a terrific blog post by Joshua Flanagan. Here is a link to Joshua's simple introduction to the yield C# keyword:

The power of yield (return)

I would also suggest the following MSDN article as well:

yield (C# Reference)

I'll give you the gist of this .NET 2.0 feature. If you have a method that returns an iterative collection and the consumers of your function will only need foreach, read-only access to that collection, then it is good practice to have your method return the universal IEnumerable collection (as opposed to you arbitrarily selecting an implementation-specific collection to be forced upon the consumers of your code). In C#, when you are returning an IEnumerable collection from a method, you are allowed to use the yield keyword in order to transform your method into what Microsoft calls an "iterator block". Here is a quote from the MSDN article I mentioned above to explain this phrase and the yield keyword:

"The yield keyword signals to the compiler that the method in which it appears is an iterator block. The compiler generates a class to implement the behavior that is expressed in the iterator block. In the iterator block, the yield keyword is used together with the return keyword to provide a value to the enumerator object. This is the value that is returned, for example, in each loop of a foreach statement. The yield keyword is also used with break to signal the end of iteration."

You are essentially building an enumerator (or iterator), and with each iteration of your foreach loop in the calling, consuming code, you are executing your method containing the iterator block until it reaches a yield return statement. At this point, only one item at a time in the collection is returned back to the consuming foreach loop for immediate logic execution by the body of the loop. On the next iteration of the consuming foreach loop, the method containing the iterator block will be called again and another single item in the collection will be returned for similar logic execution.

This game of execution control Hot Potato has its benefits, in that you can stop the flip-flop of execution control when the music has stopped. In this analogy, I am comparing the "music stopping" to your code satisfying some logic that makes the rest of your foreach loop iterations unnecessary (perhaps you have found the one item in the collection you were looking for by meeting the sufficient requirements of an if statement). The benefit is that when you break out of the consuming foreach loop before completing the iterations, you prevent wasteful code execution and memory use. This feature prevents one piece of code from fully populating a potentially large collection of items, just to have another consuming piece of code iterate partially through the list and then prematurely exit. Consider the savings especially when adding each item to the collection may be computationally intensive or if each item in the collection is itself a very large data structure. In the Hot Potato analogy, this would be as if the kids in the circle who didn't touch the "hot potato" never existed in the game, saving floor space and unnecessary tosses to people you don't really want to target for humiliating removal from the game.

For good sample code snippets of using the yield keyword, see the links provided above.

I hope to identify situations in the near future where I could benefit from using this C# keyword. Hopefully then I won't forget a year down the road from now and then have to re-search the internet for Joshua's blog post and the MSDN article to remind myself what I already learned.

FOLLOWUP (03/26/09): So I'm not sure how I missed it, but it took reading a very recent article by Scott Mitchell of 4GuysFromRolla.com to understand the real reason the yield keyword was introduced. The introduction of this keyword in .NET 2.0 was most helpful in the case of fulfilling the requirements of implementing the IEnumerable interface, which typically required you to create a sub-class that implemented IEnumerator. In many cases, it allowed you to take about 50 lines of code and turn it into 2 lines of code using the yield keyword. The introduction of LINQ brought heavy reliance on enumerating using the yield keyword in order to pipeline query operators together. Scott Mitchell takes you through this whole journey, tying all of the loose ends together to create a complete history of this keyword and how it's most commonly utilized. Please visit the following article to get the whole picture:

An Extensive Examination of LINQ: The Ins and Outs of Query Operators

SQL Server Express 2005 Remote Connections

2009-02-19T10:36:00.000-07:00

I developed an ASP.NET site connecting to a local SQL Server Express 2005 instance on my development box. To further my informal testing, I wanted to host the site under IIS 7 on a Windows Server 2008 box, but I wanted to just use the same database remotely. I got the following error message when the site tried to hit the database:

"An error has occurred while establishing a connection to the server. When connecting to SQL Server 2005, this failure may be caused by the fact that under the default settings SQL Server does not allow remote connections. (provider: Named Pipes Provider, error: 40 - Could not open connection to SQL Server)"

Apparently SQL Server Express 2005 is not automatically configured for remote access during installation (which really isn't surprising as it is the Express version). Remote connections can be enabled though with a few relatively painless steps. See the following link for the procedure:

Configuring SQL Server Express 2005 for Remote Access when SQL Server does not allow remote connections

Hope this is helpful.

IIS 7 and ASP.NET Providers (Membership, Roles, and Profile)

2009-02-17T17:38:00.000-07:00

I talked at length about the ASP.NET Provider Model pattern and the ease of implementing several built-in services you can have for free with ASP.NET 2.0 in my previous series of posts. In this post, I will be discussing the advantages of using the ASP.NET Provider system under IIS 7 found in Windows Vista and Server 2008. I will also talk about an issue with using this Provider system to try and add authentication to an ASP.NET website that contains non-ASP.NET content, like static HTML pages. I think I'll start with the discussion about non-ASP.NET content first.

IIS 7.0 Integrated Pipeline

Since I don't really understand much about ISAPI filters and such, I'm just going to quote stuff from random pages on the official Microsoft IIS site:

"IIS 6.0 and previous versions allowed the development of .NET application components via the ASP.NET platform. ASP.NET integrated with IIS via an ISAPI extension, and exposed its own application and request processing model. This effectively exposed two separate server pipelines, one for native ISAPI filters and extension components, and another for managed application components. ASP.NET components would execute entirely inside the ASP.NET ISAPI extension bubble and only for requests mapped to ASP.NET in the IIS script map configuration.

"IIS 7.0 integrates the ASP.NET runtime with the core web server, providing a unified request processing pipeline that is exposed to both native and managed components known as modules."

and...

"This allows developers to fully extend the IIS 7.0 server with the richness of ASP.NET 2.0 and the .NET Framework, instead of using the lower level IIS C++ APIs. Existing ASP.NET applications also immediately benefit from tighter integration using existing ASP.NET features like Forms Authentication, Roles, and Output Caching for all content."

Note the last three words there: "for all content." When I started this endeavor to implement the ASP.NET Provider system, I didn't realize that it would really only apply to ASP.NET content and pages. I didn't realize on IIS 6 I would have to fiddle with ISAPI filters and content filters to make my implementation work. And when I tried to doing a mapping (like *.html to the ASP.NET ISAPI DLL), I either didn't do it right or it just isn't very reliable and stable; here is a link to the thread I followed in trying to make the appropriate changes in IIS 6. I will note however that UltiDev's Cassini Web Server can host such a site with absolutely no extra modification, where even IIS 7 required a little configuration.

By default in IIS 7, an application pool runs using the Integrated mode for the Managed Pipeline configuration. But there is also the option of Classic mode, which is helpful if you are needing strict compatibility with how you ran a website under IIS 6. In many cases, however, an existing ASP.NET website runs under Integrated mode without any problems.

Configuring an ASP.NET Website to Run on IIS 7

First, I think I will point you to a great video and document on Microsoft's official IIS site that explains everything you really need to know. Then I will emphasize a few of the important points and also a gotcha or two. Here are the links you should reference:

The video above is also a terrific introduction to IIS 7. Below is a screenshot of IIS's UI for configuring a website:

Notice the ASP.NET section and how it's able to use your Providers to bring back Users, Roles, and Profile data back from the database. This UI reads from and writes to your Web.config and is really slick in my opinion.

The only real "breaking change" for running your website under IIS 7 is the fact that your Web.config might need a little migration to be compatible with Integrated mode. Apparently IIS gives you helpful error messages if it detects you haven't run through the migration yet. The two most common things that ASP.NET websites have that require this migration are if you have declared httpModules or httpHandlers in your Web.config. The fix is to either copy or move these sections under system.web to their corresponding system.webServer sections. If you duplicate the sections, then you should be able run under both Integrated and Classic modes without any problems. You can even still run on IIS 6 I believe, as IIS 6 will ignore this new section called system.webServer which is IIS 7 specific. IIS 7 even provides a utility that can perform this migration for you; here is the what you would type in a Command Prompt:

%windir%\system32\inetsrv\APPCMD.EXE migrate config <Application Path>

...where <Application Path> would be something like "Default Web Site/" or "Default Web Site/someApp". If you manually migrate your Web.config and are still getting migration error messages, here is a snippet you can add right under the system.webServer node to disable the error message:

Also, I want to make note of something I couldn't get to work that they showed in the tutorial video. At about the 13:50 mark in the video, they go into the Modules section of the UI. These are the modules of the IIS pipeline for both managed .NET code and unmanaged code. In order to make their video file hidden behind ASP.NET Forms Authentication, they change a property on two authentication modules to allow these modules to execute on non-managed content as well. However, this did not work for me for some reason when I was trying to secure HTML pages behind Forms Authentication. What did work for me (and may have been a drastic solution) was to put the following attribute on the modules node under system.webServer:

I believe the issue in my case was their was another few managed modules that I needed to clear that checkbox for in the UI. But I didn't take the time to find out which ones I was missing and opted for the drastic solution. I will also say there is a way to configure these managed modules through your Web.config so you don't have to have your IT Admin configure properties manually in the UI. In fact, it seems that much of IIS 7 configuration for your website can be done this way.

A Few Error Messages (and Their Solutions)

If you get error messages while using the IIS Manager user interface like this...

"This feature cannot be used because the default provider type could not be determined to check whether it is a trusted provider.

"You can use this feature only when the default provider is a trusted provider. If you are a server administrator, you can make a provider a trusted provider by adding the provider type to the trusted providers list in the Administration.config file. The provider has to be strongly typed and added to the GAC (Global Assembly Cache)."

...then you should visit the following article for detailed information about resolving the error message:

Adding Management Trusted Providers <add>

Getting rid of this error message is really only for convenience in letting the IIS Manager UI be able to query your database using your providers and give you a basic view of your Membership, Roles, and Profile fields. Also, if you are trying to find your Administration.config file, it is likely located under the C:\Windows\System32\inetsrv\config\ folder.

The other error message I received was not in the IIS Manager UI, but rather when you attempt to view your website in a browser (after you think you got all the configuration bugs out!). A BadImageFormatException is thrown and the error details say something like this:

Could not load file or assembly 'AssemlyNameHere' or one of its dependencies. An attempt was made to load a program with an incorrect format.

The likely cause of this error is that the assembly referenced in the error message was compiled only for 32-bit machines and you are running a 64-bit operating system. With Windows Server 2008 x64, the application pools in IIS have an Advanced Setting called Enable 32-Bit Applications, that is disabled by default. Enable this setting and you're probably good to go. See the following link for more detailed information and some nice screenshots:

Could not load file or assembly 'name' or one of its dependencies

Additional Reading

I just barely noticed that 4GuysFromRolla.com recently posted an article about the exact same stuff I was attempting to explain. To read additional details about IIS 7's Integrated Pipeline and ASP.NET Forms Authentication with static content, check out the following link:

Apply ASP.NET Authentication and Authorization Rules to Static Content with IIS 7.0's Integrated Pipeline Feature

Conclusion

I hope you've enjoyed this series on the ASP.NET Provider System. My desire is that you've found these posts helpful in getting you started with implementing such a versatile and customizable model for adding common membership and authorization functionality to your new and existing websites. There are quite a few advantages in hosting your site on IIS 7 in Windows Server 2008, as I've outlined in this specific post. Hopefully these discussions about errors and gotchas will also help you get going in no time!

ASP.NET Profile and Web Application Projects

2009-02-11T15:08:00.001-07:00

I talked at length about the ASP.NET Provider Model pattern and the ease of implementing several built-in services you can have for free with ASP.NET 2.0 in my previous series of posts. In this post, I will be discussing a few issues I ran into using the Profile system with the Web Application project template instead of the Web Site project template as found in Visual Studio's list of default project templates.

The crux of the issue is that Visual Studio doesn't automatically generate the Profile proxy class object when using the Web Application project template, like it does with the Web Site project template. This proxy class can be used to obtain access to strongly-typed properties representing the custom Profile fields you specified in your Web.config. This is a very convenient way to access a user's Profile data, both for authenticated and for anonymous users.

Let's discuss the issue a little further and then I will present a workaround that I found and have successfully implemented in my own project.

VS Project Templates: Web Site vs. Web Application

It appears that Microsoft has tried to differentiate these two project templates as much as possible in Visual Studio 2008. In 2005, you would go to the New Project dialog window and you would see these two Web project templates side-by-side, wondering what difference it would make if you chose one over the other. However, in Visual Studio 2008, it appears they reworked this whole dialog and menu system for starting a new project so that you would never see these two project templates side-by-side. In 2008, you have more than one option in the File menu for starting a project; those options are File | New | Project and File | New | Web Site. The first option is the one that will get you to the ASP.NET Web Application template, while the second takes you to the ASP.NET Web Site project template.

Now as for the differences between these two templates, I'll outline a few of the main differences and give a little bit of history of how these two templates came to coexist. The history in a nutshell is that Visual Studio 2005 came out with the Web Site project template to replace the old, but proven project configuration used by ASP.NET 1.x. In the opinion of many, the old template better encouraged Object-Oriented design practices. The new template had no project file for explicitly delineating what files where included in the project and namespacing was quite cumbersome, as the only painless design was to let everything pile up into one big default namespace. A few other changes involved taking ASP.NET back to compiling on the fly at the web server and also drastically changing the organization of UI template and code-behind files. It appears the intention was to closely mimic the configuration and deployment practices of popular agile languages like PHP and Ruby on Rails.

In the Service Pack 1 of Visual Studio 2005, Microsoft decided to resurrect the older project template under the name of Web Application. There is evidence to suggest that Microsoft considers this latter project template an "enterprise" project type, as compared to the casual Web Site project template. With the advent of Visual Studio 2008, it is apparent that Microsoft is committed to supporting both project types for at least a little while. For a more detailed discussion of the history and differences of these two project templates, I suggest the following blog post by Stephen M. Redd:

ASP.NET - Web Site vs. Web Application

Web Profile Builder by Joe Wrobel

The ability to retrieve and update your custom Profile fields at design time via strongly-typed properties on the Profile proxy class is extremely convenient. Unfortunately, you get no such compiler and intellisense love if you are using the Web Application project template for your site.

In trying to find a workaround, I came across a blog post by Joe Wrobel introducing a project he worked on to solve this issue. It's called the Web Profile Builder (here's a link to it's project page on MSDN Code Gallery) and it was based on a project called the Web Profile Generator, which was a Visual Studio 2005 Add-In project found on CodePlex. The latter project seems to have not been worked on in over a year and a half, nor does it seem to be compatible with Visual Studio 2008. Hence, Joe feeling the need to start up on his own project, with a few improvements on the side of course.

In Joe's introductory post to the project, he mentions he changed the Visual Studio integration from being a plug-in to being an MSBuild Build Task. The method for incorporating the Build Task into your project is to add a line into your project file (the one with file extension .csproj). In case you weren't aware, Visual Studio project files are just MSBuild build scripts. For details about where to put this line in the file (and about a message Visual Studio pops up when it detects you've mucked with the project file), be sure to check out Joe's post on the Web Profile Builder project.

There are a couple of other things I need to point out about using the Build Task that weren't entirely clear to me beforehand. The build task actually generates a C# code file that is intended to be included into your project; once it's generated, you need to go to the Solution Explorer and explicitly add it as a file in your project (one way is through the Add | Existing Item menu option). One of the main things that helped me decide to use this solution and how to configure it was reading two blog posts from Anthony Grace; the second post below has a great excerpt apparently from the Web Profile Builder documentation that explains the process I outlined above in a bit more detail:

Also, it is not necessary to do the steps in the Extended Usage section of Joe's blog post. They are optional configuration points in the Web.config where you control the className, nameSpace, directory, and fileName of the auto-generated code file. Most of the defaults are fine, but in my case I wanted the generated file to end up in an App_Code directory instead of in the root of the project folder. If you decide to add in this custom configuration, you need to be aware that you must add the following XML namespace to the configuration root element of your Web.config:

xmlns="http://schemas.microsoft.com/.NetConfiguration/v2.0"

Finally, it should be noted that if the website you are building is under source control, you will likely want to always keep this auto-generated code file checked out in order to prevent the file from having its Read-Only attribute set when it's checked in. If you don't have it checked out, the build will throw out a warning and the generated code file will not be regenerated if changes in your Web.config need to be propagated to it.

Conclusion

With all of this in place, you should be able to use the Profile proxy class object in your ASPX code-behind files, just as I gave examples of in my previous post about the ASP.NET Profile system. Although in my case, I mostly used the static method GetProfile from the auto-generated WebProfile class (the name the Visual Studio Build Task selects by default).

As I mentioned when I first started the ASP.NET Provider Series of posts, my next blog post will be about some advantages of using this Provider system on IIS 7 and a few issues when your ASP.NET website contains non-ASP.NET content:

IIS 7 and ASP.NET Providers (Membership, Roles, and Profile)

ASP.NET Providers - Profile

2009-02-09T16:10:00.002-07:00

This blog post is part of a series about the ASP.NET Providers (namely Membership, Role Management, and Profile). The introductory post in the series can be found at the following link, which introduces the Provider Model pattern and gives a personal example of an implementation I have been working on:

ASP.NET Providers - Membership, Role, and Profile

This post will deal with adding Profile properties to your user accounts (and apparently this can also be used with anonymous users as well). However, I will suggest using a slightly different Profile Provider than what comes in ASP.NET by default. This will show how easy it is to plug in a different implementation in this very flexible Provider Model.

SqlProfileProvider vs. SqlTableProfileProvider

The SqlProfileProvider is the built-in Profile Provider that ASP.NET comes with by default. It allows you to define custom fields that make up profiling data you would want to collect and store about your users. This could be demographics, preferences, or any other useful details. This specific implementation is designed in a way where no matter what fields you define, your database schema will be compatible with any upgrade Microsoft could send down to patch the Provider system or ASP.NET in general. The way this is accomplished is by storing a blob of all the field names in one table column and a blob of all the field values in another column; it's similar to the concept of a dictionary with key/value pairs. The difficult part is that these blobs can contain clear-text, XML, and/or binary, depending on how the source data type serializes by default. Unfortunately, this highly flexible solution is quite unusable if you need a clear view of the Profile data for reporting purposes or stored procedure needs.

When trying to find an already implemented custom provider that would allow to store each Profile field in its own table column, I came across a blog post from Scott Guthrie introducing such an implementation done by two Microsoft employees. The name of this provider is the SqlTableProfileProvider, and it can be found at the following link:

Table Profile Provider Samples

At the above location, you will find an MSI download that will install a sample project containing a few source code files you can include in your project; you will also find a download link for a "white paper" Word document that explains the usage of the SqlTableProfileProvider and the SqlStoredProcedureProfileProvider custom providers. The nice thing about both of these providers is that their use in code and their configuration in the Web.config is extremely similar to how the original SqlProfileProvider is used and configured.

Setting up the SqlTableProfileProvider

As was done with the Membership and Role Management Providers, here is the XML fragment that would go in your Web.config:

<configuration>
    <connectionStrings>
        <add name="MyDB" connectionString="..." />
    </connectionStrings>
    <system.web>
        ... authentication & authorization settings ...
        <profile enabled="true"
                 defaultProvider="ConfiguredProfileProvider">
            <providers>
                <add name="ConfiguredProfileProvider"
                     type="Microsoft.Samples.SqlTableProfileProvider"
                     connectionStringName="MyDB"
                     table="custom_Profile"
                     applicationName="SampleWebSite" />
            </providers>
            ... properties section found in the next XML snippet ...
        </profile>
    </system.web>
</configuration>

WARNING: According to Microsoft, you should never use the default provider settings and should always add a new, configured provider; in addition you must be sure to specify the applicationName attribute! See Scott Guthrie's blog post on this topic for more details. Apparently, you can also use a value of "/" for the applicationName and it will use the root application name.

You'll notice in the type attribute that we are not referencing the default SqlProfileProvider that ships with ASP.NET. What you need to do is get this new class included or referenced in your solution so that this namespace reference can successfully resolve. I opted to just include the code files in my solution as is; I chose to place them in my App_Code folder. The code files you want to grab are likely in the default location that the MSI installed to, which is Program Files/Microsoft/ASP.NET 2.0 Table Profile Provider Samples. The two files you need are SqlStoredProcedureProfileProvider.cs and SqlTableProfileProvider.cs, both of which are found in the App_Code folder of the sample project. You need to copy both code files to your solution, as it appears that the SqlTableProfileProvider depends on some logic in the SqlStoredProcedureProfileProvider for some reason.

Also note the table attribute above (which is not present in the built-in SqlProfileProvider), which tells the provider which table in your database will be storing the custom Profile fields. As for the "properties section" referenced near the end of the above snippet, this is where you specify the custom Profile fields and their mappings to column names in the specified database table. The advantage of specifying this information in the Web.config is that you will be able to get programmatic access to these fields as strongly-typed properties on a proxy class named Profile in your code-behind. Here is a sample properties configuration:

<properties>
    <add name="FirstName"
         type="string"
         defaultValue="[null]"
         customProviderData="FirstName;nvarchar" />
    <add name="Age"
         type="int"
         customProviderData="Age;int" />
    <add name="AccountExpiration"
         type="DateTime"
         defaultValue="[null]"
         customProviderData="AccountExpiration;datetime" />
    <add name="CookieID"
         type="System.Guid"
         defaultValue="[null]"
         customProviderData="CookieID;uniqueidentifier" />
</properties>

The Profile system provides a configuration point for each Profile field called customProviderData. It appears the default SqlProfileProvider doesn't even look at this additional attribute, but rather reserves this configuration point for use by custom implemented Profile providers. The SqlTableProfileProvider utilizes this extra metadata field as a place to put mapping information for a column name and ADO.NET database type. If you have questions about which ADO.NET and .NET types to use/specify in this configuration, there is helpful information in the accompanying white paper found on the download site. Also found in that document is a great discussion you may want to read about the defaultValue attribute, what it configures, and how it might differ for value types (such as integer).

Creating the Database Table

Now that you have the code files in your solution and have configured the Profile fields, you need to create the custom table in the database that this provider will query and update. Here is a sample SQL definition for our custom profile table:

create table dbo.custom_Profile
(
    UserId               uniqueidentifier not null Primary Key,
    FirstName            nvarchar(50) null,
    Age                  int null,
    AccountExpiration    datetime null,
    CookieID             uniqueidentifier null,
    LastUpdatedDate      datetime not null
)
go

Note that the SqlTableProfileProvider requires two extra columns in addition to your custom defined Profile properties, namely UserId and LastUpdatedDate. One other thing to be aware of is that if you use the Membership API to delete a user programmatically, this will remove all entries related to that user in the database except from your custom Profile table. I believe this might be because the Profile system can apparently be used independently of the Membership system, even allowing you to store Profile data on anonymous, unauthenticated users. I think the same caution would go for any utility that presumably uses this Membership API under the covers, such as the ASP.NET Website Administration Tool launched from Visual Studio that I referred to earlier in this series with a post titled ASP.NET Providers - Getting Started. Up to this point, I have resorted to manually clearing out Profile table rows myself that are linked to the membership account being removed from the database.

Also, if your web site is using a Windows user or system account for the identity of the worker process, you'll want to make sure that set of credentials has SELECT, INSERT, UPDATE, and DELETE permissions granted to it for this new custom database table you created. There are also some EXECUTE, SELECT, and UPDATE permissions required on a few of the already-existing stored procedures that the Provider system uses. Again, check the accompanying white paper on the download site for a discussion about these procedure and for some SQL statements to help you automate the granting of these permissions.

The Profile Proxy Class

If you are using the Web Site project template in Visual Studio, then you are good to go with using the Profile proxy class that can be used anywhere in your code to retrieve and update Profile fields on the current user. The availability of this Profile class is independent of whether you are using the built-in ASP.NET SqlProfileProvider or the custom SqlTableProfileProvider that I've been showcasing thus far. However, if you are using the Web Application project template, this proxy object is not auto-generated for you by Visual Studio. For a detailed discussion of the problem and a working solution, see my next post which is entitled ASP.NET Profile and Web Application Projects.

Use of this Profile class couldn't be easier and is exactly as you would expect it to be. Here is a code snippet that both retrieves and updates strongly-typed Profile properties (exactly as they were defined in the Web.config) using this proxy object:

// Set Profile property
Profile.FirstName = txtBoxFirstName.Text;

// Retrieve Profile property
int age = Profile.Age;

Read On!

This crash course of the ASP.NET Provider system is pretty much done I guess you could say, as far as a tutorial goes that is. I still have another two posts on the radar that will be coming over the next few days regarding issues and workarounds that I encountered. One post will deal with generating this Profile proxy class under the Visual Studio Web Application project template. The other post will be about the advantages of using this system under IIS 7 found in Windows Vista and Server 2008; it will also include some issues with using this system if some of your content is static HTML instead of ASPX pages. Here are the links to these two posts:

It has been a very pleasant experience overall to work with the ASP.NET Provider system because of it's highly customizable and flexible design. If your Membership, Role Management, and Profile needs are fairly common and typical, this framework is a piece of cake to incorporate into your product (including your existing ones, no matter how out-of-date they are). Hope you've enjoyed the series!

ASP.NET Providers - Role Management

2009-02-05T16:45:00.002-07:00

ASP.NET Providers - Membership, Role, and Profile

This post will deal with adding Role Management to your website.

Role Management

Creating roles and assigning users accounts to them is a great way to group users together under similar permissions and abilities. The ASP.NET Roles Management service allows you to restrict page viewing (or even just certain regions of a page) based on roles you define; you can even apply roles security to specific methods or classes using attributes, which I will show an example of a little later.

In order to add role management to your site, add an XML fragment like the one below; the process is much the same as it was with the Membership Provider:

<configuration>
    <connectionStrings>
        <add name="MyDB" connectionString="..." />
    </connectionStrings>
    <system.web>
        ... authentication & authorization settings ...
        <roleManager enabled="true"
                     defaultProvider="ConfiguredRoleProvider">
            <providers>
                <add name="ConfiguredRoleProvider"
                     type="System.Web.Security.SqlRoleProvider"
                     connectionStringName="MyDB"
                     applicationName="SampleWebSite" />
            </providers>
        </roleManager>
    </system.web>
</configuration>

Role names can be used in the Web.config in the same place we used the user class wildcard characters (namely, * for all users and ? for anonymous users); the following sample fragment would go under the system.web node:

<authorization>
    <deny users="BannedUsers,?" />
    <allow users="PremiumUsers" />
</authorization>

Role names can be defined by using the ASP.NET Website Administration Tool launched from Visual Studio that I referred to earlier in this series with a post titled ASP.NET Providers - Getting Started. You can also use this utility to assign users to one or more roles. Roles can be programmatically assigned and verified in code as well, using the provided Roles .NET API.

Attribute-based Role Management

In order to put authorization rules on classes or methods, you use the attribute named PrincipalPermission. Here is a sample that contains a method only accessible by a user with the username of administrator AND in the role group Admin:

[PrincipalPermission(SecurityAction.Demand, Name="administrator", Role="Admin")]
public void SomeMethod(...)
{
    ...
}

The OR version of the above logic (meaning the user account being verified need only satisfy one of these authorization rules) would be represented like this:

[PrincipalPermission(SecurityAction.Demand, Name="administrator")]
[PrincipalPermission(SecurityAction.Demand, Role="Admin")]
public void SomeOtherMethod(...)
{
    ...
}

Here is an interesting sample that restricts a page to authenticated users (those not visiting anonymously); you would put the attribute on the code-behind of an ASPX page, like this example for SomePage.aspx:

using System.Security.Permissions;

[PrincipalPermission(SecurityAction.Demand, Authenticated=true)]
public partial class SomePage : System.Web.UI.Page
{
    ...
}

In all of these cases, if the authorization criteria is not met, a SecurityException is thrown. You would want to catch that exception and perform alternate logic or display a more user-friendly error message.

Read On!

Continue onward by reading the next blog post in this series found at the following link:

ASP.NET Providers - Profile

ASP.NET Providers - Membership

2009-01-30T14:21:00.007-07:00

ASP.NET Providers - Membership, Role, and Profile

This post will deal with adding the Membership functionality to your website.

Membership Provider Configuration

Now that your DB is set up, there are a few snippets that need to be added to your Web.config. It involves adding a connection string and adding a new membership provider, as in the sample below:

<configuration>
    <connectionStrings>
        <add name="MyDB" connectionString="..." />
    </connectionStrings>
    <system.web>
        ... authentication & authorization settings ...

        <membership defaultProvider="ConfiguredMembershipProvider">
            <providers>
                <add name="ConfiguredMembershipProvider"
                     type="System.Web.Security.SqlMembershipProvider"
                     connectionStringName="MyDB"
                     applicationName="SampleWebSite"
                     minRequiredPasswordLength="5"
                     minRequiredNonalphanumericCharacters="0" />
            </providers>
        </membership>
    </system.web>
</configuration>

The last two attributes of the add node are only a couple of several membership features you can configure. For a complete list of attributes you can configure, see <add> Element for Providers for Membership.

Securing Site Content by Requiring Authentication

With 5 more lines of configuration added to your Web.config, you can have the whole site secured and accessible only by user account authentication. Even better, you can make that 6 lines added to the Web.config, add a Login.aspx page, and drop in a Login control from the Toolbox and you will get auto-redirect to the login page if someone tries to hit any page you've now secured. The framework is even smart enough to return you to that desired page after successful login; it accomplishes this by redirecting you to the login page but by adding a ReturnUrl query string attribute to know where to go after authentication.

Here are the additional lines for your Web.config (put them under the system.web node):

<authorization>
    <deny users="?" />
</authorization>

<authentication mode="Forms">
    <forms defaultUrl="index.html" loginUrl="Login.aspx" />
</authentication>

NOTE: You will likely already have an authentication node in your Web.config, but it's mode may be set to the default "Windows" value. To use the Membership Provider for authentication, you must have this value set to "Forms."

The optional 6th line I spoke of earlier is the forms node under the authentication node. The defaultUrl attribute of this line is used to tell the framework where to go after successful login if there is no ReturnUrl specified in the query string. The loginUrl attribute is used to specify the page the user is redirected to if they are attempting to hit a page that requires authentication.

The deny node is using the question mark (?) wildcard character, which is used for anonymous users (or those that haven't been authenticated yet); the asterisk (*) wildcard is used to signify all users browsing the site. Since we are dealing with the Web.config at the root of the site, this deny rule will apply to the whole site and it's subdirectories. You can either put a Web.config in each subfolder that requires an overriding or more restrictive set of allow and deny rules, or you can actually specify location elements in your Web.config, as is shown in the following example (basically you could have several of these location elements, each with their own authorization rules):

<configuration>
    <location path="Login.aspx">
        <system.web>
            <authorization>
                <allow users="?" />
            </authorization>
        </system.web>
    </location>
</configuration>

As far as I can tell, this sample configuration above isn't necessary if you have specified your login page in the loginUrl attribute of the authentication/forms node like we did in the previous code snippet. But this sample is at least illustrative of the location-based authorization rules.

Personally, I decided to create a folder named Public in my site and I give it its own Web.config that allows all users (including anonymous ones) access to the containing web pages. This folder currently contains the login, user account registration, account activation (a link included in the email sent upon registration), and password retrieval pages, all of which would need unrestricted access for anonymous users.

Test Your Membership Provider

With all of this now in place, you should be able to use the ASP.NET Website Administration Tool launched from Visual Studio to create a few new user accounts. I mentioned how to launch this utility earlier in this series with a post titled ASP.NET Providers - Getting Started. Then you can double-check your membership system is working by logging in with your newly created credentials. Also, you can now create a user account registration page (utilizing the CreateUserWizard control) and a password retrieval/reset page (using the PasswordRecovery control). All of the controls I have named throughout this post are highly skinable and configurable via numerous attributes and templates; they also contain flexible task workflows that you can override or plug into by registering to any of several event listeners.

One other thing that needs to be done if you want to enable the email notification capabilities is to set the SMTP settings in your Web.config. Here is a snippet you would put right above the system.web node:

<system.net>
    <mailSettings>
        <smtp from="service@website.com">
            <network host="mail.domain.com" port="25"
                     userName="..." password="..." />
        </smtp>
    </mailSettings>
</system.net>

Membership API and MembershipInfo Class

There is also a Membership API and an accompanying MembershipInfo class that you can call in order to retrieve and update user info from the database if you wanted to create your own custom controls or page logic. For instance, the following is code that I adapted from Part 11 of the tutorial I mentioned earlier in the introductory post of this series; this code activates an account when a user clicks the link emailed to them during registration:

public partial class Verify : System.Web.UI.Page
{
    protected void Page_Load(object sender, EventArgs e)
    {
        //Make sure valid querystring value was passed
        if (string.IsNullOrEmpty(Request.QueryString["ID"]) ||
            !Regex.IsMatch(Request.QueryString["ID"],
                @"[0-9a-f]{8}\-([0-9a-f]{4}\-){3}[0-9a-f]{12}"))
        {
            InformationLabel.Text = "An invalid ID value was passed " +
                "in through the query string.";
        }
        else
        {
            //ID exists and is kosher, approve user
            //Get the ID sent in on query string
            Guid userId = new Guid(Request.QueryString["ID"]);

            //Get user object
            MembershipUser userInfo = Membership.GetUser(userId);

            if (userInfo == null)
            {
                //Could not find user!
                InformationLabel.Text = "The user account could not " +
                    "be found in the membership database.";
            }
            else
            {
                //User is valid, approve them
                userInfo.IsApproved = true;
                Membership.UpdateUser(userInfo);

                //Display a message
                InformationLabel.Text = "Your account has been " +
                    "verified and you can now log into the site.";
            }
        }
    }
}

Read On!

Continue onward by reading the next blog post in this series found at the following link:

ASP.NET Providers - Role Management

ASP.NET Providers - Getting Started

2009-01-30T14:20:00.000-07:00

ASP.NET Providers - Membership, Role, and Profile

This post will deal with getting started using the ASP.NET Providers by setting up a database.

Database Setup

First, you will need to configure a database to securely store all of the site's user data and activity info. You'll most likely be content with the already provided SQL Providers (such as the SqlMembershipProvider), but Microsoft also provides you with other options in many cases. For example in the case of Membership, you also have the option of having your site use the ActiveDirectoryMembershipProvider or you can even roll your own MembershipProvider. The nice thing about using any of these Microsoft Providers is that they are already set up to store sensitive data like passwords in an encrypted format in the database.

There are two tools you can use to automatically generate the necessary database tables needed for the SQL implementation. The first tool is a web-based configuration tool launched from Visual Studio called the ASP.NET Website Administration Tool. It can not only create the database tables, but can also configure authorization rules, user roles, user accounts, and many other settings that go right into your Web.config. It is launched by selecting the ASP.NET Configuration menu option in the Project menu (or Website menu, depending on which version of Visual Studio you have or the project template you selected). However, this tool will create the database in a SQL Server file named ASPNETDB.mdf placed in the site's App_Data folder. If you would prefer to create the database schema in an already existing install of SQL Server (likely on a different box), you need to use the aspnet_regsql.exe command-line tool. The command-line tool's graphical interface can be launched by typing the name of the executable in a Visual Studio Command Prompt (located in the Start Menu under Visual Studio | Visual Studio Tools).

The only other thing you need now is the connection string to this newly populated database. I will show you where in your Web.config to put the connection string in the next post of this series.

Read On!

Continue onward by reading the next blog post in this series found at the following link:

ASP.NET Providers - Membership

ASP.NET Providers - Membership, Role, and Profile

2009-01-30T14:18:00.003-07:00

Seems like any website you start nowadays involves creating the same common features we see all over the web. These include creating user account functionality, storing profile information, implementing role-based access to content and features, instantiating SQL tables and data access repositories, and so on, so forth. In most cases it would be a complete waste of time and money to roll your own implementation every time.

There are plenty of frameworks out there that tackle this problem for you and abstract out details you shouldn't have to worry about. If you are in the .NET world, there are a set of these services available to you that are baked right into the .NET 2.0 Framework. I'm going to show you a personal example of how easy it is to add some of this functionality to an existing site, even one with an antique and cumbersome architecture. Implementing these features using the ASP.NET 2.0 Provider Model on said architecture has convinced me that it couldn't be easier to add such functionality to a website, no matter what beast of a site you are dealing with.

ASP.NET 2.0 Provider Model

With the advent of ASP.NET 2.0, Microsoft introduced a set of configuration-driven services that adhere to the Provider Model pattern. These services focus on storing application state of a website using a very flexible and extensible data access strategy. The available features that can be added to your website include Membership (which includes authentication and authorization), Role Management, Profile, Session State, Web Parts Personalization, and Site Map navigation. The whole idea is to be able to secure and enhance an existing site by dropping in a few lines into the Web.config, using a Microsoft utility to automatically create database tables (most likely your chosen storage medium), and then dropping, configuring, and skinning a few controls into your existing pages. To read a more thorough introduction to the Provider Model and these ASP.NET 2.0 Provider services (including a few helpful diagrams), check out the following link:

ASP.NET 2.0 Provider Model: Introduction to the Provider Model

Personal Example

We currently maintain a series of desktop products that we have been entrusted with. Under the covers, these "desktop" products were originally written in Java as locally-hosted websites using Apache's web server. In order to be compatible with Windows Vista, we have since ported these products to .NET 2.0 and currently use UltiDev's free, light-weight, and redistributable web server named Cassini (essentially the same thing as the development web server found in Visual Studio and a great alternative to IIS). Many of the features are implemented in JavaScript and the content is almost entirely static HTML pages. There were only a few Java Servlets that we ported to .NET HTTP Handlers and any database storage has been done using Microsoft Access databases. This set of products also has other interaction requirements like the ability to view content from another product while staying in the context of the currently open product. Finally, the installers for a few of these desktop products are getting to be nearly 600 MB in size, which has perpetuated the need for distributing the products to the users offline.

We are in the process right now of exploring the cost benefits and customer experience improvements in moving this set of offerings to an online suite of websites. The first step we are taking is to build an online version of one of the products where users can obtain a user account to view the content. Building new applications is one thing, but upgrading and maintaining existing applications (especially ones you have inherited) is a whole different development experience. This is where my appreciation for the ease and flexibility of what Microsoft is offering comes into play.

Read On!

The rest of the blog posts in this series can be found at the following links:

In addition, I came across an issue when using the Profile system with the Web Application project template instead of the Web Site project template as found in Visual Studio's default set of project templates. It has to do with the Profile proxy class object not being auto-generated by Visual Studio when using the Web Application project template. Read the following blog post for a discussion of the problem and it's solution:

ASP.NET Profile and Web Application Projects

Also, I have another post discussing the advantages of using the ASP.NET Provider system under IIS 7 found in Windows Vista and Server 2008; it will also include some issues with using this system if some of your content is static HTML instead of ASPX pages. You can find all of this goodness by following the link below:

IIS 7 and ASP.NET Providers (Membership, Roles, and Profile)

Finally, I based my implementation on a 13-part tutorial series by Scott Mitchell on 4GuysFromRolla.com, starting at this link:

Examining ASP.NET 2.0's Membership, Roles, and Profile - Part 1

Enjoy!

If Programming Languages Were Religions...

2008-12-16T11:48:00.001-07:00

This is hilarious and really creative:

http://www.aegisub.net/2008/12/if-programming-languages-were-religions.html

Which BAM is which?

2008-12-04T16:54:00.000-07:00

I just watched a presentation that I thought would be about BAM (Business Activity Monitoring) from BizTalk, but instead it was some new project that Microsoft Research cooked up that helps model cloud computing. Interesting nonetheless, but not the BAM I thought I was getting.

Correctly Using Random Number Generators

2008-12-01T17:13:00.000-07:00

Today I read another guy's blog post that reminded me of my own "Aha!" moment I had a while back with Random Number Generators. It's something I will never forget about Random Number Generators but taken for granted, realizing that it might not be obvious to everyone how these objects are intended to be used. Here is the blog entry that I read about creating and seeding a Random Number Generator once:

http://silverlight.net/blogs/msnow/archive/2008/12/01/silverlight-tip-of-the-day-77-creating-an-efficient-random-generator.aspx

However, I must admit that I think Mike Snow should have titled his post something similar to the title of my post. And I will tell you why...

In the MSDN documentation that Mike quotes, there is a key sentence everyone needs to take note of, as you can ignorantly introduce bugs into your code:

"As a result, different Random objects that are created in close succession by a call to the default constructor will have identical default seed values and, therefore, will produce identical sets of random numbers."

I have actually build a piece of code where this has happened. I wrote a for loop that iterated quickly enough that the construction of the Random objects resulted in identical random number seeds. The result was that I asked for several random numbers in quick succession and got the same exact "random" number across all my requests each time I ran the code. So not only did I get "identical sets of random numbers," but I got identical random numbers.

As Mike Snow and the MSDN documentation states (and from my own experience), Random Number Generators are designed to be constructed once and intended to live long and prosper within your application. It can serve all of the random number needs within your application (i.e., you don't need a different Random Number Generator for different use cases or different object types). All you need is a one-time created random number seed and then you can forever generate random numbers of any type and within any range of numbers. I can't currently think of a situation when you may need to reseed your Random Number Generator. Let me know if you think of one.

Is LINQ to SQL Being Replaced Already?

2008-11-03T13:00:00.000-07:00

The short answer is "kind of"; the push is for the ADO.NET Entity Framework to be the encouraged ORM approach from now on. For the long-winded, thorough explanation of this answer (based on blog posts from Microsoft employees and managers), see the following blog post that someone pointed me toward:

http://www.infoq.com/news/2008/11/DLINQ-Future