Thursday, March 29, 2012

.NET and Metro: The Windows Runtime and the CLR on Windows 8

Many developers tend to look at Windows 8 as a completely new platform and even question whether it heralded the imminent demise of managed code. After spending many months digging into the Windows Runtime (WinRT), Metro style or “tailored” applications, and exploring how they related to the .NET Framework, I’ve come to the conclusion that the two work very closely together and in fact are engineered to integrate. That means good news for managed developers. The .NET Framework 4.5 is very much “Metro-aware” while the Windows Runtime knows how to shake hands with the CLR. The purpose of this post is to elaborate on this a bit more than what I covered in my Portable Class Library series.


The first thing to note is that WinRT components, regardless of what language they were written in, share the same metadata format as .NET Framework assemblies. This is what allows you to navigate to the metadata folder at c:\windows\system32\WinMetadata and be able to use ildasm.exe to expose the definitions of WinRT components that are part of the Windows 8 operating system. The standard is documented as ECMA-335 and you can check this link to learn more.

As part of this metadata, types and assemblies can be tagged with a new Intermediate Language (IL) keyword called windowsruntime. This keyword tags the type as a WinRT component. The .NET Framework uses this to know when to marshal parameters because the WinRT type system is not the same as the one supported by the CLR. Fortunately, this is supported “under the covers” as you’ll see in the next section. When an assembly is tagged with the keyword, it instructs the .NET Framework to use a special APIs like the one called RoResolveNamespace to load references. This is a way that all supported WinRT languages can access underlying components.

Type Conversion

As I mentioned, the .NET Framework does some magic with type conversion. This happens in both directions (calls into and values received from WinRT components). This is not new – this has been supported for awhile and you can see a list of Default Marshaling for Value Types in the MSDN documentation. A System.Int32 becomes a ELEMENT_TYPE_I4 and vice versa. These are what are referred to as “fundamental types.”

In addition, however, the CLR performs implicit mapping to more complex types. If you’ve been doing any Windows 8 development, you are probably familiar with conversions that look like this:

Windows.Foundation.Collections.IVector<T> <= => System.Collections.Generic.IList<T>

You can read the list of WinRT collection types, then drill into the detail to see the corresponding .NET map.

Here is a list of commonly mapped types:

Windows Runtime .NET Framework
IIterable<T> IEnumerable<T>
IIterator<T> IEnumerator<T>
IVector<T> IList<T>
IVectorView<T> IReadOnlyList<T>
IMap<K, V> IDictionary<TKey, TValue>
IMapView<K, V> IReadOnlyDictionary<TKey, TValue>
IBindableIterable IEnumerable
IBindableVector IList
Windows.UI.Xaml.Data.INotifyPropertyChanged System.ComponentModel.INotifyPropertyChanged
Windows.UI.Xaml.Data.PropertyChangedEventHandler System.ComponentModel.PropertyChangedEventHandler
Windows.UI.Xaml.Data.PropertyChangedEventArgs System.ComponentModel.PropertyChangedEventArgs

There are other mapped types that you may not be as familiar with, such as the map from a Windows.Foundation.Uri to a System.Uri.While this is done “automatically” it does have side effects. The WinRT Uri does not support anything but absolute Uris, so any attempt to pass a relative Uri into a WinRT component will fail.

Any other types are projected automatically without conversion. A good example of this is the built-in XAML controls for building Metro applications. Windows.UI.Xaml.Controls.Button appears as a CLR class to your .NET code, but it also appears as a C++ class to developers using the C++ option. There is no map or conversion, the type remains the same but the projection provides all of the plumbing necessary for it to act and feel like a type native to the environment you are working in. Any necessary wrappers are created behind the scenes – you’ll learn more about that later.

