Azure Application Insights: Know Your Users

(The layout of this blog post is terrible, I know. Blogger.com just seems not to be suitable for pictured step-by-step guides. Or at least not with the amount of effort that I was willing to spend.)

When I was looking for a way to collect voluntary usage statistics for a desktop App, I stumbled upon Application Insights, which is a Microsoft Azure service that is currently in preview. There is an introduction and further readings on MSDN. However, I will give a short summary of which steps to take to set AppInsights up and what the results will look like so you can get a quick glance at what you can expect.

Feature Summary

Feature	Use cases
Track pages	Track which pages (web), windows (desktop) or screens (mobile) are visited how often by your users and what they load time was.
Track sessions	Track all active server sessions (web) or running app instances (desktop and mobile).
Track events	Track some meaningful events for you, such as clicking of a certain button, choosing a certain option or executing a certain command.
Track metrics	Track how often something in your app happens, how many datasets your users manage with your app or some other averages.
Track web requests	Web only: Track requests to other web services and how long they take.
Track crashes and traces	Track detailed information about crashes, exceptions or some other unexpected situation, including full call stacks and many other properties, such as geographical area, operating system, and more.
Custom properties	Attach custom properties of any kind either to the context that all metrics are collected in, or for each telemetry item itself.
Time range	Specify the time range that should be included in the graphs on the App Insights dashboard.
Alerts	Specify alerts that trigger when certain conditions are met (such as when more than 100 exceptions are logged within 15 minutes). This seems to be useful for web services only.
Data export	You can download data for any kind of telemetry item as an Excel spreadsheet.
Continuous export	If the one-time export is not enough, you can continuously export to an Azure storage space. This seems to be possible in JSON format only, so you need some hand-crafted code to process the data any further. See https://azure.microsoft.com/en-us/documentation/articles/app-insights-export-telemetry/ for more details.

Requirements

Application Insights runs on Microsoft Azure, so an Azure subscription is a prerequisite. You can use it either on mobile apps (iOS and Android), web sites and services (ASP.NET, WCF, J2EE) or desktop apps (either Classic or Windows Store Apps - in other words: anything written in .NET). AppInsights is free for a limited number of datasets and will cost about $25,- for standard and $100,- for premium accounts. See the pricing table.

Getting Started

For the impatient, there is a TL;DR version of it at the bottom.

To get started, you need to log into your Azure account at the new Azure Portal or register for a new account, and add Application Insights.
When you first log in, it looks something like this:



The design of the home screen is kept in the tiled style, just like the Windows 8 start page or Windows Phone home screens. I personally find this pretty neat and clear.

You can add Application Insights by hitting the big fat + in the upper left corner and then browse to [Developer Services > Application Insights]. A shortcut on the "Home Screen" will be created automatically for you. But before, you will have to set up your new instance of Application Insights.
First you have to select the Application Type. I think this does not influence the capabilities of the instance at all - instead only a few default settings and pinned elements on the dashboard will differ. I find the names a bit misleading, personally, since there is no clear mapping from the name to the underlying technology. E.g. I use the type "Windows Store Application" for a classic desktop application written in C# and WPF. I have no idea what a Resource Group is, but rumor has it you can find out more here. If you have multiple Subscriptions you can select the one that should be billed for this AppInsights instance here. Currently, there is only the "Central US" Location. I guess, if App Insights will find it's users, there will be more locations added.
There is now a new icon on your home screen: "tutorial APPLICATIONINSIGHTS" (I have no clue why the instance name is in lowercase and the service name is in ALL CAPS). Click this new icon and you will finally find your Application Insights.
You are now on the usage statistics dashboard, which will be the starting point for all analysis. The dashboard is fully configurable and is populated with some default widgets. These, too, are aligned in tiles. The most prominent default tile is the Timeline. You can watch the trend in numbers of metric items of the past week and you will see new items coming in live. All views in Application Insights are viewing live data, which is especially useful for websites I'd imagine. If you are interested in statistics of a longer time range, let's say half a year, you can easily configure that via the "Time Range" tool button. I will describe more features after we got some data into our dashboard.
The last step in the Azure Portal before some coding is to copy the Instrumentation Key, which is our unique identifier that we need to provide to AppInsight's Telemetry API that is used to collect and send telemetry data into our Azure AppInsights dashboard.

Collecting data from a desktop app

For our testing purposes, we will create a simple WPF application with three buttons.

We will track three different telemetry items:

• Click of Button 1, including the total number of clicks on this button in the running session.
• Click of Button 2, including the exact timestamp of the click.
• A crash.

All items share some context information that is initialized in app startup. I chose to set the User ID to a fixed user called "tutorial1" and add a custom property named "app_start" that includes the time when the app was started.
To start collecting data, we need to utilize AppInsight's telemetry API. We can install the required assemblies via NuGet by right-clicking our project in the Solution Explorer, then selecting "Manage NuGet Packages" and install the package named Microsoft.ApplicationInsights (Application Insights Core API).

