| Comments

At //build one of the surprising immediate things I heard about was folks wanting to build custom controls right away.  I knew that would happen, but not so quick on something so new (WinRT).  The XAML platform did not have good support for building custom controls in the Developer Preview but now that the Consumer Preview for Windows 8 and Visual Studio 11 Beta are out, there is much better support.  There are two key things when thinking about custom controls: 1) building it and 2) making it consumable by developers (even if those developers are your own company).  I’ll try to articulate the methods of both here.

Defining custom versus user control

There is usually some debate in the XAML community about the definition of a custom control.  For the purposes of this discussion I define a custom control as a control that provides a generic.xaml, can be styled/templated and is usually encapsulated in its own assembly which can then be distributed.  A custom control can contain user controls, but generally speaking does not.  A typical user control scenario is one that lives within your project and not meant to be consumed by anyone outside your project.

This definition is the same whether we are talking about C++, C# or Visual Basic.  Everything below applies to all languages.

Creating the custom control

The fundamentals of a custom control are that it is a class and it provides it’s own template/style.  This style/template definition usually lives in a file located at themes/generic.xaml.  This is the same pattern that has existed in other XAML implementations like WPF, Silverlight and Windows Phone.  The pattern is no different for Metro style apps in this regard.

The creation of the most basic custom control is very simple.  A Windows SDK sample for XAML User and Custom Controls is available for you to download for the quick review and core concept.  My intent here is to take that a step further for the end-to-end implementation if I were a control vendor.  Let’s first create our control.  For our purposes we will create a control that shows an Image and allows you to specify some Text for the label.  The label, however, will be prepended with some text that comes from string resources.

In Visual Studio we will create a class library project first.

NOTE: You can create a C#/VB Class Library and keep it managed, or convert it to a WinRT component.  You may also create this in C++ using the WinRT Component project type.  Again, these concepts are the same, the syntax will be obviously slightly different for C++ and managed code.

Once you create the class library (I called mine SimpleCustomControl and deleted the initial Class1.cs file that was created), add an item to the project.  You can do this via right-clicking on the project and choosing add item.  You will be presented with a few options, but the important one is Templated Control.

Add Item dialog

Watch was this does to your project as it will do 2 things:

  • Create a new class
  • Add a Themes folder and place a ResourceDictionary called generic.xaml in that folder

The themes/generic.xaml is very important if you use the DefaultStyleKey concept in your class.  This is very much a convention-based approach.  The contents of the class is very simple at this point, with the sole constructor and the DefaultStyleKey wired up:

   1: namespace SimpleCustomControl
   2: {
   3:     public sealed class LabeledImage : Control
   4:     {
   5:         public LabeledImage()
   6:         {
   7:             this.DefaultStyleKey = typeof(LabeledImage);
   8:         }
   9:     }
  10: }

This maps to the generic.xaml definition of our control.  Let’s modify our ControlTemplate in generic.xaml to be a little more than just a border:

   1: <Style TargetType="local:LabeledImage">
   2:     <Setter Property="Template">
   3:         <Setter.Value>
   4:             <ControlTemplate TargetType="local:LabeledImage">
   5:                 <Border Background="LightBlue" BorderBrush="Black" BorderThickness="2" 
   6:                         HorizontalAlignment="Center" Width="140" Height="150">
   7:                     <StackPanel HorizontalAlignment="Center">
   8:                         <Image Stretch="Uniform" Width="100" Height="100" 
   9:                                Source="{TemplateBinding ImagePath}" Margin="5" />
  10:                         <TextBlock TextAlignment="Center" FontFamily="Segoe UI" FontWeight="Light" 
  11:                                    FontSize="26.667" Foreground="Black" x:Name="LabelHeader" />
  12:                         <TextBlock TextAlignment="Center" 
  13:                                    Text="{TemplateBinding Label}" FontFamily="Seqoe UI" FontWeight="Light" 
  14:                                    FontSize="26.667" Foreground="Black" />
  15:                     </StackPanel>
  16:                 </Border>
  17:             </ControlTemplate>
  18:         </Setter.Value>
  19:     </Setter>
  20: </Style>

