I've recently been reading this book by Jon Skeet about C# 2 and 3, and it got me all inspired to write about generics. Jon's great; he's extremely active in the C# and Java community, and recently responded to an email question I had in less than 10 minutes! I'm finding the book insightful and useful and greatly enjoying my bus rides to work when I get to read it.

This post is going to assume you are familiar with using generic classes like List<T> and Nullable<T>. So lets start with the syntax for declaring our own generic class:

public class Monkey { }
public class Animator<T> {
    private T instance;
    public Animator(T t)
    {
        instance = t;
    }
    public void MoveOnce() { }
}
Animator<Monkey> animator = new Animator<Monkey>(new Monkey());
animator.Move();

This is pretty simple: the Animator class accepts a generic type T and requires you pass a T in its constructor. The MoveOnce() method is empty at the moment, we'll get to that later.

Currently our generic Animator class is somewhat type-safe: we can only pass instances of T to its constructor, but we don't really know much about T. We'd like to be able to move our instances (such as a monkey) so we need to define some things about what kinds of T we are willing to accept. Lets go back to our Monkey class for a moment and define an interface for it:

public interface IMoveable {
    void Move();
    void Stop();
}
public class Monkey : IMoveable {
    public void Move() { }
    public void Stop() { }
}

Great! We've decided that the fact a Monkey can move and stop is pretty general, and is probably something other animals can do, so we've declared an interface to indicate our monkey has those capabilities. We might also define IEater, or IDungFlinger. Now we can revisit our generic type in our Animator class definition as follows:

public class Animator<T> where T : IMoveable
{
    private T instance;
    public Animator(T t)
    {
        instance = t;
    }
    public void MoveOnce() {
        instance.Move();
        instance.Stop();
    }
}

This is where the magic begins. We've placed a constraint on our generic type, stating that it will only ever accept a type that implements our IMoveable interface. If we try to use the Animator class with something else, we will get a compile-time exception. Even better yet is that our development environment knows that since our instance will always implement IMoveable, it therefore must have a Move() and Stop() method, therefore we can call it anywhere in our class; in this case the MoveOnce() method.

You can declare more than one generic type in your class definitions. Imaging a class that facilitates a race for monkeys, whether they be chimps, gorillas, or marmosets. Consider this generic class declaration:

public class Race<T, U> where T : Monkey where U : Monkey {
    public Race(T monkey1, U monkey2) { }
    public void RunRace() { }
}
public class Marmoset : Monkey { }
public class Chimp : Monkey { }

Here we have defined that our class accepts 2 generic types: T and U. We have further restricted them that they both have to inherit from the Monkey class. Here's some example calls using this new class:

Race<Chimp, Marmoset> race1 =
      new Race<Chimp, Marmoset>(new Chimp(), new Marmoset());
Race<Monkey, Chimp> race2 =
      new Race<Monkey, Chimp>(new Monkey(), new Chimp());
Race<Marmoset, Marmoset> race3 =
      new Race<Marmoset, Marmoset>(new Marmoset(), new Marmoset());

As you can see that anything that inherits Monkey is valid. Of interest, the second example shows that even an instance of Monkey is valid. This shows that the where clause in our type restriction means anything that inherits from X or is X.

Finally here are a couple of extra cool things you can do with generic type restrictions as general non-monkey related examples:

public class TestCase1<T> where T : class { }
public class TestCase2<T> where T : struct { }
public class TestCase3<T> where T : IDisposable, IMoveable, IComparable { }
public class TestCase4<T, U> where T : U { }
public class TestCase5<T, U> where T : U, IMoveable { }
public class TestCase6<T, U> where T : class where U : struct{ }
public class TestCase7<T, U> where T : class where U : struct, T { }

TestCase1 demonstrates that we can force the type to be a reference type.
Likewise TestCase2 ensures that the type must be a value type. How is this useful? Well consider a generic class that performs expensive operations such as copying from one list to another. Reference types are just pointers and therefore inexpensive to copy around, thus ensuring only reference types are allowed in our class could be quite useful.

TestCase3 shows that we can ensure T implements multiple interfaces.
TestCase4 shows that one generic type can be forced to inherit from another. An example of an implementation might be:

TestCase4<Chimp, Monkey> test = new TestCase4<Chimp, Monkey>();

This is valid because Chimp inherits from Monkey.
TestCase5 shows that a type can be restricted to inherit as well as implement interfaces.
TestCase6 demonstrates that one type must be a reference type while the other can be a value type.

The last TestCase7 is somewhat interesting. Its declaration indicates that T is a reference type, and U is a value type that must inherit from T. How can this be? It essentially states that you must pass a struct that inherits from a class. But C# won't let you declare this.

To be honest at first I didn't know the answer to this. Thus the email to Jon, and his explanation was simple and it made sense: interfaces are reference types. Hopefully you are aware that structs can implement interfaces also (but can't do inheritance), so we might define a new animal as follows:

public struct Mouse : IMoveable {
    public void Move() { }
    public void Stop() { }
}

Then we can legitimately use the TestCase7 syntax:

TestCase7<IMoveable, Mouse> test = new TestCase7<IMoveable, Mouse>();

Then of course, valid values for an IMoveable are a Chimp, Marmoset, or even another Mouse, while of course you can only use a Mouse for the second type.

Hopefully this has given you a better idea of what you can do with generics.

The common question is: what the hell is contravariance and covariance?

Ok so you are familiar with casting right? In C# we can do this:

public class Animal { }
public class Monkey : Animal { }
...
Animal a = new Monkey();
((Monkey)a).FlingCrap();

We can also do this:

public void MoveWest(Animal a) { }
...
MoveWest(new Monkey());

Because the 'MoveWest' method accepts the narrowing type 'Animal' it is said to support 'Contravariance'. If the C# compiler forced us to only pass exact types, then it would be considered 'invariant'. Likewise C# methods support covariance, in that we can return a narrower type and cast the resulting instance to its correct form.

There are parts of the .Net framework however that aren't so flexible. In this case, I'm talking about generics.

Consider this for example:
List<Monkey> monkeys = new List<Monkey>();
monkeys .Add(new Monkey());
List<Animal> animals = monkeys;

Unfortunately this does not compile. We get the following warning:

Cannot implicitly convert type 'System.Collections.Generic.List<FeaturesCsharp2.Monkey>' to 'System.Collections.Generic.List<FeaturesCsharp2.Animal>'

Why is this? Monkey inherits Animal, so the list conversion is perfectly safe. Well this is one case of invariance. But here's the kicker: word on the street is that the CLR actually supports contravariance of generic lists; its just the C# compiler that doesn't!

My mate and fellow Readifarian Paul Stovell recently posted his 'Circle Of Interest' and started a meme by nominating 5 others to do the same. I was one of the lucky ones, so here's my circle.

I don't doubt this circle will change completely in 6 months. I expect the TFS parts to fade into the middle circle, with more focus on WPF and SilverLight perhaps. Who can tell?

The big red circle indicates things I don't care about, the baby-vomit yellow indicates stuff I am interest in but have little time or dedication to fully pursue. The dog-vomit green is the stuff that I am loving working or am most eager to develop as soon as possible.

Oh, WCF shouldn't be in the middle circle, but I couldn't be bothered changing it.

Now, to continue the meme, I nominate these people:

Matthew Rowan , John McFadyen , Joseph Cooney , Leon Bambrick

Get to it chumps!

At Readify we are encouraged to do a plan that we can use for guidance in our personal development. I was pretty generic with mine and have decided to give it more focus today (given that its labour day and all). I figure I'd post it here so that I can hold myself accountable to it next year. Lets say, end of financial year 09? Gives me 14 months to see what I can achieve off of this list. Naturally having a baby will affect this in yet to be discovered ways.