Because special types can have side effects, it’s important to know what they are and what restrictions exist. Here is a short list:

  • Array – If you still use this construct for collections it’s important to note that WinRT does not support the class being passed by reference as in the CLR. Arrays can either be provided as input parameters to a WinRT component, where they can be referenced but not modified, or as output parameters, where what you pass in is really just regarded as a buffer and not inspected but populated by the component.
  • DateTimeOffset – in the Windows Runtime, this becomes a Windows.Foundation.DateTime value which does not contain time zone information. The CLR will convert your time to UTC before passing it to the WinRT component, and will convert any result from UTC to local time. To resolve this, you should be prepared to convert the value to local time before passing it to a WinRT component and back from local time to the target time zone when you receive values back.
  • String – this becomes a HSTRING which does not support null values. You should not pass a null string into a WinRT component, nor should you ever see a null value returned back. Instead, use String.Empty.
  • Uri – this is converted to Windows.Foundation.Uri which only accepts absolute Uris. Attempting to pass a relative Uri will result in an exception.

In addition, it’s important to note some WinRT types and how they impact the CLR. Understanding these types is more important if you plan to write WinRT components in C++ for consumption by the .NET Framework – otherwise most of this happens behind the scenes for you.

  • ELEMENT_TYPE_OBJECT – on the surface, this is mapped as System.Object in the .NET Framework. It is used to pass back other types from APIs. What’s important to note is how it is mapped on the .NET side. This type represents a pointer to the COM IInspectable interface. It is responsible for projecting WinRT components into all supported languages and all WinRT interface types must derive from it. One important method that it declares is GetRuntimeClassName. If this passes back a value, the CLR will create a strongly-typed Runtime Callable Wrapper (RCW) for the projection. Otherwise, it will create a weakly-typed wrapper that simply resolves to System.__ComObject regardless of the actual backing type.
  • IReference<T> – this is an interesting type because it handles two features in the Windows Runtime. First, it is a way of providing a nullable type. While it maps loosely to Nullable<T> the mechanism is slightly different. The pointer itself will be null if the value passed is null, otherwise it will point to an implementation that returns the actual value when the get_Value method is called. Conversely, a null pointer results in a Nullable<T> instance created with HasValue set to false. The type also facilitates boxing. Instead of returning a direct value, a WinRT component can return an ELEMENT_TYPE_OBJECT (System.Object to the CLR) and implement IInspectable to return IReference<Int32> as the type. When that happens, the CLR will call the method to obtain the value, then box it on the managed heap and pass the reference back into the managed stack.


In the CLR, managed events can have multiple delegates assigned and removed. Removing an event is as simply as using the operator to remove it and passing the delegate that handles the event callbacks. In WinRT, the event system is token-based. When you add a delegate to handle an event, you receive a unique token. To remove your delegate from the event, you call a method to remove and pass in the token, not the delegate.

Events are mapped between the CLR and WinRT by the compiler. If you decompile your code you will see this in action. The CLR uses the helper classes:



The compiler will emit code that maps the events through these classes. The classes will maintain the dictionary of tokens and delegates, so you can code your familiar remove operation and have it automatically pass the correct token behind the scenes.


For the most part, you don’t have to worry about any of the magic happening behind the scenes because it is done for you. However, the purpose of this was to show how much thought and engineering went into actually working with both .NET and WinRT to ensure the two could work closely together. This to me is evidence that .NET is not a second-rate citizen in Windows 8, but an important factor that was carefully considered as part of the overall strategy to create a flexible new platform with reach.

Thursday, March 22, 2012

Jounce MVVM WCF RIA Printing and More Example

I finally managed to update and upload my To-Do List Reference Application. This is a Silverlight 5 application based on my Jounce framework that demonstrates a number of different features. I built it as part of my book, Designing Silverlight Business Applications. There are several chapters devoted specifically to the construction of this example application. It is a demonstration application, so while it contains a lot of different components designed to illustrate various points, it's not intended to be a "production application." I won't even call it an "enterprise application" because it falls far short of what you might typically build for the enterprise, but this one has a lot more code than your typical two-page blog post program.