Now we have a place for an Image, LabelHeader and a Label.  Notice that we have {TemplatBinding} statements there.  This is how the template binds (duh) to values provided to the control.  So our ControlTemplate is expecting these properties to exist on our control.  We will create these as DependencyProperty types so we can use them in Binding, change notification, etc.  In Visual Studio we can make re-use out of the ‘propdp’ code snippet that exists for WPF.  It is slightly different in the last argument, but it will definitely save you a lot of typing.  We’ll create 2 DependencyProperties like this in our LabeledImage.cs file:

   1: public ImageSource ImagePath
   2: {
   3:     get { return (ImageSource)GetValue(ImagePathProperty); }
   4:     set { SetValue(ImagePathProperty, value); }
   5: }
   7: public static readonly DependencyProperty ImagePathProperty =
   8:     DependencyProperty.Register("ImagePath", typeof(ImageSource), typeof(LabeledImage), new PropertyMetadata(null));
  10: public string Label
  11: {
  12:     get { return (string)GetValue(LabelProperty); }
  13:     set { SetValue(LabelProperty, value); }
  14: }
  16: public static readonly DependencyProperty LabelProperty =
  17:     DependencyProperty.Register("Label", typeof(string), typeof(LabeledImage), new PropertyMetadata(null));

We also had that LabelHeader property.  This is going to be a value coming from a string resource that may be localized at some point.  In our library add a folder called “en” and then within that, using the Add Item dialog in VS, add a Resources.resw file.  Within that Resources.resw file add a name/value pair of name=LabelHeader.Text and value=This is an image of a… and you can save/close the file.

Now back to our class file we are going to set the value of our TextBlock by overriding our template rendering, grabbing a reference to that TextBlock and setting the value from our string resource.

   1: protected override void OnApplyTemplate()
   2: {
   3:     base.OnApplyTemplate();
   5:     TextBlock tb = GetTemplateChild("LabelHeader") as TextBlock;
   6:     tb.Text = new ResourceLoader("SimpleCustomControl/Resources/LabelHeader").GetString("Text");
   7: }

Now, I’m showing this way, because it is pretty verbose and there is an easier way…but you wouldn’t know it is easier unless you saw the harder way right?

First it is important to understand how these resources are indexed.  You’ll notice that I’m using a ResourceLoader class to map to what looks like {component}/{resw-file-name}/{property} which is effectively right.  When you create a resw file, at compile-time these get built into a PRI file.  This post isn’t about this whole resource loading process, but you should definitely understand this a bit.  Basically for a control creator perspective you need to understand that your string resources (and file-based resources) live in a ResourceMap that is the name of your component.

NOTE: An easy way to look at this resource indexing is to use the makepri.exe tool installed with VS.  From a VS command prompt navigate to your build output and you should see a resources.pri file.  Call makepri.exe dump and you’ll get an XML representation of that file you can look at.  Knowing that structure is very helpful.

I said there was an easier way to get that string though.  First remove the OnApplyTemplate override completely…we don’t need it for this control anymore.  Now in generic.xaml change the x:Name=”LabelHeader” to the following:

   1: <Style TargetType="local:LabeledImage">
   2: ...
   3:     <TextBlock TextAlignment="Center" FontFamily="Segoe UI" FontWeight="Light" 
   4:                FontSize="26.667" Foreground="Black" 
   5:                 x:Uid="/SimpleCustomControl/Resources/LabelHeader" />
   6: ...
   7: </Style>

This will use the XAML parser way of getting the string resource (note the ResourceMap is still in the x:Uid value).  Using the ResourceMap prefix is necessary when using this method as a custom control vendor.

We are done.  Our control is complete.

Consuming the control from an application

We can quickly test our control by adding a new Metro style app to our project.  Once we do this, make that the startup project and add a project reference to our control library.  Then in the default page for our app (BlankPage or MainPage depending on your template choice), add an xmlns to the top and then consume the control:

   1: <Page
   2:     x:Class="Application1.BlankPage"
   3:     xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
   4:     xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
   5:     xmlns:local="using:Application1"
   6:     xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
   7:     xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
   8:     xmlns:controls="using:SimpleCustomControl"
   9:     mc:Ignorable="d">
  11:     <Grid Background="{StaticResource ApplicationPageBackgroundBrush}">
  12:         <controls:LabeledImage ImagePath="Assets/110Orange.png" Label="Orange" />
  13:     </Grid>
  14: </Page>