The class Microsoft.ApplicationInsights.TelemetryClient is the core class that we need to collect data. First, we initialize the Instrumentation Key and the context in MainWindow's ctor:

private TelemetryClient tc = new TelemetryClient();

public MainWindow()
{
    tc.InstrumentationKey = "aea76edd-a119-4ce3-bba0-2a31ec66880d";
    tc.Context.User.Id = "tutorial1";
    tc.Context.Properties["app_start"] = DateTime.Now.ToString(CultureInfo.InvariantCulture.DateTimeFormat);

    AppDomain.CurrentDomain.UnhandledException += CurrentDomain_UnhandledException;

    InitializeComponent();
}

Then, we will add three event handlers for the aforementioned events that we would like to track:

private int button1Counter = 0;

private void button1_Click(object sender, RoutedEventArgs e)
{
    var ev = new EventTelemetry("button1");
    ev.Properties["click_counter"] = (++button1Counter).ToString();
    tc.TrackEvent(ev);
    tc.Flush();
}

private void button2_Click(object sender, RoutedEventArgs e)
{
    var ev = new EventTelemetry("button2");
    ev.Properties["click_time"] = DateTime.Now.ToString(CultureInfo.InvariantCulture.DateTimeFormat);
    tc.TrackEvent(ev);
    tc.Flush();
}

private void buttonCrash_Click(object sender, RoutedEventArgs e)
{
    object foo = null;
    string crash = foo.ToString();
}

private void CurrentDomain_UnhandledException(object sender, UnhandledExceptionEventArgs e)
{
    if (e.ExceptionObject is Exception) {
        tc.TrackException(new ExceptionTelemetry((Exception) e.ExceptionObject));
        tc.Flush();
    }
}

That's all!
Now we can start this nice little demo app and mash the buttons a few times. Remember that the app will actually crash when you click on Crash!.
When you are done playing with your app, we can head back to the Azure Portal and look at the AppInsights dashboard. As I said earlier, the data is updated live, so the newly created items should be visible immediately. If they are not, just hit "Refresh".

Voila! There it is: One user, and four crashes - I apparently hit on "Crash!" four times. We can inspect the crashes to see more information.

You can see interesting things like how many times the crash occured, how many users where affected. If I initialized the context of the TelemetryClient properly, we could see the affected program versions, devices names and operating systems that the crash happened on. I'm sure that you can imagine that all these properties will be very interesting when trying to fix crashes in your app.

As with any telemetry items, you can even attach custom properties to the crash log, so you can include information that might be interesting in your specific app, such as the title of the active window when the crash happened or even the free disk space or things like that.

You could see these custom properties together with a few other properties that are gathered by default on the "Exception Properties" page.


If you are not using an online crash logging facility already, this will really take your bug fixing to a new level!

There are similarly useful stats for your custom events that you logged when clicking the two buttons.

TL;DR

See the feature list and the requirements at the top.
Then, execute these steps:

• Create an Azure account, if you do not already have one
• Add [Developer Services > Application Insights] in your Azure Portal
• Copy the Instrumentation Key
• Create a new WPF app
• Add the package "Microsoft.ApplicationInsights" Core API via NuGet
• Create a Microsoft.ApplicationInsights.TelemetryClient and call TrackEvent, TrackPageView, TrackException, TrackMetric, TrackRequest or TrackTrace.
• Watch the data appear in the AppInsights dashboard

Code

You can find the full example code on GitHub.

Hacky and Clean Programming

When I do programming, I do it in either of two "modes". Each of these modes serves a different purpose and I use them at different stages to achieve a goal. It is very important to be aware of the current stage you are in, because programming in the wrong mode can be most harmful for either productivity or code quality.

I call these two modes the "hacker mode" and the "clean mode".

Hacker mode

In "hacker mode", I try out either new technologies or architectural ideas. For example, when your current goal is to write a library to control a Bluetooth  device, I would first go into "hacker mode" and try things out and figure out what would be the most efficient and most stable way to use the raw Bluetooth API.

When hacking, I do not care for code quality. I may violate my own guidelines, use ugly casts, name variables "x", "foo" or "data". The uglier, the better. Because I will definitely throw that code away. This is a very important aspect that should not be violated. You have to be aware that you will throw it away, and you have to actually do this in the end. If what you hacked somehow does not work out, throw it away and start with a new hacking session - and throw this one away, too, once you learned the important aspects.

And if you are afraid that, when re-writing what you have hacked before, the Second System Effect (as described by Fred Brooks in The Mythical Man Month) might kick in, I can assure you that with this method I have not yet ever experienced this. I think the Second System Effect applies to larger scales only, and only when putting effort into producing high quality in the first system, too.