Specifically, it demonstrates the following concepts:

  • The Jounce framework (of course)
  • The MVVM pattern
  • Using a shared view model to display non-shared data (this is a common misconception, that if you edit five records you need five instances of the same view model)
  • Jounce-specific navigation and parameter-passing
  • Use of the Visual State Manager (VSM)
  • Design-time support
  • The Managed Extensibility Framework
  • Theme management (i.e. storing a theme in a separate project and referencing it)
  • WCF RIA Services
  • Mapping (auto-mapping properties from one entity to another)
  • Event aggregator messaging
  • Repository pattern
  • The Sterling NoSQL database (the example uses both a server-side and client-side instance)
  • Synchronization between the client and server when the client is offline
  • p/Invoke
  • Concurrency management
  • Offline Out-of-Browser (OOB) including UI for installation and removal
  • Use of behaviors
  • Extensions for fluent interfaces
  • Region management
  • Validation
  • Printing
  • Localization (version "as is" has Spanish text substituted in the edit dialog)
  • COM Interop (exports items to Excel)
  • HTML DOM interaction (application works with JavaScript to warn the user if they edit a record and try to navigate in the browser) and updates the title whether in browser or OOB mode)
  • Tracking dirty records using the entity view model
  • Filtering and sorting
  • Touch interaction using the LightTouch library
  • Out-of-Browser child windows
  • Toast notifications
  • Testing

I'm sure there are some items I left out. I hope this helps answer a lot of questions I receive and I also hope it is taken as guidance and an example, not a "final architecture" or production-ready module as again, the key intent is to provide examples of a lot of different features. There is only one thing I ask: that if you have questions about the application, you first invest in the book and ask me only if you don't find your answers there. Jounce is an open source community project and I'm sharing this example application as well, but the book is how I spent the better part of a year compiling all of the information I know about enterprise Silverlight development into one comprehensive resource. It's not a rehash of blog posts and contains a lot of content. However, if you've got the book, have worked through the examples and still have some questions or issues, please don't hesitate to contact me through the Jounce discussion forums or by replying in the comments section below.

Simply head over to the Jounce website and click the download icon when browsing the latest source to grab the application. Thanks, and enjoy!

Jeremy Likness

Wednesday, March 14, 2012

Understanding the Portable Library by Chasing ICommand (3 of 3)

Part 1: Creating the Portable Library
Part 2: Portability in Silverlight and WPF: a Tale of Type Forwarders
Part 3: Portability in Metro: A CLR and WinRT Love Affair (this post)

Portability in Metro: A CLR and WinRT Love Affair

In this series we’ve covered the portable library and reviewed how it allows you to create assemblies that can be shared without recompilation across multiple platforms. You created a portable assembly with a view model and a command in it, then successfully integrated it in a WPF and a Silverlight project. Now it’s time to code for the future and go Metro.

Create a new C# Metro application using the blank page template. Reference the PortableCommandLibrary project. Open the BlankPage.xaml file and drop in the same XAML you used for WPF and Silverlight. First, fix up a reference:


Next, add the XAML inside of the main grid:

<Button Content="{Binding Text}" Command="{Binding ClickCommand}"

Now compile, deploy, and run the application. It will work just as it did for WPF and Silverlight.

First the button:


Then the disabled button:


What’s interesting for this example is that you know when you want to wire a command, you have to use a completely separate namespace from Silverlight. In fact, the namespace implies that you are accessing a WinRT component that is part of the operating system and not even a managed object. How do we pull that off with an assembly that isn’t modified?

To begin the journey, start with the assembly that is referenced directly by the portable library. This is System.Windows.dll only this time you’ll inspect it in the .NETCore folder, which is the smaller profile allowed for Metro applications. Once again, the assembly contains no implementation. Opening the manifest, you will find a series of type forwarders. This time the ICommand interface is redirected to System.ObjectModel.dll.


What’s next? You guessed it. Pop open the System.ObjectModel.dll assembly and you’ll find:


So there it is … but there’s a problem. When you specify your own command implementation, you have to reference the Windows.UI.Xaml.Input namespace. So how will this reference work? This is where Metro works a little bit of magic.

It turns out the platform maintains an internal table that maps CLR namespaces to the WinRT equivalents. This allows seamless integration between the types. For example, the CLR may be exposed to the type Windows.Foundation.Uri when dealing with a WinRT component. When this happens, it automatically maps this to the .NET System.Uri. When the CLR passes System.Uri to a WinRT component, it is converted to a Windows.Foundation.Uri reference.

In our case, the code references:


The platform will automatically map this to the WinRT counterpart,


This is a very powerful feature because it enables compatibility between legacy code and the new runtime with minimal effort on the part of the developer. If your type maps to an actual object that can have an activated instance, rather than just an interface, the CLR will automatically instantiate a Runtime Callable Wrapper (RCW) to proxy calls to the underlying WinRT (essentially COM) component.