See how the ImagePath and Label are used here?  In more advanced scenarios we can bind values from our view model or other ways.  When rendered the control will show like this:

Custom control rendered

This is great…but also what we call a “project-to-project” (P2P) reference.  As a control vendor we want to distribute our control, not our source primarily.  So we need to package this up.  There are two ways you can do this.

Package your control as an Extension SDK

One of the new methods for distributing Metro style controls in VS11 is via Extension SDKs, also sometimes referred to as non-Framework SDKs.  Extension SDKs are machine-wide and available to all projects once installed.  They can be distributed via the Visual Studio gallery and using the VSIX mechanism…which allows for update notification in Visual Studio.  There are a few intricacies that you can configure your Extension SDK but for most it will get down to three things:

  • Describing your SDK and what it supports
  • Including the binary that projects need to reference
  • Including any assets/files that the control relies on to render

In examining our sample above we have a few things that map to this:

  • Describing – our sample is a C# custom control so it will only work with managed Metro style apps, we will need to describe this in our SDK
  • Binary – we have one binary: SimpleCustomControl.dll
  • Redistributables – we have a generic.xaml and a PRI file with our string resources

The last part (redist) probably is making some existing XAML control developers scratch their heads.  Why isn’t the generic.xaml embedded is what you are likely asking yourself.  In Metro style apps, XAML assets are not embedded but rather exist as “loose file” assets for your control.  This is why it is critical for getting the distribution model correct so that the runtime knows where to get the definitions for everything.

NOTE: This is a default method.  You can, of course, use other techniques to get your assets into your binary either via string constants, other embedding techniques, etc.  In doing so, however, you will now be managing all those extractions yourself rather than being able to rely on the resource APIs for Metro style apps.

The first thing we want to do is understand the structure of an SDK.  These live in %ProgramFiles%\Microsoft SDKs\Windows\v8.0\Extension SDKs directory on disk.  Within there you will have your own folder, version and then the layout of your SDK, as described by your manifest.  Here is what our manifest (SDKManifest.xml) would look like for our control:

   1: <?xml version="1.0" encoding="utf-8" ?>
   2: <FileList 
   3:   DisplayName="Simple Custom Control" 
   4:   ProductFamilyName="Simple Controls"
   5:   MinVSVersion="11.0" 
   6:   MinToolsVersion="4.0" 
   7:   CopyRedistToSubDirectory="SimpleCustomControl"
   8:   AppliesTo="WindowsAppContainer+WindowsXAML+Managed"
  10:   MoreInfo="http://timheuer.com/blog/">
  11:   <File Reference="SimpleCustomControl.dll">
  12:     <ContainsControls>True</ContainsControls>
  13:   </File>
  14: </FileList>

We are describing the display information as well as some key data:

  • Display data – the title that will show up in Add Reference
  • CopyRedistToSubdirectory – this would be the name of your component
  • AppliesTo – what I support; in this I’m saying managed, XAML, Metro style apps
  • <File> – these are the files that describe components in my SDK (not their loose assets)

Now to create the structure.  When you build the DLL your output will give you this:

Build output

We need to create the following structure that will live under the Extension SDK folder listed above:

%ProgramFiles%\Microsoft SDKs\Windows\v8.0\Extension SDKs\



------SDKManifest.xml (the file above)




Notice the References and Redist folders.  By placing these in that structure, the project will know what it needs to get type information (References) and then during running/deployment what it needs to package (Redist) and where it puts it (CopyRedistToSubdirectory).  Put this layout in the directory and then when you choose add reference on a project you will see your option:

Add reference dialog

There are other configuration options for the SDKManifest that you can use and the required reading is the Extension SDK section in this MSDN article: How to: Create a Software Development Kit.

The next step for an Extension SDK is to really package it up nicely.  You probably don’t want your users copy directories around all the time…and what about updates as well!  Using the Visual Studio VSIX structure for this really makes it easy to do.