After I hacked away and figured out which calls must be made in which order and know the parameters for best results and found a good structure for the API and the implementation, I sit back, have a good look at it and memorize the important parts. Then I stash the code aside for later reference and mentally mark it as "To Be Deleted".

Now I can switch to "clean mode".

Clean mode

I am programming in "clean mode" when I have a good mental model of what I want to create. When I know the important key parts of implementation and have an idea how the API and the architecture should look like. Sometimes this information comes from a hacking session. Sometimes it is just there because I have been thinking about the problem for days, months or even years and now finally decided that everything is clear and can be put into code.

Most of the time, when programming in clean mode, I am doing DDD - Documentation Driven Development. Don't worry, this is not the new hip paradigm that you missed. It's essentially TDD, but I am writing the documentation of the code even before writing the tests.

Most important: The Docs

One major argument why TDD is cool is because you get "a feeling how your code works out when it is put into actual use". The same argument goes for writing docs. When writing docs, I always try to state the important details, not the obvious. When thinking about the non-obvious, you will learn whether the overall design is slick, or does have a few rough edges. With docs and tests combined, you can be pretty sure that the design is sound and that it works out well in practice.

There are a few, easy rules to follow when writing docs. This is especially important when writing them before the actual implementation.

First, it must be clear what the core function of the element you are documenting is. If there is not one core function, but multiple tasks  that are accomplished, you are most likely doing it wrong. Describe the core function of the element in one sentence, i.e. in a @brief.

Second, state the preconditions that must be met to use the element. The less preconditions you can name, the better. If there are no preconditions that are not enforced by the type system, you are doing it right. If the type system is not strong enough to express the constraints of the input parameters, document them in detail. The rumor has it that Haskell has an awesome type system, but unfortunately I have had not yet a chance to use it for productive work.

Third, and maybe most important for maintenance, state the side effects that may happen and which conditions they may likely happen under. If you are a really good programmer, you are writing functional code and can skip this part. You simply do not have side-effects then.

Additionally to these, the standard rules obviously apply: Describing each parameter in detail, possible exceptions thrown, how the return value has to be interpreted, etc.

While I do this, I always have two aspects in mind:
1. What actual use does the element have for a potential user and which goals would he target?
2. How will I possibly implement this element?

And it is very important not to get distracted by the implementation and create a bad API that does not resemble the tasks that a user of the class want it to accomplish, but instead just wraps the underlying technology. But it is also important to not create APIs that can not possibly be implemented in any reasonable way, or the performance will suffer considerably. You should avoid leaky abstractions for (nearly) all costs, but there is often a limit to this. (This is often worth prototyping in hacky mode.)

When I am done writing the docs, I begin writing the tests and see how my idea of how the API might be put to use actually performs. I use the docs that I have written and the side-effects and corner-cases that I have described to derive test cases and therefore get a pretty decent coverage.

I often draw some rough pseudo-UML to visualize the dependencies and relationships.

When actually implementing the functionality, I apply all the lessons that you have learned from Clean Code. I am aware of the docs and update them, when necessary. This may also lead to redesign the API and therefore the tests. I am consciously taking the risk that implementation details that do not fit into the API are costly, because I have experienced it many times that this approach is worth it, since it results in well architectured, maintainable, clean and most importantly easy to use code.

Final notes

As stated in the beginning, it is most important to distinguish these two modes of programming and apply the correct one in each situation. Also, I would advice against using a mixture of both. Do not write hacky code in a clean code base and do not write clean code while hacking. It is just not worth it, because you either harm your code bases quality or are less productive than you could.

Only do hacking in fresh, isolated code bases that are drilled down to the minimal. This of course requires you to isolate parts and think of good, small components to build your software in, which is valuable in itself.

The Software Industry is standing in it's own way

The Software Industry is driven by Programming. Without programming, there would not be software, obviously.
The easier and faster programming will get, the better will the software industry deliver innovations, maintain their cash cows, gain customers, make revenue.
But then why is programming so hard? Why does it cost so much and why is it so often done so badly?

Learning a Programming Language is hard

Ever tried to explain to some non-programmer that has never seen or written source-code before how an application or website is built?

They have no clue, not even the slightest, what "programming" really is. In contrast to other complex fields such as architecture, brain-surgery, chemistry or law, the majority of people does not know how programming in principal works.

But they could be excellent programmers, perhaps. They are maybe just not into programming because they are not attracted to fiddling with source files, wading through compiler errors, gathering information from sources spread across the internet and writing expressions that are meaningless to them. (Ever thought about why it is called a "class", anyone?)

And then, there are so many!

Not only non-programmers need to learn a programming language. Especially when seeking a new job after programming for like 10 years for the same company, you will notice that the industry is split afar. Are you a C++ guru? Good luck finding a job if you do not have any embedded companies nearby. Are you a PHP veteran? You will be out of luck if you do not have any web companies in your reach. Wikipedia lists 122 programming languages.