The whole portable path looks like this in the end:


If you want to see the “projected” types you can use ildasm.exe with the /project switch and in theory, if you run this against one of the .WinMD files (such as Windows.UI.Xaml.Input.WinMD) located in %windir%\winmetdata you should see .NET projected types instead of Windows Runtime types … I have yet to get this to work but if you have, please post the details here.

And that’s it – you’ve learned how to create an assembly that is completely portable between .NET Framework 4.5 (WPF), Silverlight 4.0 and 5.0, and Windows 8 Metro, and learned a bit about how it works by chasing down ICommand under the covers. Hopefully this helps with understanding the library and also with planning out how to map future projects that need to share code between existing implementations and future Metro targets.

Friday, March 9, 2012

Understanding the Portable Library by Chasing ICommand (2 of 3)

Part 1: Creating the Portable Library
Part 2: Portability in Silverlight and WPF: a Tale of Type Forwarders (this post)
Part 3: Portability in Metro: A CLR and WinRT Love Affair

Portability in Silverlight and WPF: a Tale of Type Forwarders

In the last post, I walked through creating a portable assembly that will target Silverlight 4.0 and above, .NET Framework 4.5, and Windows 8 Metro. In the assembly were a few classes that handled commands and property change notification for a simple view model. In this post I’ll show you how to reference the assembly in Silverlight and WPF and explain why it works.

The first step is to create a new Silverlight 5.0 project (just using that because it’s the latest version, I know the library will technically support 4.0). Just make a simple application (no need to have a web project as well). The project will be created with the default App.xaml and MainPage.xaml. In the solution explorer, right-click on the References node and add a reference to the PortableCommandLibrary project. Now open up the XAML for the main page. At the top, add a namespace declaration for the view model:


Next, paste the following XAML inside the main grid called LayoutRoot (you’ll use the exact same snippet for all of the projects in this series).

<Button Content="{Binding Text}" Command="{Binding ClickCommand}"

Now compile and run the application. You should see something like this:


If you follow the instructions, you should end up with this:


I’d love to show you how this worked with the portable library, but the answer is pretty boring. As I showed you in the last post, the portable assembly points to an ICommand interface that lives in the System.Windows.Input namespace in the System.Windows.dll assembly. If you peek inside Silverlight’s assemblies and run ildasm.exe you’ll see:


The reference can be visualized like this:


Really no magic at all – Silverlight is a lowest common denominator here. So let’s try something a little more interesting. Create a new WPF project and reference the same portable library. Add the same namespace declaration to the MainWindow.xaml file and drop in the XAML inside the Grid tag. Run the application – look familiar?


Click it.


OK, so it works the same way, but we noted earlier that the ICommand interface lives someplace different. How does this work? If you recall, the reference to System.Windows.dll in the portable library was tagged as retargetable. This tells the runtime that the target may really exist somewhere else. In fact, if you look at the references available for the .NET Framework 4.5 (here’s a tip: forget that old %windir%\Microsoft.NET\Framework\ stuff … instead, try the newer %programdir%\Reference Assemblies\Microsoft\Framework\.NETFramework\ folder), you’ll find there is a System.Windows.dll file. Pop it open with ildasm.exe and you’ll see there is no implementation in the file, only metadata. Read the manifest and you’ll come across this little gem:


Ah-hah! The portable library people have been planning this for longer than most readers suspect. There’s a nice reference now that politely invites the CLR to look somewhere else for the implementation, specifically in System.dll. If you open that assembly, you’ll see the interface is indeed defined there. So, what really happened looks a little like this for the .NET Framework 4.5:


If you’re turning pale at the thought of so many hops, don’t get worried. These tables are loaded into memory and represent very miniscule lookups. The portable team assured me that any performance cost due to a little indirection is negligible.

What I love about the approach is that it uses a lot of pieces that have been already in place but in a clever way that gives us this powerful functionality of using the same assembly in Silverlight (web) or WPF (desktop). In the next post, we’ll take it even further and see how it relates to the brand new platform of the Windows Runtime (WinRT) for a Windows 8 Metro application. How on earth do we go from this to an unmanaged code base?