There are tools for Visual Studio to allow you to create a VSIX package.  This requires the Visual Studio extensibility SDK to be installed and using Visual Studio professional or higher.  Once you do that you can create a VSIX package and you will see the VSIX manifest designer.  On the Install Targets tab you will choose Extension SDK:

VSIX Install Targets

We then re-create the layout structure in the VSIX project and add the Assets to the manifest.  The result in the IDE looks something like this:

VSIX Manifest Assets

Now when we build we will get a VSIX installer that we can upload to the Visual Studio Gallery or distribute to our customers.

NOTE: Uploading the to Visual Studio Gallery has benefits in that once installed, any update you put in the gallery will provide notifications to the Visual Studio user than an update exists.  This is done via the unique Product ID value in your manifest, so choose that value accordingly and don’t change it if you want this capability.

When a user gets the VSIX, they double-click it and see the installer:

VSIX Installer

And then they can use it as normally in Add Reference just like described above.  Additional details on other VSIX deployment configurations can be found here: VSIX Deployment.

Once you have your VSIX you can upload to the Visual Studio Gallery and make it discoverable for users from within Visual Studio.  Remember that this method of Extension SDK is machine-wide which is in contrast to the second method described next.

Package your control as a NuGet Package

The other option you have is to package up your control via a NuGet package.  NuGet packages apply to the project and not the machine, but have the flexibility of not having to have anything installed and can travel their dependencies with the project.  NuGet packages are another type of package that has a manifest that describes what the content does. 

For Metro style XAML controls you will have to do a few things differently currently with the NuGet package you create.  NuGet packages are based on nuspec files, which is basically a manifest describing where to get/put things in the package.  You can also use the NuGet Package Explorer for a GUI way of reading/creating new packages.  If you are unfamiliar with the nuspec format, using the package explorer will help you get a package created quickly. 

NuGet is one area where there actually are current differences in C++ or managed code.  Right now NuGet only supports managed code projects and not C++.  I’m sure this may change in the future, but as of right now this applies only to managed code.  For our control above here is what my nuspec file looks like:

   1: <?xml version="1.0"?>
   2: <package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
   3:   <metadata>
   4:     <version>1.0.0</version>
   5:     <authors>Tim Heuer</authors>
   6:     <owners />
   7:     <id>SimpleCustomControl</id>
   8:     <title />
   9:     <requireLicenseAcceptance>false</requireLicenseAcceptance>
  10:     <description>A simple custom control for Metro style apps</description>
  11:   </metadata>
  12:   <files>
  13:     <file src="SimpleCustomControl\bin\Debug\Themes\Generic.xaml" target="lib\winrt\SimpleCustomControl\Themes\Generic.xaml" />
  14:     <file src="SimpleCustomControl\bin\Debug\SimpleCustomControl.dll" target="lib\winrt\SimpleCustomControl.dll" />
  15:     <file src="SimpleCustomControl\bin\Debug\SimpleCustomControl.pri" target="lib\winrt\SimpleCustomControl.pri" />
  16:   </files>
  17: </package>

This assumes that the binaries being referenced here are all relative to the nuspec file.  Notice how all the files go into the lib\winrt folder and that we essentially re-create that SDK layout in our package as well.

Now when I build this with nuget.exe I get a package output.  In Visual Studio (with NuGet installed) I can now right-click on a project and choose Manage NuGet Packages and browse the library of packages.  In testing out my package, I create a custom library (you do this via the Settings option when you are in the Manage NuGet Packages dialog) and just point it to the folder where my nupkg file was created:

Manage NuGet Packages dialog

When the package is selected, the reference is added to my project and during build, all the right pieces are put in my APPX package where they need to go.  Once the reference is there I build and run my project and the control renders as expected!

What about the design-time experience?

All of the methods above will allow you to view your control on the XAML design surface in Visual Studio as well.  In the Extension SDK method there is actually additional affordances for you to provide additional design-time assemblies/resources to make that experience even better.  Custom control developers for XAML know about this .Design.dll that is created for their projects that can improve the design-time experience for UI controls.  I highly encourage you to do that if you are creating a control that is for wide distribution and not just yourself or your small group of friends.