Even if only counting the ones widely in use, you come up with quite a number: Java, C#, C++, C, Objective C, Visual Basic, PHP, Perl, Ruby, Python, JavaScript, COBOL (ugh!), FORTRAN (ugh, too), Object Pascal/Delphi.

And then there are the newcomers and niche-languages, maybe in use by your favorite start-up you would like to apply at: D, TypeScript, CoffeeScript, Clojure, Scala, F#, Go, Rust, Dart, Haskell, Lisp, Lua, Swift, Tcl, Erlang.

Not enough? Then here is a small excerpt from popular domain specific languages: SQL and PL/SQL (in different flavors from different DBMSes), CSS, XUL (for Mozilla Firefox), Regular Expressions, UNIX Shell Script, PowerShell, Matlab, XSLT, UML.

And knowing one of them is not enough

Making it even worse, you often have to use many of them to build a software, especially when doing web development. You need a backend language like Ruby (with the domain-specific framework "on Rails"), a domain specific language inside the UI template. Then you need to write the HTML skeleton and the CSS styles. Most often, you need to write some raw SQL, too. This sums up to SIX languages in parallel use. Have you ever heard bout context switches being harmful for work productivity?

At the company I am currently working for, we are looking for C++ programmers. We create software in the business domain. That doesn't suit too well - most applicants have a very, very technical background with either Matlab or embedded engineering as their main focus. UI and usability is often not important in these fields. Office software meets quite different requirements than mathematical or electrical stuff, that's why low-level programmers are usually not suited for the work we are doing.

But we can not easily hire a, say, web UI and usability expert with HTML, JavaScript and Ruby background. Because learning C++ is very hard, and if you do not already know it, the chance of writing buggy code is very high. So the only way to hire a programmer is either find a good C++ programmer that is not a number cruncher, or we hire a programmer without C++ background and train them before they take on actual work, which is very costly.

And even with the same Language, Things can be different

And even if you are an awesome programmer in, let's say Ruby, this does not get you far. What if the company you want to work for uses a framework that you have never used before and is totally different? Even when you create the same stuff with it. Try to learn Ruby on Rails? That's nearly as much as learning a new programming language. Try to learn Qt when you already know MFC or vice versa? Even harder, since you will fall back to your old habit and create shabby stuff that will not fit the new environment.

How silly this is

Why do we need so many languages, most of them only justified by irrational reasons? Why can't we have only a few programming languages that differ in their fundamental properties and are used in all domains that require these properties? One object-oriented language, one functional language, one declarative language, one data-definition language. Or maybe even only one programming language in different flavors or in different "modes".

Each language's quality would rise, their community would be bigger, making it easier to find help online. You could actually use the language that you learned at your university in your job. The evolution of the language would be quicker, since there will be more parties interested in it. Sure, this will bring up other problems, such as concurrent ideas and visions for the language. But these can be addressed. Or circumvented, if a single organization is responsible for the language. This has worked in the past, for example with UML, Java, C#, OpenGL.

The software industry is strange. No other industry would allow so many different approaches to the same problems at hand, because it does imply a huge financial risk for each company in the industry. The software industry might be just too wealthy or too ignorant to see and address these issues with programming. I think the main cause for the current status quo is because it is so easy to build a new language or a new framework. And the inner drive of many programmers to create "their own baby" instead of making someone else's product better and use it for your own purposes. That's in some way related with the complexity and diversity of current programming languages. Often forks, clones or similar projects are started because the initiator is used to a different programming language. Why would anyone port SQLite to CSharp, if you can access SQLite's C API from within C#?

Export layers from svg files to png using xslt and inkscape

If you have svg files and you want to export all but one layer, or only some specific layers to png files using the command line (e.g. in an automated batch job or script), you can not do this with Inkscape out of the box. There is no parameter to export only one layer or to export all but one layer or anything similar. Because svg files are actually xml files, you can use xslt to strip out the layers you do not want to export.

Prerequisites

• You need inkscape and an xslt transformation tool installed.
• For Windows you can use msxsl
• For Linux you can use xsltproc.
• Of course, you need an svg file with multiple layers created with inkscape. (Inkscape uses the <g> tag to create layers and the layer name that you can see and modify in Inkscape is specified in the "inkscape:label" attribute).

Exporting all but one layer

To export all but a certain layer, you can use this xslt template. You just have to change the "inkscape:label" from 'Layer 2' to whatever layer name you want.

<?xml version="1.0" encoding="UTF-8"?>

<xsl:stylesheet
    version="1.0"
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:svg="http://www.w3.org/2000/svg"
    xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
    >
    <xsl:template match="@*|node()">
        <xsl:copy>
            <xsl:apply-templates select="@*|node()"/>
        </xsl:copy>
    </xsl:template>

    <xsl:template match="svg:g[@inkscape:label='Layer 2']"/>