Thursday, March 8, 2012

Understanding the Portable Library by Chasing ICommand (1 of 3)

Part 1: Creating the Portable Library (this post)
Part 2: Portability in Silverlight and WPF: a Tale of Type Forwarders
Part 3: Portability in Metro: A CLR and WinRT Love Affair

The portable library tools have been available for several months now. The goal for this add-in to Visual Studio 2010 was to enable you to create special portable assemblies that can run on various platforms, ranging from XBox and Windows Phone 7 to various versions of the .NET Framework and Windows 8, without having to recompile them. That’s a pretty amazing feat and allows developers to avoid some crazy practices like linking source code.

With Visual Studio 11, the tools are no longer an add-in but are a built-in part of the product. You can directly create portable class libraries and build these magic assemblies that can be reused without recompiling. For many users, this is incredibly important because it means they can not only reuse their libraries between platforms like the phone and the desktop, but also can build insurance for the future. Think about it: you can build a Silverlight application today, share your libraries with a Metro application you are developing for tomorrow, and only have to branch the parts of the code that are necessary.

You may be surprised to learn just how much functionality can be shared. Property change notification, commands, even the network stacks can be shared across targets. The purpose of this post is to summarize some of the capabilities, show you how to build a project that shares portable libraries, and then get into the dirty details of how the magic really works. How can we possibly have an assembly that Silverlight recognizes today work without modification or recompilation in our Windows 8 Metro application of the future? Keep on reading if you want to uncover the answer.

For this example I’ll walk you through creating a view model that executes a command and changes some text. The view model will be reused without modification in a Silverlight, WPF, and Windows 8 Metro project, along with property change notification and the implementation of ICommand. What makes this interesting is the fact that ICommand lives in very different places on these platforms.

In Silverlight and WPF, ICommand lives in the System.Windows.Input namespace. While the namespace is the same, the assemblies are not. The definition exists in System.Windows.dll for Silverlight but in WPF and the .NET Framework 4.5 it is defined in System.dll. On Windows 8 Metro, the namespace for ICommand is Windows.Xaml.UI.Input. There, it doesn’t even live in an assembly but is defined through metadata and projected by the underlying OS. How does the portable library reconcile these differences?

If you want to follow along and have Visual Studio 11 Beta Ultimate (this won’t work with Express) simply create a new solution called PortableCommandLibrary and with a project of type Visual C# –> Windows –> Portable Class Library.


Now you can modify the target frameworks. As you may imagine, the platforms you wish to target will limit your options. For example, if you want to target the phone, you won’t be able to use the Managed Extensibility Framework (MEF). If you want to target the XBox, you won’t have the networking stack available. The combination of targets will limit the portable APIs available for you to use in your portable library. The beauty is that you don’t have to figure out what’s compatible as the team has figured this out for you and will automatically restrict your options based on what you select.

Right-click the project node and go into Properties (ALT+ENTER). Click on the Change button.


This will give you the option to select the profile you wish to use. For this example, we’ll build a library that targets .NET Framework 4.5 for WPF, Silverlight 4.0 and higher, and Metro.


Great! Now take a look at the Solution Explorer under References. What is that? “Portable Subset”?


Look at the properties for the reference and you’ll see a path. Navigate to the path. Wow, now this is interesting! There are the DLLs you can safely use between the targets. You can see a redistribution list and a set of supported frameworks as well.


The magic here is worked by a new Visual Studio 11 feature called Extension SDKs. This feature allows you to use a “reference” that is actually a package of files. It solves the problem of deploying custom controls with assets and also helps us write portable code. The portable team was kind enough to figure out all of the available permutations of framework combinations and package them as specific extensions to make a seamless reference experience in Visual Studio 11. You can read Microsoft’s documentation on how to create your own SDKs here.

OK so now we’ve learned a little bit about the magic that makes this work. The SDK reference constrains what we can do to code that is portable between the target runtimes. So what next? How about create a command that can perform a single action and then disables itself? You’ll need to add a using statement for System.Windows.Input:

public class ClickOnceCommand : ICommand 
    public ClickOnceCommand(Action action)
        _action = action;

    private Action _action; 
    private bool _canClick = true;

    public bool CanExecute(object parameter)
        return _canClick;

    public event EventHandler CanExecuteChanged;

    public void Execute(object parameter)
        _canClick = false;
        var handler = CanExecuteChanged;
        if (handler != null)
            handler(this, EventArgs.Empty);

Great! Next, let’s create a view model that exposes a text property. The property invites the user to click. The view model will expose a command and feed it the action to change the text (to admonish the user not to click). The view model looks like this:

public class ViewModel : INotifyPropertyChanged 
    public ViewModel()
        ClickCommand = new ClickOnceCommand(() => Text = "Don't Click Me");
        _text = "Click Me";

    private string _text;

    public string Text
        get { return _text; }
            _text = value;

    public ICommand ClickCommand { get; private set; }

    protected void RaisePropertyChanged(string propertyName)
        var handler = PropertyChanged;
        if (handler != null)
            handler(this, new PropertyChangedEventArgs(propertyName));

    public event PropertyChangedEventHandler PropertyChanged;

Here’s the interesting part: we’ve now created a functional view model and command that will work on multiple platforms from a single assembly without recompilation. If you’re concerned about your path from now to Windows 8, consider Silverlight 5 or WPF as an interim because the following XAML will work without a single modification across all of these targets (Silverlight, WPF, and Windows 8 Metro):

    <Button Content="{Binding Text}" Command="{Binding ClickCommand}"

Obviously it won’t always be that simple but there is a lot of opportunity for sharing code here. Don’t worry about using the XAML just yet – I’ll walk through that in the next post. You don’t have to be an expert to figure out what the goal is: we want to show a button that invites the user to click. When clicked, it will disable itself and tell the user not to click it. Simple, no?

You can build the portable library and inspect it with ildasm.exe. What I want you to notice is that the ICommand reference points to the System.Windows.dll assembly:


For Silverlight, this is fine … that’s exactly where it lives. In the .NET Framework 4.5, however, it lives in System.dll. Windows 8 Metro defines it in a different namespace: Windows.UI.Xaml.Input. So how can this single assembly work in those environments without being rebuilt?

I’ll explore the answer for WPF and the .NET Framework 4.5 in the next post. For now, take a look at the manifest that was generated for our portable assembly. Note the special tag on the external references.


More to come!

Tuesday, March 6, 2012

Windows 8 Icons: Segoe UI Symbol

Here's a quick and easy tip for developing Windows 8 applications from my book, Building Windows 8 Apps with C# and XAML. (Be sure to check out the updated Windows 8.1 book Programming the Windows Runtime by Example). Are you looking for decent icons to use in your Application Bar? Windows 8 makes it incredibly easy by using the built-in Segoe UI Symbol font. There are tons of icons embedded in the font that are perfect for using in your applications.

Take a look at the following XAML snippet from the Microsoft quick start for adding an app bar:

<StackPanel Orientation="Vertical" Margin="0,14,0,5" Grid.Column="1">
   <Button Style="{StaticResource AppBarButtonStyle}"
       FontFamily="Segoe UI Symbol" FontSize="18.667" 
       Padding="8,8,0,0" Margin="0,0,0,10"
   <TextBlock Text="Back" />

It defines the section of the application bar you see below:


The key is in the content tag that specifies the arcane text &#xE112; – this is simply a notation that references the location of the symbol in the font (you can see the “font family” is set to the appropriate font). So how do you go about finding these icons? Fairly simple: on the Windows 8 machine, press the Windows Start Button (that button that has the Windows logo on it) or open the start menu and type “Character Map.” This will give you access to launch the Character Map application. Switch the font to Segoe UI Symbol and scroll down to the bottom until you see something like this:


Now you can simply select the icon you wish to include. For this example I’ve selected the camera icon. Note the code at the bottom: U+E114. That is the code I need to know I can use &#xE114; in text for the Segoe UI Symbol font to make the camera icon appear.

How cool is that? You’ll find the font covers most of the icons you would need for your application. By using the icons from the font set, you also ensure consistency with other Metro applications. Users will be familiar with the fonts and it will make it easier for them to choose the right one for the task they intend to perform.

Check out more tips like this in Building Windows 8 Apps with C# and XAML. Learn how to develop Windows 8.1 apps in Programming the Windows Runtime by Example.