Wow this felt like a long post…thanks for reading this far!  I think developing custom controls is a great way to encapsulate specific UI and behavior you want in your application.  XAML has a great ecosystem of control vendors and I fully expect them to produce controls for Metro style apps as well.  Hopefully these techniques of packaging them up for distribution will help us all take advantage of them.

I also think that creating an Extension SDK *and* a NuGet package are the best ways of thinking about it as a producer.  This enables your consumers to have the greatest flexibility in how they want to consume your control.  Creating these distribution mechanisms may seem cumbersome at first (and there are some places where Visual Studio can improve the experience of creating/managing these manifests), but once you understand the core layout that is required for a Metro style XAML control and the fact that you now have “loose files” to consider it really becomes pretty streamlined and you can automate the creation of these pretty quickly in your build systems.

Be sure to check out these resources again:

Here is the solution for the project I walked through above: SimpleCustomControl.zip

Hope this helps!

| Comments


A while back I posted a sneak peek preview of 3 new themes that we were working on for Silverlight 4 applications.  Our team wanted to do more than just the overall base theme and provide the themes for the core, SDK and some Silverlight Toolkit controls as well.  In addition, there was a lot of internal chatter about how cool these new themes were and a lot of teams wanting to adopt them as default, including WCF RIA Services.

While we finalize a better distribution plan for these templates (and some may show up as defaults soon), I wanted to provide a raw drop of the sample project we use to display the themes.  These projects have the Silverlight ResourceDictionary files for the themes and a few pages showing samples.  These are raw theme project files.  And without further adieu, I present the bits for you:

Grayscale Theme

This theme is a clean implementation that initially has a ‘greenscale’ approach to it, but modifying the brushes even slightly will give you some great color pallettes to work with.

Silverlight 4 Theme - Grayscale

Honestly, initially this one didn’t pop for me as much, but the fit-n-finish added here is really making me like this structure.  And the ability to change a single brush and have it replicate through other areas makes this clean template highly customizable.

Windows Theme

Want a theme for your application to look a bit more native?  Here’s a starter place for you. 

Silverlight 4 Theme - Windows

Cosmopolitan Theme (formerly Metro)

And finally the most popular requested, we’re calling Cosmopolitan.  This one has features that resemble the Zune and Windows Phone design language aspects of it in a modern, clean UI form.

Silverlight 4 Theme - Cosmopolitan

This theme also has a ToUpper and ToLower behavior files that you can apply to your XAML for text formatting.

How these raw projects are structured

As I mentioned, these are raw project structures…ripped from the designer’s desktop, zipped and presented here.  There may be dependencies that you don’t have and will need (i.e., Toolkit, etc.).  There may be residual test files in there.  Deal with it :-).  But at the basics the core themes are all structured as ResourceDictionary files in the Assets folder:

Theme project structure

As you can see in here the files should be relatively self-explanatory.   We tried to make it so that you can pick and choose what you’d like from them (as well as learn how to segment out these types of dictionary files).

In each project you will also see the themes represented in showing: core controls, sdk controls and toolkit controls.  Please make sure to appreciate all of them.  I didn’t post screenshots of all here.

The future deployment of these themes/templates

The idea is that we’ll clean these up in a more distributable manner.  We’ll likely create VSIX files (Visual Studio extension installers) so that you could then say File…New Silverlight Cosmopolitan Application and have these already in there.  This also allows us to put them in the Visual Studio Gallery where you can search/download directly to Visual Studio.  We also will likely put the resources on the Expression Gallery for download.  And as I mentioned before, it’s possible that future iterations of things like WCF RIA Services and such might use them as default.  You tell me: what is the best distribution method?  How would you expect to download/install/use these?


I love these new themes.  I think our design team did a great job here.  Tsitsi and Corrina are awesome and put a lot of work into refining these.  By the feedback that I’ve been getting in email and blog comments, these are exactly the type of things that you’ve been wanting.  Mostly from developers I’m hearing the thank you for helping me since I have no design skills!  This is great feedback that our team loves to hear.  I hope you find these valuable.

These raw project templates here are essentially the Silverlight Navigation Application template modified.  We’ll have the biz app ones a while later, but these should get you started.