</xsl:stylesheet>

Just copy this text into a text-file and save it (preferable with the file extension ".xsl" or ".xslt").
Then, from the command-line, do the following:

msxsl Example.svg YourXsltFile.xslt -o YourNewExample.svg
C:\Program Files (x86)\Inkscape.com YourNewExample.svg --export-png=YourNewExample.png

(Use "xsltproc -o YourNewExample.svg YourXsltFile.xslt Example.svg" instead of msxsl for Linux).

Exporting certain layers

When you want to export just a number of layers, it's better to use this template for the xslt file:

<?xml version="1.0" encoding="UTF-8"?>

<xsl:stylesheet
    version="1.0"
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:svg="http://www.w3.org/2000/svg"
    xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
    >
    <xsl:template match="@*|node()">
        <xsl:copy>
            <xsl:apply-templates select="@*|node()"/>
        </xsl:copy>
    </xsl:template>

    <xsl:template match="svg:g"/>

    <xsl:template match="svg:g[@inkscape:label='Background']|svg:g[@inkscape:label='Layer 2']">
        <xsl:copy>
            <xsl:apply-templates select="@*|node()"/>
        </xsl:copy>
    </xsl:template>
</xsl:stylesheet>

Better, type-safe dependency properties in C#, WPF

WPF is a great toolkit for graphical user interface programming where you can truly (and easily) separate program logic from user interface.
The dynamic and flexible binding mechanism is powerful, yet easy to use (once you grasp it :D). Because of it's dynamic nature, type safety is often an issue. Even the most fundamental constructs, like declaring a property that you can use as a binding target (called DependencyProperty) requires you to use casts. Here as a simple example that declares a DependencyProperty called Number of type int:

using System.Windows;

class ProgramLogic : DependencyObject {

    public static readonly DependencyProperty NumberProperty = DependencyProperty.Register("Number", typeof(int), typeof(ProgramLogic));

    public int Number {
        get { return (int) GetValue(NumberProperty); }
        set { SetValue(NumberProperty, value); }
    }
}

As you can see, there are some constructs that you would usually avoid, such as using typeof and - the single worst construct in every programming language - a cast to int in the property's getter.
While describing this to a friend lately, we said to ourselfs: "Why did they choose this construct? C# does have Generics, so why didn't they use it? Even if it would be just a helper function or class, it'd be much better than that.". So we came up with a wrapper to DependencyProperty, which is a bit shorter, and, most importantly, does not require a cast.

class DepProp <PropertyType, OwnerType> where OwnerType : DependencyObject {

    public DepProp(string name) {
        property = DependencyProperty.Register(name, typeof(PropertyType), typeof(OwnerType));
    }

    private DependencyProperty property;

    public DependencyProperty Property {
        get { return property; }
    }

    public PropertyType Get(OwnerType owner)
    {
        return (PropertyType) owner.GetValue(property);
    }

    public void Set(OwnerType owner, PropertyType value)
    {
        owner.SetValue(property, value);
    }
}

The class DepProp (pick a better name when you decide to use it, please) uses two generic parameters. The first one is the type of the property, the second one is the owner's type, which must be derived from DependencyObject. IMHO, using generic parameters is much better than using typeof. These generic parameters are used to guarantee that later calls to Get() and Set() are called with - and return - the correct types. This way, we made the DepdencyObject.GetValue() call type-safe. Sure, the implementation still uses a cast, but what I find most important is that there are no casts spread throughout the whole project. A neat side-effect is that using this class requires a tiny little less typing than the original DependencyProperty. Another nice feature is that you don't need to call a static member function to register your dependency property. Instead, you use new, just like you would do with any other object. Here is the implementation of ProgramLogic using the new DepProp:

class ProgramLogic : DependencyObject {

    public static readonly DepProp<int, ProgramLogic> NumberProperty = new DepProp <int, ProgramLogic>("Number");

    public int Number {
        get { return NumberProperty.Get(this); }
        set { NumberProperty.Set(this, value); }
    }
}

As we can see, the required code is a little less. But the real nice thing is that the compiler can help you pointing out refactoring errors. Let's imagine that you would want to change your NumberProperty to be of type string instead of int. When you change the generic parameter of your NumberProperty declaration and initialization, the compiler would spill out an error in the "normal" property's getter and setter, because the property is still of type int.
I hope that you find this (really) small helper class useful and that it inspires you to write more code like this that makes your overall codebase more maintainable and readable.

GridLayout for WPF: Escape the Margin hell

Working with WPF, you surely have come across the System.Windows.Controls.Grid class. It is a derivation of System.Windows.Controls.Panel, which in turn is a base class for layouters. You can use a Grid to create windows that have their child elements arranged in a uniform manner.