The list is priorities by importance for high level headings only. Its mostly just a bullet point list, which is interesting because I am unsure how to measure success for some of these things (for example, when will I 'know' WCF? I've done a bit already but still am not across all the security aspects).

Anyway, here's the list. Feel free to critique or post your own list in response.

Certifications (importance: HIGH)
· MCTS: Web Applications
· MCTS: Windows Applications
· MCTS: WCF
· MCT: Certified Trainer
· MCTS: Business Intelligence

Improve blog quality (importance: HIGH)
· Attract more readers
· More diverse topics (as my knowledge increases)
· More frequent postings

Specific Technologies (importance: HIGH)
· LINQ, dLINQ, xLINQ, etc
· SilverLight
· Expression tools
· Windows Presentation Foundation
· MVC Framework
· ADO.NET Data services
· ADO.NET Entity Framework
· Windows Workflow Foundation
· Windows Communication Foundation
· Active Directory, DNS, and networks
· Sharepoint
· Intermediary Language
· Team Foundation Server / Team Build
· Visual Studio Team System
· ASP.NET Ajax
· Business Intelligence
· Reporting Services
· BizTalk
· Integration Services

Attend Special Interest Conferences (importance: HIGH)
· Tech Ed - Australia
· ReMix - Australia
· Mix - United States
· Tech Ed – Europe

Presenter (importance: MEDIUM)
· User groups / SIGs
· Code Camps
· Tech conferences like TechEd

Further Study (importance: LOW)
· Physics/Chemistry/Astro-physics
· MBA

Author (importance: LOW)
· A technical book, unsure of topic at this stage
· Articles to MSDN, code magazines, etc

Wow, looking at this list, I feel like I know absolutely nothing! But to be honest, I have groundings in a lot of the technical stuff (like SilverLight, WCF, Reporting Services, BI, LINQ, etc), but I really want to gain expertise in these areas.

Why do I rank certifications so highly? Well I'm keen on the MCT, which requires an MCTS or two. Also they are useful to an employer for points towards partner status. Finally, its a personal milestone, ie the certification is for me, not you. I want to pass all those tests based on my knowledge (not cheating, examining practice tests, etc).

I don't expect I'll get to Tech Ed Europe or Mix US anytime soon, but ReMix is a possibility for me this year (I've never been) and Tech Ed is a definite (see you there!).

At my work I am starting to integrate PowerShell scripts into the TeamBuild projects for our nightly build. Including PowerShell is very easy: you just need to ensure that PowerShell is installed on the build server. Installing PowerShell will adjust the PATH environment variable, but you may need to restart the build service in order for the build server to pick up this new path.

Including a PowerShell script in your TeamBuild (or MSBuild) targets is very easy. You might have a target that looks something like this:

<Target Name="UnrestrictedExecutionPolicy">
    <Exec Command="powershell set-executionPolicy unrestricted&quot;" />
</Target>
<Target name="TestScript" DependsOnTargets="UnrestrictedExecutionPolicy">
    <Exec Command="PowerShell ./Scripts/testscript.ps1" />
</Target

As with most environments, we need to change the execution policy so that it will allow scripts to be run. We only need to do this once for our whole build, so best to create it in its own target and place a dependency to it from other targets that will be calling PS scripts.

In the above example, we are calling a script in the Scripts folder called testscript.ps1. Pretty simple really. If an error occurs in that script, then the exit code will indicate an error, and the build will fail. However, we may not want the build to fail. Perhaps only a warning is required. Or perhaps we want the script to do things that might break the build AND raise warnings. How can we handle this?

An easy way is to use exit codes. Most EXEC calls will return an exit code. 0 usually means success, and 1 or higher means failure. In MSBuild (ie. TeamBuild) that means 1 or higher will break the build. So what if we want our PowerShell script to return all sorts of exit codes, and only have certain exit codes break the build, and others raise warnings? This is easy too, but requires some jigging.

First, we call the EXEC task with an attribute that tells it to ignore the exit code that results from the call. This means that even failed calls will not break the build. Second, we capture the exit code of the EXEC task with the Output attribute and assign it to a Property. The target might then look like this:

<Exec Command="PowerShell ./Scripts/testscript.ps1" IgnoreExitCode="true">
     <Output TaskParameter="ExitCode" PropertyName="ScriptExitCode" />
</Exec>

Cool... we now have the exit code in the property 'ScriptExitCode' and can manually do what we like with it. Using the Warning and Error tasks that already exist, we can react in a more custom way:

<Warning Condition="$(ScriptExitCode)==2"
               Text="Warning: The script raised a warning" />
<Error Condition="$(ScriptExitCode)==1"
           Text="Error: The script raised an error: Build stopping." />

In this example, if the script returns exit code 1, the build still fails. However if it returns 2, then only a warning is raised, and the build continues on.

So only one thing remains: how do we tell PowerShell scripts to return a specific exit code? Well that's just as easy. In our PS script, we can use this line:

$host.SetShouldExit(2)

$host is a reserved variable in PowerShell. In the above code, we are telling the script to return exit code 2 when it exits. Note that this line does not tell the script to exit straight away. To do that, call the command 'exit'.

So using this knowledge, we can sprinkle the relative exit codes throughout our scripts and let MSBuild handle it on the outside.

Brisbane: A rich ecosystem of technology, enthusiasm, and deliverance. I often wonder how I manage to stay married when there is so much going on in this town that keeps me distracted. I'm sure its just as rich in other cities, but hell, I don't care about those infestations. Brisbane is great for the developer/enthusiast and here's why: my week since last Wednesday.

Weds 26th March - Heroes Happen
I was sitting in one of the Server 2008 sessions and I realised "I've seen all this before". It was at that point in time I remembered last year playing around with server 2008 beta 3 and TFS 2008. I had had so many problems, I'd reinstalled the server like 5 times, so I was very familiar with the interface. I was most interested in the Server Core and Hyper-V products and particularly interested in the Server 2008 license now sitting on my desk waiting to be installed. To be honest, I didn't learn much from the developer sessions. I've been using VS2008 for quite a while: both in production over the last 3 months, and beta last year with 'toy' projects. Still, Dave Glover showed a few cool things I hadn't seen before, such as the native debugger support for WCF apps, including the WCF test window.

Thurs 27th March - Sql Server User Group
The guys from Soul Solutions showed up to deliver some useful information on Sql Spatial. Unfortunately I couldn't stay from the whole event, but I hung around long enough to find out that John and Bronwen were in fact the 2 people dressed up as Batman and Batgirl at Heroes! Those 2 are crazy...

Mon 1st April - QUT Alumi Presentation
There was a few hours of work left when Joel Pobar came roaming through the pods trying to drum up interest in a presentation at QUT by Gordon Bell. The topic was around data and its management: how do we derive quality information? He covered briefly his history around the starting of the Microsoft Research Centre and the work done there in recent years around data management, in particular a case study into celestial data and the resulting Worldwide Telescope.

Tues 2nd April - Security Interest Group
A new user group that I only stumbled on as I was walking out the door at the end of the day, this group had a great presentation on Microsoft's product offerings and where security fits into the 'now' and 'future'. While MS product based, it was quite well generalised. I felt quite odd though being the only developer in a room full of system admin-type people! I'm very keen to see where this group goes from here (no link because they don't have a web site yet: hit me up if you want the administrators email, sorry I don't have it handy at the time of this post!).

Weds 3rd April - Briztalk User Group
This is the second time I have come to this group's meetings and have enjoyed them both greatly. The first was about RFID, and last night's was about the new 2008 offerings in Server and Visual Studio. The second talk was old news (again) but once again I felt fascinated by the infrastructure aspects of 2008 Server, and it was my questions (single handedly) that caused the group to finish 1 hour later than it should have! (sorry everyone)

So as you can see, Brisbane is a rich fertile ground of development. I've learnt so much over the last week, its ridiculous. Luckily the VSTS user group (was suppose to be Friday morning) was postponed, help give meaning to the weeks ahead! Next week looks rather quiet, which should be good because I have some interesting ideas around F# that I would like to explore.

See you at the next Brisbane community event.

Hopefully by now you have heard of PowerShell (PS) and know that it is a scripting shell much like BASH or any other Unix shell. However unlike those other languages, PS uses an object pipeline, rather than strings, and those objects work directly with the .Net Framework. What this gives us is a powerful, flexible, scripting platform where developers don't have to learn a whole lot before they can start leveraging some real scripting power.

There's lots of examples around how to get started with PowerShell so I'd like to skip that part but first I just want to cover off a few key commands. First, everything in PS is an object of some sort. Unless otherwise specified, most commands will deal with objects or arrays of objects. Since all .Net types inherit from System.Object, this is how PS assumes type safety for all command calls.

Creating an instance of a class is relatively easy. This is how you would create an XmlDocument:

$xml = New-Object "System.Xml.XmlDocument"

The dollar $ sign indicates a variable in PS. The New-Object is a command that accepts a string input for the type. We could then continue to load some XML as we would in .Net:

$xml.Load("c:\somefile.xml")
$xml.LoadXml("<a><b>test</b></a>")

However, PS has a nice XML shortcut that you should know about, and that's the [xml] cast:

$xml = [xml] Get-Content "c:\somefile.xml"
$xml = [xml] "<a><b>test</b></a>"

Now lets use something more interesting for our XML:

$xml = [xml] '
    <world>
        <continent name="Africa">
            <country name="Zimbabwe" />
            <country name="South Africa" />
            <country name="Ethiopia" />
        </continent>
        <continent name="Asia">
            <country name="China" />
            <country name="Japan" />
        </continent>
    </world>'

Another cool operation with XML is referring to Xml Nodes specifically rather than searching. The .Net way would be this:

$continents = $xml.SelectNodes("/world/continent")

This would return an array of Xml Nodes that represent all continents. In PS we can shortcut to:

$continents = $xml.world.continent

You can look at the type of any variable with the standard GetType method:

$continents.GetType()

Interestingly you will see that rather than an XmlNodeList or array of XmlElements, this in fact is an array of Objects! However if we look at the contents of that array we will see each item is something more reasonable:

$continents | % { $_.GetType() }

This command tells us that we have 2 objects of type System.Xml.XmlLinkedNode in our array. The syntax is specific to PS. The | symbol is a pipe, and means to take everything from the left, and shove it into the right. The % symbol is a shortcut for "foreach", which also works just as well. Because we have piped in some content, we don't need to specify any condition logic for our loop, and can go straight to the inner contents. When you don't specify what the name of the variable in the range will be, you can use the $_ variable instead. So overall, the above statement is the same as:

foreach ($_ in $continents) { $_.GetType() }

Let's do something a little different. We will attempt to now take our array of Xml nodes representing continents, and put just the continent name into a generic collection of strings. The syntax around creating an instance of a generic class is as follows:

$list = New-Object "System.Collections.ObjectModel.Collection``1[System.String]"
$list.GetType()

The type shows as Collection''1 without the generic part (string) but it is still there, under the covers. Now lets put the name of all continents into that collection with out % syntax:

$continents | % { $list.Add($_.Name) }
$list | % { $_.GetType() }

The second command shows the type of each item in the collection, and we can see they are all strings.

So that wraps up my first PowerShell post. I've been doing a lot of it this past week, and was very green to begin with. All my work has been around Xml, and I'll be doing some more this week. My specific usage is relating to build and release management in TFS, and am enjoying it greatly.

When it comes to using PowerShell you can create your scripts in any text editor. Currently I am using Notepad++ with PowerShell language definitions, and also PowerGui. PowerGui in particular is an excellent free tool.

During the week the QLD MSDN User Group was treated to a presentation by Leon Bambrick who demonstrated F# in all its glory. The very next day I had the opportunity to meet with Don Syme, inventor of F# (you never know who you meet sitting at the hot desks in Microsoft SDC!).

To me, this was a sign from the powers that be: play with F# or else! First step to get started, is download the latest version MSI from the Microsoft Research site. After you install it, you can open Visual Studio and you will find that you have a new project template:

Not a lot of options for project types I'm afraid. But its a start at least, and Leon indicated there will be full commitment from Microsoft in the future (don't make me a liar Leon). When you create a new project, its very empty. So we add a new item, and notice a few options:

To be honest, I have no idea what they all do. I'm as new to this as you! The script file has a FSX extension and this makes me wonder what kind of cool script stuff you can do with it. Undecided, Leon's voice came to me as if in a dream... "Use the Source, Luke, use the source".

Sure enough, the F# Source File option has a FS extension which is what I was looking for. It comes with a heap of template code for you see how the language syntax works. I was pretty comfortable with the magic keyword 'let' already from Leon's presentation. I set off instead to get the 'interactive' mode to work, since I found this quite a neat feature.

So it seems that there is a 'FSI.exe' which stands for F# Interactive. It is a command line tool that allows you to pass snippets of F# code followed by two semi-colons ;; to terminate the parameter. It seems to remember your 'state' such that functions are remembered in between calls. This is further implemented as a command window in Visual Studio, which is a nice feature. You have to activate it after you have installed F# MSI, by turning it on in the 'Add In' section:

Tick all the boxes, and the F# Interactive window opens. Now you can start typing inline F# code to your heart's content! You can even execute sections of existing code in your .FS files by highlighting a section of code, and pressing ALT-ENTER. This is very similar behaviour to SQL Management Studio - Query window, where you can highlight some T-SQL and press F5 to run just that code. The F# Interactive window will show any errors inline.

For example, when you add a new source file, it comes with a bunch of syntactical examples, and one of them is the "highest common factor" code, as follows:

let rec hcf a b =           // notice: 2 arguments seperated by spaces
    if a=0 then b
    elif a<b then hcf a (b-a)           // notice: 2 arguments seperated by spaces
    else hcf (a-b) b

So 'let' is kind of like 'dim' in VB, or 'var' in C# / Javascript, but, er, not really. 'rec' means that the call is recursive. You can't have a function that calls itself without the 'rec' identifier. Can't say that I am a fan of 'elif' instead of 'elseif'.

I wanted to test to see if this function really works as indicated. Some tests I thought up in my head:

hcf 15 5 // Should return 5
hcf 48 52 // should return 4
hcf 1 1 // should return 1

I could have deleted all the other redundant code, and entered my 3 tests above, then compiled and run it, but I suppose I would also have to print out the results or some such... too much hassle! So I highlighted the function definition and pressed ALT-RETURN to run it in interactive mode. Then in the interactive window, I typed each example, placing ;; at the end. Each time it returned the correct result:

val it : int = 5

Finally I wanted to see the DirectX demo again that Leon showed in his presentation. The MSI also installs these examples, and I ran the DirectX demo in script mode, just to prove to myself Leon isn't a trickster or a witch (burn him!). Very impressive stuff.

Great! I now feel that I can put F# on my resume. I am interested in exploring it some more. I have some thoughts around graphing and other mathematical applications. I am particularly interested in finding examples of complex algorythms made extremely simple through the F# syntax. Finally, since FSI can effectively be called script-like (and there are those mysterious FSX files), what advantages might we be able to see in using it with other scripting tools/languages like PowerShell?

Oh, see you all at the launch on Wednesday.

Some interesting things announced today. First, the official dates for ReMIX Australia:

Sydney: Tuesday 20th May
Melbourne: Thursday 22nd May

To be honest I've never been, but I think I'll see if it's doable this year.

Secondly, the speakers for CodeCampOz are announced! Check out the sessions here.

Of particular interest to me are the following sessions:

• Interactive video using Silverlight and WCF - Jonas Folleso
• ORM Smackdown - Adam Cogan

Oh and don't forget the Readify presenters!

• Mitch Denny
• Phillip Beadle
• Mahesh Krishnan
• Luke Drumm

Finally, my new Microsoft SDC friend: Joseph Cooney on Silverlight 2.0 and WPF (even though it doesn't say WPF on the CodeCampOz site, trust me, he's doing a WPF / SL comparison).

All in all its going to be a great weekend! Look forward to seeing you all there.

No doubt you've hit F5 to debug your web application from time to time, and you noticed the little web server that sits in your system tray.

In the old days you needed to have your web site setup as a virtual directory in IIS in order to be able to debug it. Now days it's a lot easier: the first time you debug Visual Studio starts up its own mini-IIS that hosts your web application and lets you debug. This works for web sites, ASMX web services, and WCF services.

By default, it assigns a random port on the local machine. If you already have IIS then no doubt it is configured to use port 80, which is why the VS web server uses another random one. When your application loads up in browser, it will usually have a URL similar to this:

http://localhost:53669/default.aspx

Even when you stop debugging, the web server continues to run! Which means you can manually open a browser and still hit that same location. This is perfect if you don't have a version of XP or Vista that comes with IIS.

However, by default the port number is random. This means tomorrow when you go to open and debug your application, it will run up with a different port number. Sometimes this is no big deal, but with web services and (in my case) WCF services, this hurts. Your WCF endpoints will be configured for debugging and the endpoints will specify the port number, so that you can debug them in VS. Every time the VS web server starts up, it gets a new random port number, which you then have to update in your WCF client endpoint.

Luckily the internal web server is configurable. With your web projects there is a property under the project properties - Web section:

By default, the "Use Visual Studio Development Server" option is checked, and "Auto-assign Port" is selected. However you can change this to "Specific Port" as I have in the above example. You can also configure the web server further to pretend to use a virtual directory. This is great because it allows you to simulate production environments by specifying the same combination of ports and virtual directories as would exist on the production server.

Of course, you can save yourself the hassle of having multiple web servers running at once by just selecting "Use IIS Web Server" instead, however this isn't ideal in environments where multiple people work on a project and could potentially have different workstation setups.

Further Resources
ASP.NET and IIS Configuration
Build Web Server Solutions with End-To-End Extensibility
Web Servers in Visual Web Developer
Troubleshooting the ASP.NET Development Server

Sql Server Notification Services can be tricky to debug. You have no code that you can put a breakpoint in (except for your managed api calls of course) and there's a lot of working parts inside. Here's a couple of tips that have helped me today dealing with a local and alpha problem.

Rule Testing
After you upload your instance and the application is created, a view is created for your event, subscription, and notification schemas. This means that the Sql you define in your subscription rule can be run against the table. I tend to remove the "INSERT" part of the rule, and just execute the select to make sure that my event is getting picked up and associated with a subscriber.

Even one step lower, you can just view the contents of your events schema (view) to make sure the event was posted there correctly, and view your subscriptions schema (view) to ensure that the correct subscription information is in there.

Enable Distributor Logging
In your Application XML there is a node for settings called <ApplicationExecutionSettings>. You can use this to turn on 3 layers of debugging in your Notification Services application as follows:

<DistributorLogging>
    <LogBeforeDeliveryAttempts>true</LogBeforeDeliveryAttempts>
    <LogStatusInfo>true</LogStatusInfo>
    <LogNotificationText>true</LogNotificationText>
</DistributorLogging>

Obviously this will add some overhead to your processing, but if you don't have high through-put then you could leave this on all the time. But for initial setups (such as on your local machine, or on production databases) it is invaluable.

As the name suggests, the logging occurs around distributions of notifications. Your event should get stored in the relevant table after it is submitted, and your rule should process the events and post them to the notifications table. At this point, the distributor logging kicks in. When the service 'ticks' and processes your notifications for delivery, information is logged in a view matching your notifications view. For example, if your notifications class name is "BlogUpdates" then there will be a view automatically created called 'NSBlogUpdatesNotificationDistribution'. You can monitor this view for changes while you post an event that should trigger a distribution. Keep refreshing the view and you will see a new entry appear for a desired notification delivery. It details what delivery channel to use, the user, the content being delivered, and a status of the delivery. Eventually this will change to "Delivery Succeeded". If not, you can find information inline to assist in debugging.

Windows Event Log
Some problems are not specific to Notification Services. For example, your distributor account might not have read access to the XSLT needed to format the content for delivery. In these cases, information is posted to the event log.

Email Notifications
A final tip relates specifically to email notifications. I have noticed that if the SMTP server rejects the service sending the distributions (for whatever reason) you will not receive any information to the affect. Nothing appears in the event log, and nothing in the distributor log view. If you suspect this is your issue, then I can only suggest installing an SMTP relay locally and pointing your delivery channel to that server instead. At least you can get more information in your SMTP logs this way.

More Information On Notification Services
My 4 part series for beginners:
Notification Services - Part 1 - Technology Overview
Notification Services - Part 2 - Example Overview and Instance XML
Notification Services - Part 3 - Application XML
Notification Services - Part 4 - Managed API

Notification Services tutorial: http://msdn2.microsoft.com/en-au/library/ms170337.aspx
MSDN help: http://msdn2.microsoft.com/en-au/library/ms172483.aspx
API reference: http://msdn2.microsoft.com/en-au/library/microsoft.sqlserver.notificationservices.aspx

Presumably you subscribe to blogs. You might even subscribe to this blog. How many do you subscribe to? What about other feeds, like Engadget? Podcasts? What about sites you read manually, like your local newspaper site?

Let's be honest, there's a lot of information on the web that we would like to be able to digest. 3 years ago, I would simply load up my browser, go to a url of a site, and read the articles. This is how I kept up with the technology industry and the goings-on. Unfortunately it was hard to sort through and get to the quality pieces of information that I really wanted to know about.

Then I started subscribing to blogs. A few at first. People who were at the top of their game and were driving the technologies I was interested in. I tried some other tools (including Outlook) for periods at a time, and eventually came across Google Reader. By now my list of feeds had grown.

Content Is King

I was following the big corporate bloggers as well as the little guy down the street. I was more interested in the content of the post than the poster themselves. In a move that would shock the world, some of the big guys on campus were scratched from my feed list. I spent a fair amount of time customising my Reader with the information I really wanted to receive. I still had a dilemna though: what about those posters who provide quality sometimes, boring crap other times? Well I guess I just had to skip those entries, 'mark as read', although sometimes I didn't know the post was crap and not related until I had spent time reading the first few lines or summary.

Enter Particls

I can't remember how I first came across Particls. But for me it was a smash hit instantly. The essence of Particls is about attention management. From their About page:

The web is just too big. No one has time to keep track of all the sites and topics that interest them.

You see, every person, site, feed has something interesting to say at some point. Why not have a system that can rate and prioritise the information for you so that you only get presented with information you are specifically interested in?

For example, with Particls I can specify all those blog feeds I follow in Reader (imported as OPML of course) and all those feeds I previously removed. Then I can prioritise them individually: which ones are more important to me on the whole? Further, I can specify key words that I am interested in, and keywords that I am not interested in.

Particls will present the inf ormation to me based on relevancy. By spending a certain amount of time up front defining the kinds of information I want to hear about, Particls can continue to deliver information that I specifically want to read.

Furthermore, you can tell Particls to search for information. This means even if you don't have any blogs you subscribe to, you can still specify keywords of interest, and let Particls do the rest.

The information can be delivered to you in a number of ways. If you must, you can get the annoying popups around the system tray area. You can get a news ticker across the top, or a nice sidebar (my personal choice). You can use multiple options if you like: tell your news ticker to display only the most relevant and important information, tell your sidebar to disappear when not in use and show less relevant information. Particls can even provide an RSS feed for you to consume in another reader if you so desire.

On my wide screen it works great with Vista sidebar. If you get a notification that is inaccurate, you can simply right click and tell it to give less information about this topic. In this way, Particls quickly learns what your priorities are in order to deliver you more relevant information.

Oh, did I mention Particls is free? Enough reason to go and give it a shot.
Even better, it is produced by a local Brisbane (Australia) company called Faraday Media.

Currently the download link on the site is disabled. I believe this is because they might be moving from beta to production (can anyone shed light on this?). I'll let you know as soon as I hear something.

Update: I've tried to contact Chris Saad from Faraday Media about this a few times this week but didn't want to delay the article any longer waiting for a reply.

In the first 3 parts of this series we discovered how to define a Notification Services application via the instance and application XML. In part 2 we defined an example scenario where users are automatically subscribed to receive notifications in their email whenever someone posts a comment against their blog post. In this part we will discover how to write code to access the event schemas we defined in part 3, and how to insert subscribers. For the sake of brevity, this post will define sections of code, not entire classes. Assume a class library project in C# that will be called by our main blog ASP.NET application. The methods defined in this post would be found in such a library.

This post assumes that the Notification Services instance is installed on the same machine that will be running the code. This is important because to access a NS instance, you don't use connection strings as is typical in ADO.NET. Instead, it refers to registry entries which are automatically placed by NS when the instances is 'Registered' and 'Started'. For more information, see the MSDN link.

Preperation
Our class library project will need access to the Notification Services libraries in order to communicate with Notification Services. You can add this through references. The assembly file name is Microsoft.SqlServer.NotificationServices.dll. This assembly is installed in the GAC when Notification Services is installed (with SQL Server).

At some stage we will also need to define what our Instance name and Application name is. We could put this in a constant but ideally it would be in web.config and accessible through a property somewhere. This code will assume a class called 'Settings' which has properties called 'InstanceName' and 'ApplicationName'. Eg. string application = Settings.ApplicationName;

A lot of the time we will need access to an instance of a class called NSInstance. Through this class we can get access to our NS application, by getting an instance of NSApplication. The rest of this post will refer to instances of both of these classes, so we will define some code for them now:

NSInstance BlogInstance = new NSInstance(Settings.InstanceName);
NSApplication BlogApplication =
             new NSApplication(BlogInstance, Settings.ApplicationName);

In Notification Services an instance can have multiple applications, even though previously we have defined only 1.

Subscribers
First we'll define some methods for subscribing and unsubscribing users. Before we do this, we need to think about how authentication is tracked. For simplicity sake, we will assume that users are authenticated by active directory. This means the current windows principal will provide us with a username as a string:

string userId = WindowsIdentity.GetCurrent().Name;

You may remember from our application schemas that we needed to store a UserId. This was a simple string that represents the user a subscription belongs to. Before we can add subscriptions, we need to first check that the instance has the user registered as a subscriber. We can do this as follows:

public bool Exists(string userId)   {
         SubscriberEnumeration mySubscriberEnumeration =
                new SubscriberEnumeration(BlogInstance);
         Subscriber mySubscriber = mySubscriberEnumeration[userId];
         return (mySubscriber != null);
}

As you can see we use our BlogInstance to access an enumeration of all users, which can be indexed by the user's name. We could easily modify this into a Delete method for a subscriber as follows:

if (mySubscriber != null)  mySubscriber.Delete();

Now we know how to check for a subscriber, we can write code to add one:

if (Exists(userId)==false) {
      Subscriber subscriber = new Subscriber(BlogInstance);
      subscriber.Enabled = true;
      subscriber.SubscriberId = userId;
      subscriber.Add();
}

Simple! If we don't check for a subscriber first, an exception will occur if a name is added twice.

Devices
In my last post I discussed Devices very quickly. Devices allow you to specify different delivery locations for different subscriptions. For example, I might want to receive notifications by email and instant message. We need to define a device for our subscriptions to be allocated against:

            SubscriberDevice device = new SubscriberDevice(BlogInstance);
            device.DeviceName = "WorkEmail";
            device.SubscriberId = userId;
            device.DeviceTypeName = "Email";
            device.DeviceAddress = "myrealemailaddress@hotmail.com";
            device.DeliveryChannelName = "SMTP";
            device.Add();

DeviceName is often referenced in your application XML rule for subscriptions so it is usually important to have a naming standard for your devices. However we have not been using devices up to this point so the values you put here aren't important for now.

DeliveryChannelName however is extremely important. In part 2 we defined the instance XML and part of that was the <DeliveryChannels>. In that XML we defined a protocol of type SMTPDelivery with a name of SMTP. When defining the device delivery channel name, it must match one of the channels specified in your instance XML otherwise no deliveries will be sent (no exception will occur, however when the service runs your notifications, it is at this point that it will fail, and details will be inserted into the event log).

As with subscribers you can check if the device has already been added as follows:

SubscriberDeviceEnumeration deviceEnumeration =
                new SubscriberDeviceEnumeration(BlogInstance, userId);
SubscriberDevice mySubscriberDevice = deviceEnumeration ["WorkEmail"];
return (mySubscriberDevice != null);

As with subscribers, we should check the device has not already been added before commencing the insert process. And as with subscribers, deleting a device is as easy as calling the Delete method of the SubscriberDevice instance.

Subscriptions
Since we are only concerned with adding a subscription, the code for this is reasonably simple. Remember our requirements originally stated that a user will be automatically subscribed to a post after the post is created. This means we don't even need to check if the user is already subscribed since they couldn't possibly be. This makes our code even easier. Here is what the add method might look like:

public void Add(string userId, string deviceName, int PostId) { 
            Subscription subscription =
                         new Subscription(BlogApplication, "CommentSubscription");         
            subscription.SetFieldValue("DeviceName", "WorkEmail");
            subscription.SetFieldValue("SubscriberLocale", "en-au");
            subscription.SubscriberId = userId;
            subscription.SetFieldValue("PostId", PostId);
            subscription.Add();
}

Because the .Net type subscription has no way of knowing at design-time what fields your subscription schema might have, it uses a common method for setting your subscription fields. This means you won't get compile errors if you don't really have a "PostId" in your subscription schema in Notification Services, but you will get a runtime exception on the subscription.Add();  method call.

Important to note is that in the constructor for a Subscription takes an NSApplication instance now. This is because even though subscribers and devices are specific to an instance, an actual subscription is specific to an application only. Also note the second parameter of the constructor. This is the name of the subscription class we are subscribing to. Note that the name we supplied 'CommentSubscription' is the name we specified for our subscription class in the application XML. Once again, this will cause a runtime exception at the subscription.Add(); method call if the subscription class name is invalid.

Well done! The user is now subscribed to receive notifications when comments are posted. However we still have to define how comments are posted to Notification Services so that those subscriptions can be acted upon.

Events
Going back to our Events schema defined in our application XML, there is a number of fields we need to supply information for. The Event class helps us set values for those fields very easily, just like it does for subscriptions. To add an event to Notification Services is as easy as this:

Event event = new Event(BlogApplication, "NewCommentEvent");
event["PostId"] = postId;
event["Name"] = CommentPosterUserName;
event["Details"] = CommentText;

EventCollector eventCollector =
                new EventCollector(BlogApplication, "BlogEventsProvider");
eventCollector.Write(event);

In this code, we assume that we already have the values of the comment text, the user who posted the comment, and the original blog postId that the comment was posted against. The Event class lets us define the details to post to Notification Services through an indexer, and the EventCollector class will write the events to Notification Services for us. As usual incorrect fields specified will result in a runtime exception.

Some items to note here. First, the constructor for an event needs the name of the event class we are posting to. We only defined 1 in our events schema; this was defined in the last post in our application XML. Secondly, in our last post we also defined the <Providers> node and the <NonHostedProvider> sub node (right at the end). When defining an EventCollector we must pass our provider name to the contstructor. You can not post an event to Notification Services without using one of the providers specified in your application XML. Because we are specifying events in code outside of Notification Services, our provider is a 'NonHostedProvider': not hosted by Notification Services.

Summary
Well that's it. We call the events to post a subscription in the very next line of code after we post our blog entry. And we call our event method whenever someone posts a comment against a blog entry. And Notification Services will take care of the rest.

This brings us to the end of my series on Notification Services. If there is anything else you would like to know about, please don't hesitate to contact me and I'll do my best to provide useful information.

Notification Services Series
Notification Services - Part 1 - Technology Overview
Notification Services - Part 2 - Example Overview and Instance XML
Notification Services - Part 3 - Application XML
Notification Services - Part 4 - Managed API

Further Resources
Notification Services tutorial: http://msdn2.microsoft.com/en-au/library/ms170337.aspx
MSDN help: http://msdn2.microsoft.com/en-au/library/ms172483.aspx
API reference: http://msdn2.microsoft.com/en-au/library/microsoft.sqlserver.notificationservices.aspx

The application XML defines the key information about your Notification Services (NS) application. This includes the schemas for event data being received, schemas for what users can subscribe to, and schemas for the information that will be sent in a notification. At the bare minimum you need 1 schema for each section. The application XML is defined with the following elements:

<?xml version="1.0" encoding="utf-8" ?>
<Application xmlns:xsd="..."  xmlns:xsi="..."  xmlns="...">
    <EventClasses></EventClasses>
    <SubscriptionClasses></SubscriptionClasses>
    <NotificationClasses></NotificationClasses>

    <Providers></Providers>
    <Generator></Generator>
    <Distributors></Distributors>
    <ApplicationExecutionSettings></ApplicationExecutionSettings>

</Application>

Here you can see the sections where we define our 3 different schemas: EventClasses, SubscriptionClasses, and NotificationClasses.

Events
Continuing on from the example we mentioned previously, users will subscribe to comments for a particular blog. This means that the comment itself is an event: when a comment is sent to notification services, the system checks for any subscribers who should be notified, and notifies them. This means that the comment is in fact our event.

It is important to decide early on what information you want to track about the comment. In our case, users will be subscribing to receive comments for a particular blog post. The best way to track a blog post is by its Id. Referring to the schema defined in part 2 each blog post has a 'PostId' and this is referenced as a foreign key to the Comment table. This is the first item of information we will need in our schema. No doubt we'll also need to send notifications with the comment title and contents, so we'll add those two fields to our schema as well. Our final entry for the application XML looks like this:

<EventClasses>
    <EventClass>
        <EventClassName>NewCommentEvent</EventClassName>
        <Schema>
            <Field>
                <FieldName>PostId</FieldName>
                <FieldType>int</FieldType>
                <FieldTypeMods>not null</FieldTypeMods>
            </Field>
            <Field>
                <FieldName>Name</FieldName>
                <FieldType>varchar(255)</FieldType>
                <FieldTypeMods>not null</FieldTypeMods>
            </Field>
            <Field>
                <FieldName>Details</FieldName>
                <FieldType>nvarchar(4000)</FieldType>
                <FieldTypeMods>not null</FieldTypeMods>
            </Field>               
        </Schema>
        <IndexSqlSchema>
            <SqlStatement>
                CREATE INDEX KnowledgeEventIndex
                ON KnowledgeEvent ( PostId );
            </SqlStatement>
        </IndexSqlSchema>
    </EventClass>
<EventClasses>

When your instance XML is imported into NS, and the application XML is processed, these fields will actually be created in a new table. You can also see we have defined an index that will be created in the same table.

Notifications
This is quite simple to define. What information will our users receive in their email? Well we already had to consider this when defining our event schema. The user will receive the comment name and contents in their email. So this is the only information we need to define in our schema for notifications:

<NotificationClasses>
    <NotificationClass>
        <NotificationClassName>BlogCommentNotification</NotificationClassName>
        <Schema>
            <Fields>                   
                <Field>
                    <FieldName>Name</FieldName>
                    <FieldType>nvarchar(255)</FieldType>
                </Field>
                <Field>
                    <FieldName>Details</FieldName>
                    <FieldType>nvarchar(4000)</FieldType>
                </Field>                   
            </Fields>
        </Schema>
        <ContentFormatter>
            <ClassName>XsltFormatter</ClassName>
            <Arguments>
                <Argument>
                    <Name>XsltBaseDirectoryPath</Name>
                    <Value>....</Value>
                </Argument>
                <Argument>
                    <Name>XsltFileName</Name>
                    <Value>NotificationFormatter.xslt</Value>
                </Argument>
            </Arguments>
        </ContentFormatter>
        <Protocols>
            <Protocol>
                <ProtocolName>SMTP</ProtocolName>
                <Fields>
                    <Field>
                        <FieldName>Subject</FieldName>
                        <SqlExpression>'[BLOG_COMMENT] ' + Name</SqlExpression>
                    </Field>
                    <Field>
                        <FieldName>From</FieldName>
                        <SqlExpression>N'blogbot@snagy.name'</SqlExpression>
                    </Field>
                    <Field>
                        <FieldName>To</FieldName>
                        <SqlExpression>DeviceAddress</SqlExpression>
                    </Field>
                    <Field>
                        <FieldName>Priority</FieldName>
                        <SqlExpression>N'Normal'</SqlExpression>
                    </Field>
                    <Field>
                        <FieldName>BodyFormat</FieldName>
                        <SqlExpression>N'html'</SqlExpression>
                    </Field>
                </Fields>
                <ProtocolExecutionSettings></ProtocolExecutionSettings>
            </Protocol>
        </Protocols>
    </NotificationClass>
</NotificationClasses>

The first part of the <NotificationClass> node is very simple to create. First we give our schema a name via the <NotificationClassName> node. Then we define our 2 fields in the <schema> node.

Next we go on to define our content formatter. In our case, we want to use a stock standard XSLT to define our markup. So we specify its base path and file name. Finally, we want to define what protocol to use for this notification class. In the last post we defined our <DeliveryChannels> in the instance XML. Here, we must match a valid protocol from that list. We only defined one: of type SMTPDelivery, and called it 'SMTP'. We use that name here and go on to define all the important fields required for sending an email. Note that the <SqlExpression> field specifies the value to use. This actually is a valid SQL expression; the value you supply here is translated into an SQL statement to retrieve the values required for the notification. For example, the 'To' section specifies DeviceAddress as the value to use for this field. We'll learn about the DeviceAddress and where it comes from a little later, but suffice to say it is pulled from the database. For absolte literal values, we follow normal SQL conventions and put them in 'single quotes'. In the case you want to combine a literal value with a database field, combine them with normal SQL syntax, such as in the case of the 'Subject' field where we defined the literal '[BLOG_COMMENT] ' and the database value Name (which is the comment name).

Subscriptions
Next we have to define how to turn event data into notifications, and we do this through the <SubscriptionClasses> node:

<SubscriptionClasses>
    <SubscriptionClass>
        <SubscriptionClassName>CommentSubscription</SubscriptionClassName>
        <Schema></Schema>
        <EventRules>
            <EventRule></EventRule>
        </EventRules>
    </SubscriptionClass>       
</SubscriptionClasses>

As usual, we give our subscription class a name through the <SubscriptionClassName> node. Then, we define 2 parts to our subscription: the schema defining what fields can be subscribed to, and the rule that will process an event and turn it into a notification.

The schema follows the same format as the <EventClasses> schema. For our application, we only want the user to be able to subscribe to a particular blog post, so we specify the PostId. However, we also want to track subscriptions on a 'per device' basis, so we also need to track what device the user is subscribing with. This manifests in our schema as follows:

<Schema>
    <Field>
        <FieldName>DeviceName</FieldName>
        <FieldType>nvarchar(255)</FieldType>
        <FieldTypeMods>not null</FieldTypeMods>
    </Field>
    <Field>
        <FieldName>PostId</FieldName>
        <FieldType>int<FieldType>
        <FieldTypeMods>not null</FieldTypeMods>
    </Field>
</Schema>

Essentially, any subscription being made to the application will have to supply a device name and a PostId. However, when this schema is created as a table, Notification Services adds some other fields, such as a SubscriberId. In fact, all the schemas we've seen so far will be slightly modified by NS to keep things running smoothly.

Next we must specify the rule to bring it all together. This rule takes the form of an SQL statement which joins potential subscriptions on to events. Each resulting row is a notification to be sent, and is parsed through the NotificationClass schema and formatters. Here is the <EventRule> we need to create notifications:

<EventRule>
    <RuleName>CommentSubscriptionRule</RuleName>
    <EventClassName>NewCommentEvent</EventClassName>
    <Action>
        INSERT INTO BlogCommentNotification (SubscriberId, DeviceName, Name, Details)
        SELECT s.SubscriberId, s.DeviceName, e.Name, e.Details
        FROM NewCommentEvent e, CommentSubscription s
        WHERE e.PostId = s.PostId ;
    </Action>
</EventRule>

So first up we give our rule a name. Next, we define which event class we are comparing against for subscriptions. We only have one: NewCommentEvent. Finally the <Action> node defines our SQL statement that discovers potential notifications. Later on we define a time interval for how often NS should check for new notifications. When this interval fires, NS goes through all Event Rules and runs them.

So lets delve into that a little further. Lets pretend NS is configured to fire off notification checks every 4 hours. Over a 4 hour period, our blog site gets 15 comments spread over 3 different blog posts: PostId 17, 18, and 19. NS already has received subscriptions for PostId 17 only, however 3 people are subscribed to that single post. In total 7 comments were made. The 4 hours expires, and the above SQL statement is processed. The result of the select statement will return 21 rows, which are inserted into the 'BlogCommentNotification' table. Another process fires and passes each row in this table to our XSLT formatter, and sends the notification via the defined channel (SMTP).

Other Settings
Besides the Events, Subscriptions, and Notifications classes, we originally mentioned some other nodes in our application XML. These provide settings for how often the service should check for notifications, trace detail levels, and vacuuming (the process of cleaning out data from events table once sent, etc). For example, with the <Distributors> node you can specify a different machine as being responsible for sending the notifications (useful for high-load scenarios). The only other node worth specifically mentioning is the <Providers> node:

<Providers>
    <NonHostedProvider>
        <ProviderName>BlogEventsProvider</ProviderName>
    </NonHostedProvider>
</Providers>

This node is used to define how events get submitted to the application. If you intend to provide events through the managed API (as we are) then this must be set to a <NonHostedProvider>. The name you specify here will be used in your code. More on this in the next post.

Summary
Well that wraps it up. Sorry for such a long post: I just didn't want to separate the application XML out into different posts. Note that all 3 major classes allow you to supply multiple schemas. This way you can have different kinds of notifications, different delivery methods, etc all depending on how users subscribe. The additional setting nodes that we didn't cover in detail can be found in the MSDN reference mentioned at the bottom. Next post will cover the managed API, specifically how to submit events, and how to add/remove subscribers.

Notification Services Series
Notification Services - Part 1 - Technology Overview
Notification Services - Part 2 - Example Overview and Instance XML
Notification Services - Part 3 - Application XML
Notification Services - Part 4 - Managed API

Further Resources
Notification Services tutorial: http://msdn2.microsoft.com/en-au/library/ms170337.aspx
MSDN help: http://msdn2.microsoft.com/en-au/library/ms172483.aspx
API reference: http://msdn2.microsoft.com/en-au/library/microsoft.sqlserver.notificationservices.aspx

As mentioned in part 1 of my discussions about NS, I described how 'Subscribers' can subscribe via certain 'Devices' to 'Events' to receive 'Notifications'. In this post, I will demonstrate how to declaratively define your Notification Services instance. In following posts I will discuss how to create your application XML and talk to Notification Services using the API.

Example Overview

Previously we mentioned a user's blog as an example. We'll continue with that concept here. Imagine the database schema for a blog: You have 'Posts' which are performed by 'Users', and people can publish 'Comments' to them. A simple schema might look like this:

You want to be able to let the Users of the blog subscribe to Comments made against particular posts. You've already built the main web application where users can login and post new blog articles. Now you want to extend the application to allow for notifications, and decide to use Notification Services as your technology.

So you come up with a design and decide on the following:

1. Only the writer of a blog post can subscribe to the comments for that post
2. Subscription will be automatic: As soon as the 'Publish' button is clicked, the user is subscribed to receive notifications. That way you don't have to write any new web pages for subscribing/unsubscribing - You'll deal with that in a later version
3. Notifications will be delivered by email. They will contain the title of the blog post being commented against, and the details of the comment itself.
4. All comments will be emailed to the user to keep it simple.

You now have to do a couple of things. The first is to create the Notification Services instance/application, and the second is to modify your existing blog code to do 2 things: auto-subscribe a user who writes a post, and to also send all comments to Notification Services.

Instance XML

You decide to call your instance 'Intranet' and this specific NS application 'BlogNotifications'. First you have to create the instance XML, and the first draft looks something like this:

<InstanceName>Intranet</InstanceName>
<SqlServerSystem>(local)</SqlServerSystem>
<Applications>
    <Application>
        <ApplicationName>BlogNotifications</ApplicationName>
        <BaseDirectoryPath>...</BaseDirectoryPath>
        <ApplicationDefinitionFilePath>  ...  </ApplicationDefinitionFilePath>
        <Parameters>
             ...
        </Parameters>
    </Application>
</Applications>

<DeliveryChannels>       
    <DeliveryChannel>
        <DeliveryChannelName>SMTPDelivery</DeliveryChannelName>
        <ProtocolName>SMTP</ProtocolName>
        <Arguments>
            <Argument>
                <Name>SmtpServer</Name>
                <Value>smtp.myhost.com</Value>
            </Argument>
            <Argument>
                <Name>BodyEncoding</Name>
                <Value>utf-8</Value>
            </Argument>
        </Arguments>
    </DeliveryChannel>
</DeliveryChannels>

This means that you want an instance called 'Intranet' to be created on the local server. The available delivery channels to this instance are only SMTP at this stage. The name 'SmtpServer' is the name that will be used by your application code to reference what delivery channel to use for a particular subscription (more on that later). In Notification Services, anyone who is a subscriber, is defined at the instance level. This means only 1 list of subscribers is maintained for multiple applications.

The application will be called 'BlogNotifications' and the 'ApplicationDefinitionFilePath' points to the second XML file we need to define. As mentioned earlier, you can have multiple applications in an instance. Here we have defined only 1, as with the Delivery Channels.

It is possible to define variables to use in your instance XML to make things easier. These are called 'parameters' and when your instance xml is uploaded to Notification Services, it will prompt you for the values of any parameters you have defined. This works great in our case, because we may not want to 'hard code' the SMTP server. When testing we might use 1 server, but the production server might be somewhere else and therefore we would want to change the SMTP server at upload time. Parameters work perfect for this:

<ParameterDefaults>
       <Parameter>
            <Name>_SMTPServer_</Name>
            <Value>smtp.myhost.com</Value>
       </Parameter>
</ParameterDefaults>

We would then alter our deliver channel code like this:

<Argument>
        <Name>SmtpServer</Name>
        <Value>%_SMTPServer_%</Value>
</Argument>

You can define any number of parameters. You can even use machine variables from the local OS in your parameters, as follows:

<Parameter>
         <Name>_Server_</Name>
         <Value>%COMPUTERNAME%</Value>
</Parameter>

Finally, you can pass on values to your Application by defining some parameters for your application XML:

<Applications>
        <Application>
           <ApplicationName>BlogNotifications</ApplicationName>
           <BaseDirectoryPath>...</BaseDirectoryPath>
           <ApplicationDefinitionFilePath>  ...  </ApplicationDefinitionFilePath>
           <Parameters>
                <Parameter>
                    <Name>_NSServer_</Name>
                    <Value>%_Server_%</Value>
                </Parameter>
            </Parameters>
        </Application>
</Applications>

Here we are passing the value of a paramter called _Server_ as a parameter to the application XML called _NSServer_.

That pretty much sums up the instance XML. In the next part, I'll discuss the Application XML how to link notifications to subscriptions.

Notification Services Series
Notification Services - Part 1 - Technology Overview
Notification Services - Part 2 - Example Overview and Instance XML
Notification Services - Part 3 - Application XML
Notification Services - Part 4 - Managed API

Further Resources
Notification Services tutorial: http://msdn2.microsoft.com/en-au/library/ms170337.aspx
MSDN help: http://msdn2.microsoft.com/en-au/library/ms172483.aspx
API reference: http://msdn2.microsoft.com/en-au/library/microsoft.sqlserver.notificationservices.aspx

A new year comes with a new job and a new perspective.

One of my personal goals this year is to increase my community involvement. There are lots of user groups in Brisbane, and similar opportunities Australia wide. I've filled in my Outlook calendar with all the upcoming events and thought I'd share the list with you as well (for the next month):

• 30/1/08 5:30pm : BizTalk user group - Mark Daunt on RFID support in BizTalk
• 01/2/08 7:30am : VSTS user group - Grant Holiday on securing TFS
• 19/2/08 5:30pm : QLD MSDN user group
• 28/2/08 5:30pm : SQL Server user group

Also, in April (26th and 27th) is CodeCampOz. Although I've never been before, I'm aiming to drive down this year. Want to car pool? CodeCampOz has been described to me as a mini Tech.Ed except without the advertising.

Readify provide presentations called RDNs which I hope to also get moved to Brisbane in the not-so-distant future. RDNs are like user groups, but the content can have more depth. Getting these in Brisbane will be great for the local development community.

My blogging will hopefully increase in both quantity and quality. Currently I am working with Notification Services, Visual Studio 2008 and .Net 3.5. All new technologies for me, which means more tidbits to learn and share with you.

I've also decided to move my blog to Windows Live Spaces. As portals go its not too shabby, and has a nice layer of extensibility. The official link is here. If you have a windows Live account then its easy for you to leave comments. Oh, and add me as a friend! I am currently cross posting to both old and new blogs for now, but you should definitely subscribe to the new version as soon as possible.

There's some projects I'd like to attack this year. I've found a podcast receiver that works on Vista called PrimeTIme Podcast Receiver, but am not wowed by it. So one of my plans this year is to build a podcast subscription tool. Could be a good candidate to learn some WPF as well.

I also want to work on a patterns web site that provides code examples in multiple programming languages.

Most importantly, this year I will get certified. I've delayed it for too long. I have a few certifications in mind long term, but currently I am aiming for MCTS in Web Applications.

Let me know if there is something you would like me to cover in my blog. Otherwise the direction will be random (as it has been). Also, if you would like to provide feedback on how to improve my writings/content, please feel free to be open and honest since it will only benefit you when my style gets better.

Watch this space.

Sql Server 2005 is more than just a relational database management system (RDBMS). It also contains a reporting engine called Reporting Services (SSRS), a data warehousing system called Analysis Services (SSAS), an engine for selectively pulling data from various sources called Integration Services (SSIS), and a subscription based notification engine called Notification Services (although I've not seen this notation, I presume we can say SSNS for short?).

Each of these items are a technology unto themselves and take time to learn and master. Recently I started with Readify and my first job was to do a proof of concept for an internal project. It involved Notification Services and I was able to learn some cool stuff to share with you.

SSNS is available in all versions of Sql Server 2005 ; all my development was done with Developer which costs around $80AUD. The core components of a SSNS instance are as follows.

Subscribers
Users must be in the subscriber list to add subscriptions. This is essentially a 'User' table in SSNS.

Subscriber Devices 
Users can receive their notifications in different ways. For example I might get a full detailed notification in my email, just the 1 line title on my MSN messenger, and a summary of all of the days alerts on my PDA.

Subscriptions
A subscriber can subscribe to a particular field in an event. For example, they may want to receive notifications when someone posts a comment on their blog that contains swear words. So the subscription uses a SQL query to look for key words in the blog comment, and if it finds them, the user will be notified.

Events
Events are the things occurring that may or may not cause notifications to go out. In the above example, the Event is the comment being posted. Every comment that gets added to the blog causes an event in Notification Services, but only the events with swear words in the comment field will cause notifications to go out.

Notifications
These are the content that are sent to users. They occur as a result of an event matching a subscription. They are sent on a channel such as email, file, service, etc. The notification is formatted with XSLT, and can use event data as necessary.

How It Works
So there's no real programming involved here. Essentially its all declarative via 2 XML structures. The first simply specifies the applications; its kind of like a solution in Visual Studio. It specifies what applications will exist, and also allows you to specify parameters for your XML files. Then you need 1 XML file per application. This file will contain XML schemas of your Events, Subscriptions, and Notifications. It also allows you to specify how notifications can be sent, and how events can be submitted.

Don't I Get To Write Code?
Yes you do. The API is very open to fiddle with. When you upload your XML files to SSNS it will create 2 databases, with lots of tables and stored procedures. The good news is that you don't have to touch those items. If you maintain your schemas in your XML files, it will ensure the tables are created correctly.

However, some of the stored procedures are there for you to call; particularly around submitting subscribers, devices, subscriptions, and events. So you could call those sprocs, or you could use the managed API for Notification Services. This is just an assembly you can add a reference to in your application. For example, create a windows app that provides the interface for logging in and adding/removing subscriptions. With a few quick method calls you have connected to your SSNS application and not had to write any SQL! I can't stress enough how easy it is to use this API. You can do everything you need, and its very logical to use.

Pulling It Together
Ok so think about this example. I want to receive email updates whenever anyone adds a comment on my blog that mentions 'Notification Services'. So I create an event schema that allows for a comment ID and content to be sent to SSNS. Then I create my notification schema with just the comment data field (since I don't need the ID in my email). Thirdly I create a subscription schema where I specify a field called 'SearchPhrase' and an SQL statement that inserts data into the Notification schema by searching the Event comment data for the search phrase.

Now I just need to specify how the event data gets into the event schema in SSNS. I have lots of options here:

• My comment code just calls a sproc, so I can change that sproc on the server to include a call to insert the event data into SSNS via a sproc
• I could add a trigger on the comments table in my database such that when data is added, it will also add that data to SSNS via a sproc
• In my .Net code I could just call the sproc to insert the comment data after I have added it to the database
• Or I could use the API mentioned earlier to add the subscription so I don't have to worry about nasty sprocs!

Oh I need to add a subscription too; since I now know SSNS well enough, I can just insert this into the right table; I don't plan on subscribing/unsubscribing continuously.

Notification Services Series
Notification Services - Part 1 - Technology Overview
Notification Services - Part 2 - Example Overview and Instance XML
Notification Services - Part 3 - Application XML
Notification Services - Part 4 - Managed API

Further Resources
Notification Services tutorial: http://msdn2.microsoft.com/en-au/library/ms170337.aspx
MSDN help: http://msdn2.microsoft.com/en-au/library/ms172483.aspx
API reference: http://msdn2.microsoft.com/en-au/library/microsoft.sqlserver.notificationservices.aspx

Thought I'd post this before I go on vacation. Today I resigned from my position as a Lead Developer for Zap Technology. I've been offered an excellent position with Readify, a company I've viewed from afar for about a year and a half now.

One of the things that sold me on Readify was their attitude towards the development community. Most people who attend user groups (anywhere in Australia) will have seen a Readify presentation. They hold a large percentage of the Microsoft MVPs in Australia and empower their employees to do the same if they so desire. In fact they even give you incentives to get active in your community.

These are all the things I love to do: And they want to pay me to do it!

Well I start with Readify in mid January. I was planning to move this blog to Microsoft Live Spaces when I got back but I'll reconsider this move now. One thing's for certain is that my postings will increase in frequency and in quality. Hopefully they'll sound less like a letter written to my mother, and provide more technical information.

I also have a personal mission that I have challenged myself with: To drive the Brisbane/QLD development community, to the point where the other states get jealous. I hear so much about what's happening in other states on various blogs, but never Brisbane. This might be because I read the wrong blogs, but I'm a patriot none-the-less, and I want to see user groups with turnouts in the hundreds! I also want to see some deviation and expansion. Perhaps a Rich Web user group? Or a group dedicated to code quality (which fits with another idea I hope to act upon next year)? All ideas are welcome, and if you have any ideas for an open source project, I'd also be keen to hear.

I'll use my holiday to think through some strategies for how to achieve these meager goals.

I wonder if Readify have an indoor soccer team?

I'm sorry! I've been so busy, posting has suffered.

I am now the Lead Developer for our primary Business Intelligence product at Zap Technology. My 3 month review at Zap resulted in this promotion which I happily accepted. Those who know me know that I was in a Lead Developer position prior to Zap.

This post though is more of an encouragement to all you fellow Australian developers. The Australian dollar is doing quite well against the US dollar. Now is a great time to buy those technical/reference books you always wanted! My recent Amazon order went in when the dollar was at USD $0.92. Normally I purchase theory related books but saw this as a good opportunity to get some reference books as well. Here's my order, some of which have already arrived:

• Implementation Patterns - Kent Beck
• LINQ In Action - Fabrice Marquerie, Steve Eichert, Jim Wooley
• ASP.NET 2.0 Web Parts in Action - Darren Neimke
• ASP.NET AJAX in Action - Alessandro Gallo, David Barkol, Rama Vavilala
• Programming WCF Services - Juval Lowy
• Programming WPF - Chris Sells, Ian Griffiths
• C# in Depth - Jon Skeet

Hopefully you recognize some of the names. Kent Beck has been around the code quality scene for ages, and this new book of his is due out in January. Darren Neimke works for Readify, a Microsoft Gold-Partner consulting firm in Australia. Jon Skeet is a Microsoft MVP based in the UK. I respect Jon's commitment to the community and enjoy is writing style in news groups, and am looking forward to his first .Net related book in January.

So get those orders in! Create yourself a wish list and get your family to buy you some books for Christmas.

This will be the last blog post until after the Christmas season, so happy new year to you all!