Hope this helps!

This work is licensed under a Creative Commons Attribution By license.

| Comments

The source code for the Silverlight 2 controls was just published!  This is the source for the controls as shipped in the runtime and the SDK.  When you download the project you’ll see the structure:

Image of source project tree in Visual Studio

The source, released under the Microsoft Public License (Ms-PL), includes the source for the following controls in the runtime:

    • ButtonBase
    • Button
    • HyperlinkButton
    • CheckBox
    • RadioButton
    • ToggleButton
    • RangeBase
    • ProgressBar
    • Slider
    • ScrollBar
    • Thumb

and the following from the SDK (part of the Silverlight Tools for Visual Studio):

    • Calendar
    • DatePicker
    • DataGrid
    • TabControl
    • GridSplitter

Unit tests for the SDK controls have also been included as well!

With the release of this source code as well as having access to the source for the Silverlight Toolkit, you should have some great base implementations to extend and learn from!  Get the code here: Source code for Silverlight 2 controls.

| Comments

Last week I had the pleasure of talking with the crew from the Herding Code podcast.  Among the questions was one about the open source community and Silverlight.  There was mention about MVCContrib and how that community sprouted almost instantly with the ASP.NET MVC initial releases.  I let the Herding Code crew know that I believe there already is a vibrant open source community around Silverlight and pointed to things like DevExpress’ AgDataGrid control which is free and provides source.  I also mentioned a project that did start right away around Silverlight 2 initial releases: .  The project, started by Page Brooks, had a good start and keeps on rolling now as they just released a set of free open source Silverlight controls!

The team of Page Brooks, Rob Houweling, Koen Zwikstra, and Shawn Wildermuth have just released “Alpha 2” of the project which includes:

    • Color Picker
    • Gauge Control
    • Star Selector
    • Enhanced Metafile (EMF)
    • Cool Menu
    • Libraries: Zip, Byte utilities, String utilities, Simple text parser, Animation Tweening, Wheel Mouse listener

While the project code is hosted at Codeplex, the team also has a blog at SilverlightContrib.org which has a Live Demo page that will show you demonstrations about the controls:

Color Picker:

Cool Menu (OSX style):

Gauge samples:

The code is available with the Ms-Pl license which is very permissive, so go and grab these controls…and better yet…contribute back to the project!!!  There are more than just controls there as I mentioned there are libraries as well – check out the Live Demo for examples.  I haven’t checked to see their compatibility with the Blend designer, but that is something you can tweak with yourself as needed.

Congratulations to Page and the team for a great community resource and a great release.  I look forward to more great things!

| Comments

I suspect we’ll be seeing more of these efforts for Silverlight and I love it.  In fact, INETA will be sponsoring the 2008 INETA Silverlight Challenge soon, so you should sign up for more information about that as well.  But until then…

But until then, check out what some of the community MVPs and leaders are doing on their own!  They’ve started the Silverlight Control Builder Contest ‘08.  Two main organizers (Page Brooks and Dave Campbell) have put some time and thought into how they can get the community excited about developing solutions for the community and alas this idea came out of that!  These two have done some research, sought guidance, solicited some sponsors and did this on their own.  They built the contest site which is very detailed providing all the rules, prizes, and an FAQ.  Please be sure to read the rules.  One key thing is that this contest is open to US residents (over 18) only.  Please note that Pete/Dave answer why in their FAQ and please also realize this is completely a community-driven effort from these two guys.  I applaud them for their efforts and can tell you that they indeed researched the effort to make it an internationally available contest, but simply didn’t have the resources to do so…but hey, there is nothing preventing you in your local community from using this same idea :-).

Additionally, there are some additional tidbits in the rules, so read them carefully…I picked out some highlights only:

    • Silverlight 2 Beta 2 or higher
    • Control must have a default and 1 additional template
    • No use of third-party controls
    • Source code must be open
    • Entries cannot be commercial/shareware

The prizes are pretty great as well, including a 1-year MSDN Premium subscription provided by the organizers of the contest!

So get your mind working and submit your entry by 11 AUG 2008.  Since only 1 entry allowed per contestant, make sure you put some good thought into it!