When you have worked with the Grid class, you probably know about this issue: Adding elements to the Grid will make them be strung together without any spacing between them. When you want to add spacing, you have to set each element's Margin property accordingly. This wouldn't be half as bad - it's just that, depending on where in the Grid your element is, you have to set the left, top, right and bottom margins differently. This can become quite a tedious task and makes your XAML look far more complicated than it needed to be. And that's not all - imagine you putting together a prototype of a very complex UI. Just think about one of those equalizer/sound processor programs that have dozens of controls arranged in a grid. You finally finished your prototype - you think it looks awesome - and show it to your boss. His face turns to a disgusted visage and he says "Why is it all so clung together? You can barely tell the buttons apart since they are too near to each other. Can't you add more space between them?". With the standard Grid class, you would gasp, look a bit depressed and tell your boss to come again in an hour or two. And when he comes around and wants to look at your updated prototype, you are still not finished changing all the margins correctly.

Forget that scenario. Use the GridLayout class from the download below and change all margins at once. It automatically sets a uniform margin to all child elements of this specialized Grid class. And even better - it is smart enough to set the Margin.Left of elements in the first column to 0. The same goes with the Margin.Right in the rightmost column, Margin.Top in the first row and Margin.Bottom in the last row. With this class, you simply change the newly introduced ChildMargin property and be done - you will see the effect of the changes immediately, live in the WPF designer and at runtime.

Here is a screenshot of a simple form done with the default System.Windows.Controls.Grid class - without setting any special margins. You can see how narrow the space between the elements is and that it does not look very appealing.

And here is the same form done with the GridLayout. Note that only the class of the Grid has been changed - the child elements are exactly the same.

The best of all is that this has been done in very few lines of code. It just took two steps: The first was to introduce a new property in a class that derives from System.Windows.Controls.Grid that would define the margin that the cild elements of the new Grid would use. The second set was overriding

protected void MeasureOverride(Size)

that has been introduced in FrameworkElement. The overwritten version of MeasureOverride enumerates all children and changes their Margin accordingly. After that, the base version of MeasureOverride is called. This makes sure that, before each arrangement, the margins are updated correctly.

Here is the complete source-code of the GridLayout:

using System.Windows;
using System.Windows.Controls;

namespace GridLayoutTest
{
    // The GridLayout is a special Panel that can be used exactly like the Grid Panel, except that it
    // defines a new property ChildMargin. ChildMargin's left, top, right and bottom margins will be applied
    // to all children in a way that the children will have a vertical space of ChildMargin.Top+ChildMargin.Bottom
    // and a horizontal space of ChildMargin.Left+ChildMargin.Right between them.
    // However, there is no margin for the borders of the internal widget, so that the GridLayout itself can be
    // aligned to another element without a margin.
    // It's best to have a look at TestWindow, which effectively tests all possible alignments of children.

    public class GridLayout : Grid
    {
        public static readonly DependencyProperty ChildMarginProperty = DependencyProperty.Register(
            "ChildMargin",
            typeof(Thickness),
            typeof(GridLayout),
            new FrameworkPropertyMetadata(new Thickness (5))
            {
                AffectsArrange = true,
                AffectsMeasure = true
            });
        // The child margin defines a margin that will be automatically applied to all children of this Grid.
        // However, the children at the edges will have the respective margins remove. E.g. the leftmost children will have
        // a Margin.Left of 0 and the children in the first row will have a Margin.Top of 0.
        // The margins that are not set to 0 are set to half the ChildMargin's value, since it's neighbour will also apply it,
        // effectively doubling it.

        public Thickness ChildMargin
        {
            get { return (Thickness)GetValue(ChildMarginProperty); }
            set 
            {
                SetValue(ChildMarginProperty, value);
                UpdateChildMargins();
            }
        }

        // UpdateChildMargin first finds out what's the rightmost column and bottom row and then applies
        // the correct margins to all children.

        public void UpdateChildMargins()
        {
            int maxColumn = 0;
            int maxRow = 0;
            foreach (UIElement element in InternalChildren)
            {
                int row = GetRow(element);
                int column = GetColumn(element);
                if (row > maxRow)
                    maxRow = row;
                if (column > maxColumn)
                    maxColumn = column;
            }
            foreach (UIElement element in InternalChildren)
            {
                FrameworkElement fe = element as FrameworkElement;
                if (null != fe)
                {
                    int row = GetRow(fe);
                    int column = GetColumn(fe);
                    double factorLeft   = 0.5;
                    double factorTop    = 0.5;
                    double factorRight  = 0.5;
                    double factorBottom = 0.5;
                    // Top row - no top margin
                    if (row == 0)
                        factorTop = 0;
                    // Bottom row - no bottom margin
                    if (row == maxRow)
                        factorBottom = 0;
                    // Leftmost column = no left margin
                    if (column == 0)
                        factorLeft = 0;
                    // Rightmost column - no right margin
                    if (column == maxColumn)
                        factorRight = 0;
                    fe.Margin = new Thickness (ChildMargin.Left   * factorLeft,
                                               ChildMargin.Top    * factorTop,
                                               ChildMargin.Right  * factorRight,
                                               ChildMargin.Bottom * factorBottom);
                }
            }
        }

        // We change all children's margins in MeasureOverride, since this is called right before
        // the layouting takes place. I was first skeptical to do this here, because I thought changing
        // the margin will trigger a LayoutUpdate, which in turn would lead to an endless recursion,
        // but apparantly WPF takes care of this.

        protected override Size MeasureOverride(Size availableSize)
        {
            UpdateChildMargins();
            return base.MeasureOverride(availableSize);
        }


    }
}

You can download a complete project with an exhaustive test scenario here:

Edit: I forgot to take the ColumnSpan and RowSpan into account in the first version. This lead to margins being too large when an element with a Column- or RowSpan was spanning to the rightmost or bottommost row or column. This has been fixed in version 1.1. Download link has been updated.

Using .NET and WPF in Win32 legacy applications, Part 1: The basics

Introduction

There are applications that are just impossible to port to any new technology, because of sheer size. Unfortunately, most of these applications are very important to their creators, such as commercial applications that have been developed for decades. Those applications often matured over the time and are satisfying a broad range of users. Rewriting these in a new programming language or a new framework, while being economical, would be impossible.

That's why interoperation and downwards-compatibility is something every new platform should provide. .NET, with it's new Windows Presentation Foundation (WPF) is one of these platforms. You can use .NET in the (from Microsoft's point of view) "legacy" C++ programming language through C++/CLR. And you can use WPF controls and windows in the now deprecated WinForms classes using the "interop" class System.Windows.Interop.HwndSource. Fortunately, since WinForms is built on raw Win32 API under the hood, this HwndSource class is suitable to be used to integrate WPF with raw Win32 applications as well. And it's not that hard at all.

For the impatient among us, you can directly skip to the download and look at the source code. It's only a few dozen lines of code.

Getting started

To get started, we will create a new, empty C++/CLR project. We need C++/CLR, since, obviously, we need to access .NET from either C or C++ source code. I will assume that the "legacy" application you want to use WPF in is a C++ project, since C projects can easily be ported or integrated with C++ code.

Step 1: Creating a new C++/CLR project

In Microsoft Visual C++ 2010 Express, you do that by choosing File -> New -> Project from the menu. Then you select Visual C++ > CLR > CLR Empty Project as the template. I picked win32wpfinterop as the project name, but you can use any name you want. When you hit OK, you will have a new, empty project.

Step 2: Building the Win32 window skeleton

Since C++/CLR is a superset of the "normal" C++ that you write in Visual C++, you can use the Win32 API just as you please. The window example skeleton does not differ from normal C++ at all. Add a new C++ File to the Source Files folder (filter) and add your Win32 window code. Here's how my code looks:

#include <Windows.h>

// Constants
namespace {
   TCHAR * windowClassName = TEXT("win32host");
   TCHAR * windowTitle     = TEXT("Win32 Host (Win32 WPF Interop)");
   int          windowWidth     = 200;
   int          windowHeight    = 100;
}

// Window message procedure
LRESULT CALLBACK WindowProc(
  HWND hwnd,
  UINT uMsg,
  WPARAM wParam,
  LPARAM lParam)
{
   switch (uMsg) {
   case WM_DESTROY:
      ::PostQuitMessage (0);
      return 0;
      break;
   default:
      return ::DefWindowProc (hwnd, uMsg, wParam, lParam);
   }
}

// Main program entry  point
[System::STAThread] // This is IMPORTANT, but it's for in C++/CLR  only
int CALLBACK WinMain(
   HINSTANCE hInstance,
   HINSTANCE hPrevInstance,
   LPSTR lpCmdLine,
   int nCmdShow)
{
   // Register our Window class
   ::WNDCLASS wndclass;
   wndclass.style = CS_VREDRAW | CS_HREDRAW;
   wndclass.lpfnWndProc = &WindowProc;
   wndclass.cbClsExtra = 0;
   wndclass.cbWndExtra = 0;
   wndclass.hInstance = hInstance;
   wndclass.hIcon = NULL;
   wndclass.hCursor = NULL;
   wndclass.hbrBackground = reinterpret_cast <HBRUSHgt; (COLOR_BTNFACE + 1);
   wndclass.lpszMenuName = NULL;
   wndclass.lpszClassName = windowClassName;
   ::RegisterClass(&wndclass);

   // Create our main, raw win32 API window
   // We create the window invisible (meaning that we do not provide WS_VISIBLE as the window style parameter), because making it visible and then
   // adding a HwndSource will make it flicker.
   HWND mainWindow = ::CreateWindow(
      windowClassName,
      windowTitle,
      0,
      CW_USEDEFAULT,
      CW_USEDEFAULT,
      windowWidth,
      windowHeight,
      NULL,
      NULL,
      hInstance,
      0);

   // Now that setting up the HwndSource is finished, we can finally make our window visible
   ::ShowWindow (mainWindow, SW_SHOW);

   // Start message processing
   ::MSG message;
   while (::GetMessageA(&message, 0, 0, 0)) {
      switch (message.message) {
      case WM_QUIT:
         break;
      default:
         ::TranslateMessage(& message);
         ::DispatchMessage(& message);
         break;
      }
   }
   return 0;
}

Download here

Yeah I know, it's a bit length ;-) but that's just how Win32 code is. The good news is that adding WPF components is much less code than this skeleton. Here is how your window should look like:

You need to add the User32.lib to your references, since the functions we used are defined in the Windows' User32 library. You need to right-click on your project in the Solution Explorer and choose Properties. Then navigate to Configuration Properties > Linker > Input and add User32.lib as an Additional Dependency.

Step 3: Create a HwndSource

Before we will be going to use WPF classes, we need to add the required WPF Assemblies to our project references. Right-click your project in the Solution Explorer again, but this time choose References. Now press Add New Reference and get a cup of coffee, while Visual Studio loads every registered .NET assembly. (This has become much faster in Visual Studio 2010, but it is still unbearably slow.) We will need the following assemblies to our project: System (for String), WindowBase and PresentationCore (for HwndSource) and PresentationFramework (for Label).

As the simplest example, we will be adding Label (type System.Windows.Controls.Label) to the window in this tutorial. But we can not just add a Label object to the Window -- the Label class has no members that would take a HWND as the parent class or anything like that. Instead, we need to create an intermediate object that builds the very bridge between Win32's HWND and WPF's System.Windows.UIElement. That intermediate object is of the aforementioned type System.Windows.Interop.HwndSource. Creating a HwndSource-object is very similar to creating a new win32 control - The HwndSource constructor basically takes the same parameters as WinAPI's RegisterClass () and CreateWindow() do. We create a HwndSource using this call:

System::Windows::Interop::HwndSource ^ hwndSource = gcnew System::Windows::Interop::HwndSource (
      CS_VREDRAW | CS_HREDRAW, // window class styles
      WS_CHILD,                // window flags
      0,                       // extended windows styles
      0,                       // x position (will be overridden later)
      0,                       // y position (will be overridden later)
      "WPF Interop",           // window title (not visible)
      static_cast <System::IntPtr> (mainWindow)); // parent window

HwndSource is, at the same time, a pure HWND-style window and a WPF UIElement. This means it can be hosted by another HWND (because we passed the WS_CHILD flag), but can host a WPF UIElement itself. And since being able to host one element in WPF means that you can host any number of elements (e.g. by using a Grid), you have the ultimate freedom to embed complex controls written in .NET and WPF in your Win32 application.

Step 4: Finally, add the Label

It's a bit tricky to get hold of the HWND window handle of HwndSource, because of .NET and C++ type differences. The HWND is available as a System.IntPtr. You need to call ToInt32 and reinterpret_cast it to a HWND like so:

HWND hwndSourceHandle = reinterpret_cast <HWND> (hwndSource->Handle.ToInt32 ());

Now we can call any Win32 API functions on that HWND, such as SetWindowPos:

::SetWindowPos (
      hwndSourceHandle,
      NULL, // ignored
      10,   // x position
      10,   // y position
      180,  // width
      80,   // height
      SWP_NOZORDER | SWP_SHOWWINDOW);

The HwndSource now exists, but that alone is not much of a gain. It's not even visible. You need to create some visible WPF control and add that to the HwndSource. Adding to the HwndSource means setting the control as the HwndSource's RootVisual. Here's how you can do this:

System::Windows::Controls::Label ^ label = gcnew System::Windows::Controls::Label ();
label->Content = gcnew System::String ("WPF Label -- it works!");
label->Background = System::Windows::Media::Brushes::White;

hwndSource->RootVisual = label;

When you insert this code between the call to ::CreateWindow() and ::ShowWindow(), you will experience your first moment of success and a window like this should be visible:

Controls that don't required keyboard focus work very good. Controls with keyboard focus work good, too, as long as there are no other controls in the host window that may steal the focus from WPF. The next part will be about making keyboard handling and focusing work correctly, so stay tuned.
(Don't expect it before June or July 2011, though)

There's a complete example project for Visual C++ 2010 (build with VC++ 2010 Express) with commented source code for download.

And besides: You can build a window's complete content in a C# class library e.g. as a UserControl, add that class library's assembly as a Reference in your C++/CLR's project and go ahead and use it in this interop framework we just built. This basically means that you can embed C# windows and controls in your legacy C++ application.