If you write Silverlight controls, you should consider writing design time assemblies for your controls too, for two simple reasons:

• developer productivity: try to imagine Silverlight development without tools like Visual Studio or Blend! For custom controls, you may need to provide much of the design time experience for your controls in Visual Studio or Blend yourself.
• designers: XAML and tools like Blend enable developers and designers work together. A key design criteria for Silverlight controls is to make sure designers can use them without writing a single line of code.

Design time experience usually includes (but not limited to) the following:

1. Metadata for property window, like category, infotip, custom property/binding/collection editors etc.
2. Metadata for design surface, like initializer, adorner, context menu, adapters etc.
3. Toolbox integration, like icons, control registration
4. intellisense for code editor

Except intellisense (please see Add Rich Intellisense for Your Silverlight Controls) and control registration (please see Register Silverlight Controls with visual Studio and Blend), above design time experience are usually delivered through design time assemblies. Below I will discuss various approaches of delivering design time experiences, in increasing complexity and flexibility, and gradually introduce pieces of the naming convention for design time assemblies.

Runtime Assembly Only

The simplest way to deliver design time experience is to package design time code into the runtime assemblies, especially when design time metadata are meaningful at runtime too, like TypeConverterAttribute.

The pros and cons of this approach:

• Pro: simple
  • no separate design time assemblies, simpler setup
  • design time attributes are specified directly on the runtime code, easier to maintain
• Con: tight coupling of runtime and design time code
  • perf degradation because of useless design time code at runtime
  • design time dependencies (like MWDs and other VS/Blend assemblies) get dragged into runtime unnecessarily
  • can’t service runtime or design time independently
  • can’t support multiple designers (like both VS2008/Blend2 and VS2010/Blend3)

The cons are particularly bad for Silverlight, because design time assemblies are actually .NET assemblies, with references to Silverlight types. Mixing Silverlight and .NET assemblies can be challenging and confusing, and may lead to subtle bugs. Also, Silverlight applications are mostly web applications, so download size and performance are particularly important. Dragging in .NET assemblies in Silverlight applications certainly doesn’t help. So this approach is highly discouraged, unless there is strong justification for it.

Shared Design Time Assembly

So the revolutionary step forward is to decouple design time and runtime code, release and service them with separate assemblies. This opens up all kinds of possibilities. Of course, we need a way to link design time assemblies to their corresponding runtime assemblies, without introducing any unnecessary dependency or perf degradation to runtime assemblies. Hence the naming convention: if a runtime assembly Foo.dll is referenced in a Silverlight project, the designer (like Visual Studio and Blend) will first try to load design time information like icons (via another naming convention, see How to Add an Toolbox Icon for Your Silverlight Control) and design time metadata (via interface, like IRegisterMetadata for VS2008 and Blend2, or IProvideAttributeTable for VS2010 and Blend3. Please see How to Write Silverlight Design Time for All Designers: Visual Studio 2008, Blend 2; Blend 3, and Visual Studio 2010) from the runtime assembly; it will then look for a design time assembly by the name Foo.Design.dll in the same directory as Foo.dll; if found, the designer will try to load design time information from Foo.Design.dll as well.

Designer Specific Design Time Assembly

Visual Studio is mostly for developers, while Blend is mostly for designers, so they have different requirements for design time experiences. Putting all design time code in one shared design time assembly introduces tight coupling among designers. So the naming convention is enhanced: for runtime assembly Foo.dll, there is a shared design time assembly Foo.Design.dll that’s loaded by all designers; each designer will also try to load its own design time assemblies, like Foo.VisualStudio.Design.dll for Visual Studio, and Foo.Expression.Design.dll for Blend. The designer specific design time assembly is loaded after the shared design time assembly. Third party designers can define their own designer specific design time assembly. Silverlight Toolkit December 2008 Release is using this naming convention. Please see Design Time Features in Silverlight Toolkit and Design Time Feature Implementation in Silverlight Toolkit for more information.

Design Sub Folder

So to support both Visual Studio and Blend, each runtime assembly has three design time assemblies, in the same directory, and a package (like Silverlight SDK or Silverlight Toolkit) usually contains several runtime assemblies. So the directory gets a bit crowded. A minor improvement is to put the design time assemblies under a Design subfolder. So the naming convention is further enhanced: if a designer (like Visual Studio or Blend) can’t find corresponding design time assemblies in the same directory as a runtime assembly, it will look for them in the Design subfolder, if it exists. 

Support Multiple Versions of MWDs

Design time are built on top of designer extensibility framework, which consists of several dlls like Microsoft.Windows.Design.Extensibility.dll and Microsoft.Windows.Design.Interaction.dll. We usually call them collectively as MWDs. To make life more interesting, sometimes we have to introduce breaking changes to the extensibility framework, like VS2008 and Blend2 use MWD version 3.5, VS2010 and Blend3 use MWD version 4.0, and they are incompatible. So if you have a runtime assembly Foo.dll, and you want your users to be able to develop against it with both VS2008 and VS2010, you have to provide two sets of design time assemblies: one set built against v3.5 MWDs and used by VS2008, and another set built against v4.0 MWD and used by VS2010. The two sets of design time assemblies probably have a lot of code in common, while the one for VS2010 may have some new code to leverage the new functionalities exposed by VS2010. Since design time assemblies are loaded by name and you can’t have two files with the same name, so the naming convention is enhanced yet again:

for a runtime assembly Foo.dll, the shared design time assembly is named Foo.Design*.dll, the Visual Studio specific design time assembly is named Foo.VisualStudio.Design*.dll, and the Blend specific design time assembly is named Foo.Expression.Design*.dll, where * can be zero or more valid characters for file names. When a designer (like Visual Studio or Blend) tries to load a design time assembly and several fit the naming convention, zero or one will be loaded:

• If the MWD version referenced by the design-time assembly has a different major version number than the designer’s MWD version, then the design-time assembly will not load and is bypassed.
• If more than one design-time assembly is compatible with the designer’s MWD version, the Designer loads the one compiled against the highest MWD version that is less than or equal to the designer’s MWD version.

Silverlight 3 Toolkit October 2009 Release uses this naming convention to support both VS2008 and Blend3/VS2010. Please see Silverlight Design Time: Toolkit October 2009 Release Update, How to Write Silverlight Design Time for All Designers: Visual Studio 2008, Blend 2; Blend 3, and Visual Studio 2010, and Extensibility Series – WPF & Silverlight Design-Time Code Sharing – Part I more information.

Support Both WPF and Silverlight

To complicate life further, since WPF and Silverlight are so awfully similar, you may be tempted to try to write it once and run with both WPF and Silverlight. You are not alone. There are many articles on how to share source code and/or binaries across Silverlight and WPF. We’d like to do that for design time assemblies too, i.e. have the same design time assemblies for both WPF and Silverlight controls. One approach is to make most of the design time assemblies platform agnostic, and limit platform specific (WPF or Silverlight) code and references to a small platform specific assembly. Silverlight 3 SDK GDR 2 (installed by VS2010 automatically too) uses this approach for DataGrid designer (there is a System.Windows.Controls.Data.VisualStudio.Design.4.0.Silverlight.dll in the SDK directory). Please see Extensibility Series – WPF & Silverlight Design-Time Code Sharing – Part I for more information.

Last One Wins

The same design time metadata for a class or its member can be specified multiple times in multiple design time assemblies, which allows the shared design time assembly to specify default/common behavior and then designer specific design time assemblies to override it if necessary. The same design time metadata can also be specified multiple times within a single design time assembly (please see Design Time Feature Implementation in Silverlight Toolkit as an example, where DescriptionAttribute for a class or its property can be added by AddDescriptions, AddAttributes and AddTables methods). So we need to know which metadata wins. The simplest and most logic design is last one wins. This is mostly true but not always. Sometimes the result can be un-deterministic when the same design time metadata is specified several times but with different values.

Feedback

Design time sounds easy, but devil is in the details! Feedbacks are always appreciated. Please let me know what issues you run into, what requests/improvements you’d like to make, for both design times experience and designer extensibility framework. Thanks!

Visual Studio 2010 Beta 2 is available now. For Silverlight developers, the most exciting news about VS2010 is that Silverlight designer will be in feature parity with WPF designer, and VS2010 will support multi-targeting for Silverlight development. Silverlight Toolkit team has been working closely with Cider team in providing the design time experience for Silverlight SDK and Toolkit controls. The design time for Silverlight 3 SDK controls has been released with SL3 SDK in August 2009, and is also chain installed by VS2010 Beta2. The design time for Toolkit controls, together with sources for both SDK and Toolkit controls, and their design time, samples, unit tests etc, are in Silverlight Toolkit October 2009 Release. We purposely made October 2009 release to be in sync with Visual Studio 2010 Beta 2 on Monday, 10/19/2009. This post demonstrates the new design time experiences for Silverlight controls in VS2010.

Install

VS2010 installs side by side with VS2008. Multiple releases of Toolkit install side by side too. So it is perfectly safe to install VS2010 and Toolkit October 2009 release on your main machine. The only caveat is that if you have a pre August 2009 version of Silverlight 3 SDK installed, you will need to uninstall it first, before installing VS2010. You can install VS2010 Beta2 from http://msdn.microsoft.com/en-us/vstudio/dd582936.aspx, and Silverlight Toolkit from http://silverlight.codeplex.com.

Walkthrough

The October 2009 release is for Silverlight 3 only. It provides design time support for both VS2008 and VS2010, as well as Blend 3. Below walkthrough will be VS2010 only. Design time experience for VS2008 and Blend 3 are similar to July 2009 release. Please see my previous posts for design time experience with VS2008 and Blend3.

• Create a new Silverlight Application project in VS2010, notice that:
  
  • the toolbox is populated with both SDK and Toolkit controls, with nice icons. If you have Blend3 installed before Toolkit, you may see a lot of Blend controls on the toolbox that are not supposed to. You can safely remove them by right click a control in the toolbox and select delete.
  • it is a real designer: both the design view and the properties window work!
• double click TabControl in the toolbox will add a tabControl1. Notice that:
  
  • A reference to System.Windows.Controls.dll is added, together with a xmlns definition: xmlns:controls="clr-namespace:System.Windows.Controls;assembly=System.Windows.Controls"
  • tabControl1 is initialized with a tabItem1, which itself is initialized with a header and <Grid/> content. (via DefaultInitializer)
  • Property Items is selected in the Properties window (via DefaultPropertyAttribute)
  • Properties are categorized (via CategoryAttribute), and have tooltip (via DescriptionAttribute)
• Double click tabControl1 will add an event handler for SelectionChanged event (via DefaultEventAttribute)
  
• right click tabControl1, select Add Tab (via PrimarySelectionContextMenuProvider):
  
• A new tabItem2 is added. Notice that:
  
  • tabItem2 is initialized with a <Grid/> content
  • tabItem2’s default property Header is highlighted. You can type into the text box next to it and change the object typed Header property directly. (via TypeConverterAttribute)
  • all properties have nice infotip
• double click DatePicker on toolbox:
  
  • a datePicker1 is added to tabItem2’s <Grid> (via ParentAdapter)
  • datePicker1 is fully expanded, even though its IsDropDownOpen property is false (via DesignModeValueProvider)
• Now click tabItem1, notice that tabItem2’s content is hidden and tabItem1’s is shown:
  
• click Chart on toolbox:
  
  • a chart1 is added to the right place, initialized with sample data, and nicely rendered
  • default property Series is selected in the properties window
• click the … button next to Series property to pop up the Collection Editor:
  
  • the Select item ComboBox is populated with the correct types (via NewItemTypesAttribute). The pink background for the icons are fixed now.
  • the Properties window for the series highlights the default property DependentValuePath, have all properties categorized (like the Data Visualization category), and you can modify the object typed Title property directly in the text box.
• Create a simple data class with some simple properties, and add it as a data source, via Data |  Show Data Sources menu item: 
  
• Drag MyData over tabItem1’s header and drop it :
  
  • a CollectionViewDataSource is inserted, used as DataContext of the LayoutRoot, and tabItem1’s Header is bound to it. (Via DefaultBindingPropertyAttribute)
• Just for fun, open the project in Blend 3, you will see very similar design time behaviors:
   

While VS2010 design time is the exciting new feature of this release, design time support for VS2008 and Blend 3 are still there and has lots of bug fixes. Please refer to previous post Silverlight Toolkit Design Time Features: March 2009 Release Update for more information for VS2008 and Blend 3 design time experience.

Conclusion

Above walkthrough is only a peek into all the design time features we have implemented for VS2010. I am very excited that VS2010 now provides a real designer for Silverlight, and I will continue enriching the design time experience for Silverlight in VS and Blend. Your feedback is welcome.

I will write a series of posts explaining how those design time experience are implemented.

• Install Silverlight 3, Blend 3 and Toolkit from http://silverlight.net/getstarted/
• Open Blend 3, create a new Silverlight 3 Application project
• Open Asset Library, notice few improvements:
  • the new Asset Library. See Unni’s blog The Blend 3 Asset Library for more info. 
  • the nicer icons and more informative infotip

• Add an Expander control, and set it as the new active container:

• Add a DatePicker to the Expander, notice that both the DatePicker and its Calendar drop down are shown, even though both Expander’s IsExpanded and DatePicker’s IsDropDownOpen are false.

• Select LayoutRoot so Expander and the nest DatePicker are no longer selected, notice that both are now collapsed.

Open the project in Visual Studio,notice that the Toolbox is populated with lots of controls from Silverlight SDK and Toolkit, with nice icons.

So far, design time features for Silverlight are mostly exposed through Blend. This will change with next beta of Visual Studio 2010, which will come out soon, according to this Visual Studio Magazine article. Stay tuned!

Introduction

This is part of the series on design time feature implementation in Silverlight Toolkit. This post uses the Chart default initializer to illustrate how to implement default initializer for Silverlight controls, and explain the underlying editing model architecture.

Experience

If you install Silverlight 3 Toolkit in March 2009 Release, you can drag the Chart control from Blend Asset Library and drop it onto designer surface, and you have a chart nicely initialized and rendered:

You can read more about it in prior post Silverlight Toolkit Design Time Features: March 2009 Release Update.

Architecture

DefaultInitializer

It is actually pretty simple to provide a default initializer for a Silverlight control:

• implement a subclass of DefaultInitializer, and override its InitializeDefaults function
• associate the default initializer class with the control class via a FeatureAttribute

Below screenshot shows the implementation of DefaultInitializer abstract base class, and other classes in Microsoft.Windows.Design.Model namespace that will be discussed shortly:

Initialization is done in InitializeDefaults override, and result is serialized into xaml. So the first step in implementing a default initializer is to define the desired xaml to be produced.

Editing Model

Once the result xaml is defined, I wish there is a higher level abstraction/method that would just take the xaml. But unfortunately we have to use a much lower level (thus more flexible and powerful) imperative API called editing model that consists of classes like ModelItem, ModelProperty, ModelEvent, ModelFactory and ModelService. The MSDN page Editing Model Architecture gives an basic overview:

Your design-time implementation interacts with run-time controls though a programming interface called the editing model. The objects being designed are called editable objects.

Your controls are defined in Extensible Application Markup Language (XAML). You update the XAML for your controls programmatically by using the editing model.

Model, Wrapper, and View

The editing model consists of three functional subunits: a model, a public wrapper that abstracts the model, and a view that represents the user interface (UI) of the model. The model and the view are separate, but the wrapper and model are closely related. The following illustration shows the relationship among the three subunits.

The design environment uses the ModelItem type to communicate with the underlying model. All changes are made to the ModelItem wrappers, which affect the underlying model. This allows the model to be simple. The ModelItem wrappers handle complex designer features, such as transaction support, undo tracking, and change notifications.

Below class diagram may help explain interactions among core classes of the editing model:

Use below xaml as an example:

<UserControl
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    x:Class="ModelTest.Page" Width="640" Height="480">
    <Grid x:Name="LayoutRoot" Background="White">
        <Button x:Name="Button">
            <Rectangle x:Name="Rectangle" />
        </Button>
    </Grid>
</UserControl>

• ModelItem: assume variable item is the ModelItem for the Button control above,
  • Name is persisted as x:Name attribute in xaml: item.Name = “Button” is persisted in xaml as x:Name = “Button”.
  • ItemType is the Type object of the underlying control, and decides the tag used in xaml: item.PropertyType == tyepof(Button), and the xaml tag is <Button />.
  • Properties is the collection of properties, wrapped in ModelProperty type, of the underlying control. For example: item[“ClickMode”] = ClickMode.Release will be persisted in xaml as ClickMode=”Release”.
  • Content represents the Content property defined in ContentControl (and inherited by its subclasses): item.Content is the ModelItem representing the Rectangle object.
  • Source: when a ModelItem represents an element that’s a property of another element, Source is the ModelProperty wrapper of that property. For example, item.Content.Value.Source == item.Content // the Rectangle.
  • Events represents the collection of events of the underlying control, wrapped in ModelEvent type. From my debugging experience, it is always null, so it seems Events property is not yet supported by Blend3 for Silverlight3 yet.
  • Parent is the the logic parent of the underlying control, wrapped in ModelItem type. ex: item.Parent is the ModelItem for Grid.
  • Root is the ModelItem wrapper for root visual, ex: item.Root represents the UserControl.
• ModelProperty: assume variable prop is the ModelProperty for Button.Content, i.e. prop = item.Content,
  • Name is the name of the property of the underlying control. It is persisted in xaml as attribute name. ex: prop.Name == “Content”.
  • PropertyType is the Type object of the property of the underlying control this ModelProperty object represents. ex: prop.PropertyType = typeof(object).
  • AttachedOwnerType is the Type object of the control that first defines the property this ModelProperty object represents. ex: prop.AttachedOwnerType == typeof(ContentControl) // note: not Button.
  • Value is the value of the property of the underlying control, wrapped in ModelItem type. ex: prop.Value is the ModelItem representing the Rectangle object.
  • Parent is the control, wrapped in ModelItem type, of which the property belongs to. ex: prop.Parent == item.
• ModelEvent: as mentioned above, item.Events is always null, so it doesn’t seem that ModelEvent is supported in Blend3 for Silverlight3 yet. But assume it works, and variable evt is the ModelEvent for Button.Click, i.e., evt = item.Events[“Click”],
  • Name is the name of the event. ex: evt.Name == “Click”.
  • EventType is the type of the event delegate, ex: evt.EventType == typeof(RoutedEventHandler).
  • Handlers is the string collection of event handlers, ex: evt.Handlers = new string[] { “Button_Click” } will be persisted as Click = “Button_Click”. Note: this is pure speculation, since ModelEvent isn’t yet supported, and I don’t know whether/when/how it will be supported for Silverlight.
  • Parent is the control, wrapped in ModelItem type, of which this event belongs to. ex: evt.Parent == item.

Implementation

The Chart default initializer class ChartDefaultInitializer is implemented in ChartDefaultInitializer.cs, and registered in ChartMetadata.cs. Both files are in Controls.DataVisualization.Toolkit.Design.csproj of Silverlight.Controls.Design.sln. Please read prior post Design Time Feature Implementation in Silverlight Toolkit for more information.

Result XAML

As the first step, define the result xaml to be produced by ChartDefaultInitializer:

<Charting:Chart Title="Chart Title">
    <Charting:Chart.DataContext>
        <PointCollection>
            <Point X="1" Y="10" />
            <Point X="2" Y="20" />
            <Point X="3" Y="30" />
            <Point X="4" Y="40" />
        </PointCollection>
        <Charting:Chart.Series>
            <Charting:ColumnSeries ItemsSource="{Binding}"
                DependentValuePath="X"
                IndependentValuePath="Y" />
        </Charting:Chart.Series>
    </Charting:Chart.DataContext>
</Charting:Chart>

Registration

Done in ChartMetadata.cs with following code:

b.AddCustomAttributes(new FeatureAttribute(typeof(ChartDefaultInitializer)));

References

See below screenshot:

Even though DefaultInitializer is defined in version 3.5 of Microsoft.Windows.Design.Interaction.dll (under %devenvdir%\PublicAssemblies, i.e. c:\Program Files\Microsoft Visual Studio 9.0\Common7\IDE\PublicAssemblies on 32bit Windows), it is not supported by Blend2 or Visual Studio 2008 for Silverlight. It is supported by Blend3 and Visual Studio 2010, but they both switch to newer version of Microsoft.Windows.Design*.dll (3.7 for Blend 3 Preview, 4.0 for Blend 3 RTM and Visual Studio 2010), so we need to link against the newer version of MWDs. Please see prior post How to Write Silverlight Design Time for All Designers: Visual Studio 2008, Blend 2; Blend 3, and Visual Studio 2010 for more information.

Please also notice that reference to Silverlight’s System.Windows.dll is aliased, and the PointCollection is specifically called out to be the Silverlight one, not WPF’s. Since WPF and Silverlight share a lot of classes in same namespaces, it is important that Silverlight types, not WPF’s, are used in creating ModelItem and ModelProperty in default initializer for Silverlight controls.

Collections

Please note in below screenshot that while all other property value can be set via ModelProperty.SetValue:

Chart.Series is of collection type (Collection<Series>), so its value has to be set by first creating a ModelItem via ModelFactory.CreateItem for the value, and then add the created ModelItem via ModelProperty.Collection.Add. Otherwise, even though the correct xaml may be generated, Blend won’t refresh to render the Chart control correctly, you have to reload the page to have it rendered correctly.

ChartDefaultInitializer.cs

// (c) Copyright Microsoft Corporation.
// This source is subject to the Microsoft Public License (Ms-PL).
// Please see http://go.microsoft.com/fwlink/?LinkID=131993 for details.
// All other rights reserved.

extern alias Silverlight;
using System.Windows.Controls.DataVisualization.Charting;
using System.Windows.Controls.Design.Common;
using Microsoft.Windows.Design.Metadata;
using Microsoft.Windows.Design.Model;
using SSW = Silverlight::System.Windows;
using SSWD = Silverlight::System.Windows.Data;
using SSWM = Silverlight::System.Windows.Media;

namespace System.Windows.Controls.DataVisualization.Design
{
    /// <summary>
    /// Default initializer for chart. 
    /// </summary>
    internal class ChartDefaultInitializer : DefaultInitializer
    {
        /// <summary>
        /// Sets the default property values for chart. 
        /// </summary>
        /// <param name="item">Chart ModelItem.</param>
        public override void InitializeDefaults(ModelItem item)
        {
            string propertyName;

            // <Charting:Chart Title="Chart Title">
            propertyName = Extensions.GetMemberName<Chart>(x => x.Title);
            item.Properties[propertyName].SetValue(Properties.Resources.ChartTitle);

            // <Charting:Chart.DataContext>
            //     <PointCollection>
            //         <Point X="1" Y="10" />
            //         <Point X="2" Y="20" />
            //         <Point X="3" Y="30" />
            //         <Point X="4" Y="40" />
            //     </PointCollection>
            // </Charting:Chart.DataContext>

            SSWM::PointCollection defaultItemsSource = new SSWM::PointCollection();
            for (int i = 1; i <= 4; i++)
            {
                defaultItemsSource.Add(new SSW::Point(i, 10 * i));
            }

            propertyName = Extensions.GetMemberName<Chart>(x => x.DataContext);
            item.Properties[propertyName].SetValue(defaultItemsSource);

            // <Charting:Chart.Series>
            //     <Charting:ColumnSeries ItemsSource="{Binding}"
            //         DependentValuePath="X"
            //         IndependentValuePath="Y" />
            // </Charting:Chart.Series>

            ModelItem columnSeries = ModelFactory.CreateItem(item.Context, typeof(ColumnSeries));
            propertyName = Extensions.GetMemberName<ColumnSeries>(x => x.ItemsSource);
            columnSeries.Properties[propertyName].SetValue(ModelFactory.CreateItem(columnSeries.Context, typeof(SSWD::Binding)));
            propertyName = Extensions.GetMemberName<ColumnSeries>(x => x.DependentValuePath);
            columnSeries.Properties[propertyName].SetValue("X");
            propertyName = Extensions.GetMemberName<ColumnSeries>(x => x.IndependentValuePath);
            columnSeries.Properties[propertyName].SetValue("Y");

            propertyName = Extensions.GetMemberName<Chart>(x => x.Series);
            item.Properties[propertyName].Collection.Add(columnSeries);
        }
    }
}

change history:

• 4/30/2009: published for Visual Studio 2008 SP1, Blend 3 Preview, Silverlight 3 Beta 1, and Silverlight 3 Toolkit March 2009 Release.
• 11/29/2009: updated for Visual Studio 2010 Beta 2.

I will keep the content up to date with latest version of Visual Studio, Blend & Silverlight.

Introduction

This is part of the series on design time implementation changes in Silverlight Toolkit March 2009 Release. This post illustrates the integration of Silverlight Toolkit with Visual Studio and Blend 3 after running Silverlight 3 Toolkit March 2009 Installer, and explains how it is done, so you can register your Silverlight controls with Visual Studio and Blend too.

Blend Integration

After installing Silverlight 3 Beta1 Tools, Blend 3 Preview, and Silverlight 3 Toolkit March 2009 (please see post Silverlight Toolkit Design Time Features: March 2009 Release Update, Silverlight 3 Development with Visual Studio 2008 and Blend 3 section for more information), create a Silverlight 3 Application from Blend 3, we can see that Silverlight Toolkit controls show up automatically in Asset Library:

User can drag and drop Toolkit controls from Asset Library to design or xaml view, and Blend will automatically add assembly reference, xmlns prefix and xaml code, very convenient:

Visual Studio Integration

Open the project in Visual Studio, we can see that Toolkit controls show up automatically in Visual Studio Toolbox, and user can drag and drop controls from Toolbox to design or xaml view as well:

Besides Toolbox, Toolkit assemblies also show up in Add Reference dialog:

and Choose Toolbox Items dialog:

Implementation

The integration with Visual Studio and Blend is done via registry. If you open “Silverlight 3 Toolkit March 2009.msi” in Orca, you can see the registration magic:

Register with Visual Studio

AssemblyFoldersEx

Registering with Visual Studio is mostly done via [HKLM|HKCU]\Software\Microsoft\Microsoft SDKs\Silverlight\v3.0\AssemblyFoldersEx. The References in Visual Studio page has very good explanation on AssemblyFoldersEx and reference resolution. It is a bit outdated, and is for .net instead of Silverlight. But it is mostly right for Silverlight too, and shows the root of the new toolbox registration mechanism with Visual Studio 2010. We’ve worked hard to rationalize the registration mechanism, consolidating and simplifying it across tools like msbuild, Visual Studio and Blend.

Take Silverlight 3 Toolkit October 2009 release as example:

c:\>reg query "HKEY_LOCAL_MACHINE\software\Microsoft\Microsoft sdks\Silverlight\v3.0\AssemblyFoldersEx\SilverlightToolkit0910" /s

HKEY_LOCAL_MACHINE\software\Microsoft\Microsoft sdks\Silverlight\v3.0\AssemblyFoldersEx\SilverlightToolkit0910
    (Default)    REG_SZ    C:\Program Files\Microsoft SDKs\Silverlight\v3.0\Toolkit\Oct09\Bin\

HKEY_LOCAL_MACHINE\software\Microsoft\Microsoft sdks\Silverlight\v3.0\AssemblyFoldersEx\SilverlightToolkit0910\Toolbox

1. AssemblyFolderBase indicates the target framework platform. Above registry path "\Software\Microsoft\Microsoft SDKs\Silverlight" indicates Silverlight SDK. Other possible values of AssemblyFolderBase:
   • "\Software\Microsoft\Microsoft SDKs\Windows"
   • "\Software\Microsoft\.NETFramework"
   • "\Software\Microsoft\.NETCompactFramework"
2. FrameworkVersion indicates the version of the target framework. “v3.0” in above example indicates this is for Silverlight 3. For Silverlight 4, use “v4.0”.
3. AssemblyFoldersSuffix describes the sub-target. “AssemblyFoldersEx” in above example tells build system how to resolve assembly references when path of the referenced assembly isn’t given. Other typical values of AssemblyFoldersSuffix:
   • “Install Path”: where Silverlight SDK is installed.
   • “ReferenceAssemblies”: where Silverlight SDK reference assemblies are installed.
4. PackageName indicates the name of the package registered, and its default value indicates where it is installed. In above example, “SilverlightToolkit0910” indicates this is Silverlight Toolkit October 2009 release, and its default value of “C:\Program Files\Microsoft SDKs\Silverlight\v3.0\Toolkit\Oct09\Bin\” indicates where it is installed. With this registration, Toolkit assemblies will show up in Add Reference dialog and Choose Toolbox Items dialog, and they can be references by other Silverlight projects without hint path.
5. Toolbox: the existence of Toolbox sub key tells Visual Studio 2010 to scan all assemblies under the install path of this package, and add all controls found to Visual Studio Toolbox, except those with ToolboxBrowsableAttribute(false) specified.

Toolbox Controls Installer (deprecated)

Jim Nakashima blogged about Toolbox Controls Installer for WPF controls in his post Have you seen the Toolbox Controls Installer? in 2007. Toolbox Controls Installer package is now part of Visual Studio 2008, but it doesn’t work for Silverlight because of a bug that is later fixed in Visual Studio 2010. Given the new AssemblyFoldersEx\Toolbox registration mechanism, there is no reason to use TCI with Visual Studio 2010 and later.

Register with Blend

Registering with Blend is via HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Expression\Blend\v3.0\Toolbox\Silverlight\v3.0:

c:\>reg query "hklm\software\Microsoft\expression\blend\3.0\toolbox\Silverlight\v3.0\SilverlightToolkit0910" /s

HKEY_LOCAL_MACHINE\software\Microsoft\expression\blend\3.0\toolbox\Silverlight\v3.0\SilverlightToolkit0910
    (Default)    REG_SZ    C:\Program Files\Microsoft SDKs\Silverlight\v3.0\Toolkit\Oct09\Bin\

Unni Ravindranathan’s blog post Blend 3 Extensibility has more information about this mechanism. You can kind of mapping this registration mechanism to above Visual Studio registration mechanism:

• AssemblyFolderBase is “\Software\Microsoft\Expression\Blend\v3.0\Toolbox\Silverlight”
• FrameworkVersion is “3.0”
• PackageName is “SilverlightToolkit0910”, and its default value “C:\Program Files\Microsoft SDKs\Silverlight\v3.0\Toolkit\Oct09\Bin\” indicates where it is installed.

One caveat: if the registered assemblies depend on other assemblies, those dependent assemblies need to be in the same directory as registered assemblies, or themselves registered under AssemblyFoldersEx as described above.

Conclusion

Registration with Visual Studio and Blend makes Silverlight Toolkit controls a lot easier to use for developers. We are constantly looking at improving the registration mechanism in hope to make it simple and consistent across designers (Visual Studio and Blend) and technologies (WPF and Silverlight). All feedbacks are welcome!

This is part of the series on design time implementation changes in Silverlight Toolkit March 2009 Release. This post illustrates the rich intellisense support for Silverlight Toolkit, and explains implementation workflow from xmldoc in source to infotip in intellisense xml file and design assemblies.

Intellisense

Silverlight Toolkit has rich Intellisense in code and XAML editors in both Visual Studio and Blend:

• Visual Studio Code Editor:
  
• Blend 3 Code Editor:
  
• Blend 3 XAML editor:
  

Visual Studio XAML editor has intellisense too, but no infotip:

 

Implementation

Code Editor Intellisense Infotip from XML Files

The intellisense infotips in code editors in Visual Studio and Blend come from intellisense xml files installed under Silverlight SDK and Toolkit directories:

Localization

Those intellisense xml files can be localized. If you install localized Visual Studio and localized Silverlight SDK, you will see localized infotips, which is a great help for those who don’t speak English. Below is the screenshot of Visual Studio running with Simplified Chinese language and simplified Chinese version of Silverlight Tools for Visual Studio SP1:
 

The Chinese infotip is from localized System.Windows.Controls.xml under zh-CHS sub directory:

C:\Program Files\Microsoft SDKs\Silverlight\v2.0\Libraries\Client>dir/s /b system.windows.controls.xml
C:\Program Files\Microsoft SDKs\Silverlight\v2.0\Libraries\Client\system.windows.controls.xml
C:\Program Files\Microsoft SDKs\Silverlight\v2.0\Libraries\Client\zh-CHS\system.windows.controls.xml

XAML Editor Intellisense Infotip from Design Assemblies

The intellisense infotips in Blend 3 XAML editor come from a different mechanism: they come from DescriptionAttribute implemented by design dlls installed under the Design subdirectory:

So it is the same as infotips in Blend Properties panel (please see Design Time Features in Silverlight Toolkit for more information):

xmldoc comment –> intellisense xml file –> DescriptionAttribute in design assembly

All those infotips come from xml documentation comments in source code, as seen from below screenshot:

1. we put xmldoc comments in source code
2. build generates .xml files from those xmldoc comments
3. the generated .xml files are embedded in design dlls (see Design Time Feature Implementation in Silverlight Toolkit for more information)
4. the control dlls, design dlls, and xml files are installed by SDK and Toolkit setup

Conclusion

This post describes the rich intellisense support of Silverlight Toolkit and its implementation workflow from xmldoc comments to intellisense xml files to design dlls. Good commenting pays!

This is part of the series on design time implementation changes in Silverlight Toolkit March 2009 Release. This post discusses how to enhance property editing experience for Silverlight controls using property value editor and type converter. I will start with describing the overall property editing architecture in WPF/Silverlight designer extensibility framework, then use examples in  Silverlight Toolkit March 2009 Release to demonstrate how it is done, and unique issues/tricks in Silverlight design time development.

Property Editing Architecture

Visually editing object properties is an important part of designers. Designers usually don’t know how to render properties of custom type (struct, class or interface), much less to provide an nice editing user interface. Control developers usually need to provide TypeConverter, PropertyValueEditor, or both, to provide rendering/editing UI and XAML serialization for properties of custom types.

The designer extensibility framework defines three types of property value editor: inline editor, extended editor, and dialog editor, each implemented by a class:

Editing UI of those editors are defined by DataTemplate. The property being edited is exposed to editor as DataContext of PropertyValue type. Editor UI usually bind to the underlying property being edited via one of the three properties of PropertyValue: Value, StringValue, or Collection.

PropertyValueEditor

PropertyValueEditor holds a single inline editor defined by InlineEditorTemplate property. Inline editor appears inside the properties window. Below is an simple example of InlineEditorTemplate that uses a TextBox to display and edit a property:

<DataTemplate x:Key="TextBoxEditor">
    <TextBox Text="{Binding Path=Value}"/>
</DataTemplate>

ExtendedPropertyValueEditor

<DataTemplate x:Key="inlineEditor">
    <Button Content="..." Command="{x:Static PropertyEditing:PropertyValueEditorCommands.ShowDialogEditor}"/>
</DataTemplate>
<DataTemplate x:Key="extendedEditor" xmlns:PropertyEditing="clr-namespace:Microsoft.Windows.Design.PropertyEditing;assembly=Microsoft.Windows.Design.Interaction">
    <Slider x:Name="slider" Value="{Binding Path=Value}" />
</DataTemplate>

DialogPropertyValueEditor

DialogPropertyValueEditor has two editors too: the inline editor inherited from PropertyValueEditor, and an additional dialog editor defined by DialogEditorTemplate property. The dialog editor is usually popped up by inline editor via PropertyValueEditorCommands.ShowDialogEditor command. Below is a simple example:

<DataTemplate x:Key="inlineEditor">
    <Button Content="..." Command="{x:Static PropertyEditing:PropertyValueEditorCommands.ShowDialogEditor}"/>
</DataTemplate>
<DataTemplate x:Key="dialogEditor" xmlns:PropertyEditing="clr-namespace:Microsoft.Windows.Design.PropertyEditing;assembly=Microsoft.Windows.Design">
    <Grid>
        <Grid.ColumnDefinitions>
            <ColumnDefinition Width="Auto" />
            <ColumnDefinition Width="*" />
        </Grid.ColumnDefinitions>
        <Grid.RowDefinitions>
            <RowDefinition Height="*"/>
            <RowDefinition Height="*"/>
        </Grid.RowDefinitions>
        <TextBlock Text="User Name:" VerticalAlignment="Center" HorizontalAlignment="Right" Margin="0,0,4,4"/>
        <TextBox Text="{Binding Path=Value}" VerticalAlignment="Center" HorizontalAlignment="Stretch" Margin="0,0,4,4" Grid.Column="1"/>
    </Grid>
</DataTemplate>

Implement Custom Property Editor

To implement a custom property editor for a Silverlight control:

• implement a custom property editor class
  • inherit from PropertyValueEditor, ExtendedPropertyValueEditor, or DialogPropertyValueEditor
  • set its editor template(s): InlineEditorTemplate, ExtendedEditorTemplate, and/or DialogEditorTemplate;
• Associate the custom property editor with a property of a Silverlight control via a AddCustomAttributes call, something like

  attributeTableBuilder.AddCustomAttributes(
      typeof(MyControl),
      "MyProperty",
      new PropertyValueEditor.CreateEditorAttribute(typeof(MyValueEditor)));

   

A correctly implemented property value editor must satisfy the following requirements:   
• The property value editor must be designed so that the inline editor and extended editor parts can be used independently.
• A property value editor must not store state. Property value editors are stateless, might be cached by a host implementation, and can be re-used across multiple property values.
• A property value editor must not assume that only one value editor part (view/inline/extended) control is active at a given time. For example, a dialog box could have the view part, inline part, and extended UI part active at the same time.
• A control implemented as part of a property value editor must not store state. A control implemented as part of a value editor should not assume that it will only be bound to one property value. Controls may be recycled to change different property values. Any information that is cached should be flushed if the data model is updated.
• A control implemented as part of a property value editor must not make any assumptions about the host or its parent controls. The only communication mechanisms that should be used are the PropertyValue data model, by way of the DataContext, and the standard set of commands.

You can read more about property editing architecture and designer extensibility framework on MSDN.

Reference Both WPF and Silverlight Assemblies

A design assembly is a .NET/WPF assembly loaded by Visual Studio or Blend, but it usually needs to reference Silverlight assemblies (at least the Silverlight control assembly it provides design time features for). This can create reference ambiguity for design assembly project: it sometimes needs to reference the same fully qualified type in both WPF and Silverlight, say System.Windows.FrameworkElement in both PresentationFramework.dll of WPF and System.Windows.dll of Silverlight. To avoid confusing Visual Studio, you can use extern alias to distinguish WPF and Silverlight references.

For example, see the screenshot below for Controls.DataVisualization.Toolkit.Design project in Silverlight 3 Toolkit in March 2009 Release:

• the project references both PresentationFramework and System.Windows, but System.Windows is under Silverlight alias, instead of the default global alias. The System.Windows reference under Silverlight alias is persisted in .csproj file as below:

  <Reference Include="System.Windows, Version=2.0.5.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e, processorArchitecture=MSIL">
    <SpecificVersion>False</SpecificVersion>
    <HintPath>..\Binaries\System.Windows.dll</HintPath>
    <Private>False</Private>
    <Aliases>Silverlight</Aliases>
  </Reference>

   

• in source code, we add

  extern alias Silverlight;
  using SSW = Silverlight::System.Windows;

   

  and reference Silverlight’s FrameworkElement via SSW::FrameworkElement.

TextBoxEditor

There is a inline editor TextBoxEditor in Controls.DataVisualization.Toolkit.Design project for displaying and editing Title property of object type for  [Area|Bar|Bubble|Column|Line|Pie|Scatter]Series and Chart controls, as shown below:

Text filled in Title field in Properties window on the right shows up automatically in XAML and design views in the middle.

The implementation of TextBoxEditor followed the steps outlined before:

• TextBoxEditor is a subclass of PropertyValueEditor. It sets InlineEditorTemplate in its default constructor. Here I use code instead of XAML to construct the DataTemplate, because somehow I can’t get xaml to build, and everything in XAML can be rewritten in C# anyway.
• It is associated with Chart.Title in ChartMetadata.cs (see Design Time Feature Implementation in Silverlight Toolkit for more information on *Metadata.cs files)

TextBoxEditor.cs:

// (c) Copyright Microsoft Corporation.
// This source is subject to the Microsoft Public License (Ms-PL).
// Please see http://go.microsoft.com/fwlink/?LinkID=131993 for details.
// All other rights reserved.

using System;
using Microsoft.Windows.Design.PropertyEditing;
using System.Windows;
using System.Windows.Data;

namespace System.Windows.Controls.DataVisualization.Design
{
    /// <summary>
    /// Simple TextBox inline editor.
    /// </summary>
    public partial class TextBoxEditor : PropertyValueEditor
    {
        /// <summary>
        /// Preserve the constructor prototype from PropertyValueEditor.
        /// </summary>
        /// <param name="inlineEditorTemplate">Inline editor template.</param>
        public TextBoxEditor(DataTemplate inlineEditorTemplate)
            : base(inlineEditorTemplate)
        { }

        /// <summary>
        /// Default constructor builds the default TextBox inline editor template.
        /// </summary>
        public TextBoxEditor()
        {
            FrameworkElementFactory textBox = new FrameworkElementFactory(typeof(TextBox));
            Binding binding = new Binding();
            binding.Path = new PropertyPath("Value");
            binding.Mode = BindingMode.TwoWay;
            textBox.SetBinding(TextBox.TextProperty, binding);

            DataTemplate dt = new DataTemplate();
            dt.VisualTree = textBox;

            InlineEditorTemplate = dt;
        }
    }
}

CultureInfoEditor

My colleague RJ wrote inline editor CultureInfoEditor for TimePicker.Culture property, because the default editing experience for CultureInfo in Blend leads to invalid XAML. Below screenshot shows the CultureInfoEditor uses a ComboBox to display all CultureInfo and generates right XAML.

CultureInfoEditor is a more complex example than TextBoxEditor, really shows how the underlying property is associated with editor via DataContext property.

CultureInfoEditor.cs:

// (c) Copyright Microsoft Corporation.
// This source is subject to the Microsoft Public License (Ms-PL).
// Please see http://go.microsoft.com/fwlink/?LinkID=131993 for details.
// All other rights reserved.

using System.Reflection;
using Microsoft.Windows.Design.PropertyEditing;
using System.Globalization;
using System.ComponentModel;

namespace System.Windows.Controls.Input.Design
{
    /// <summary>
    /// Editor for CultureInfo.
    /// </summary>
    /// <remarks>Currently does not support binding from xaml to the editor.</remarks>
    public class CultureInfoEditor : PropertyValueEditor
    {
        /// <summary>
        /// The ComboBox being used to edit the value.
        /// </summary>
        private ComboBox _owner;

        /// <summary>
        /// Preserve the constructor prototype from PropertyValueEditor.
        /// </summary>
        /// <param name="inlineEditorTemplate">Inline editor template.</param>
        public CultureInfoEditor(DataTemplate inlineEditorTemplate)
            : base(inlineEditorTemplate)
        { }

        /// <summary>
        /// Default constructor builds a ComboBox inline editor template.
        /// </summary>
        public CultureInfoEditor()
        {
            // not using databinding here because Silverlight does not support
            // the WPF CultureConverter that is used by Blend.
            FrameworkElementFactory comboBox = new FrameworkElementFactory(typeof(ComboBox));
            comboBox.AddHandler(
                ComboBox.LoadedEvent,
                new RoutedEventHandler(
                    (sender, e) =>
                    {
                        _owner = (ComboBox) sender;
                        _owner.SelectionChanged += EditorSelectionChanged;
                        INotifyPropertyChanged data = _owner.DataContext as INotifyPropertyChanged;
                        if (data != null)
                        {
                            data.PropertyChanged += DatacontextPropertyChanged;
                        }
                        _owner.DataContextChanged += CultureDatacontextChanged;
                    }));

            comboBox.SetValue(ComboBox.IsEditableProperty, false);
            comboBox.SetValue(ComboBox.DisplayMemberPathProperty, "DisplayName");
            comboBox.SetValue(ComboBox.ItemsSourceProperty, CultureInfo.GetCultures(CultureTypes.SpecificCultures));
            DataTemplate dt = new DataTemplate();
            dt.VisualTree = comboBox;

            InlineEditorTemplate = dt;
        }

        /// <summary>
        /// Handles the SelectionChanged event of the owner control.
        /// </summary>
        /// <param name="sender">The source of the event.</param>
        /// <param name="e">The <see cref="System.Windows.Controls.SelectionChangedEventArgs"/> 
        /// instance containing the event data.</param>
        private void EditorSelectionChanged(object sender, SelectionChangedEventArgs e)
        {
            // serialize with name.
                object DataContext = _owner.DataContext;
                DataContext
                    .GetType()
                    .GetProperty("Value", BindingFlags.Public | BindingFlags.Instance | BindingFlags.GetProperty)
                    .SetValue(DataContext, ((CultureInfo)_owner.SelectedItem).Name, new object[] { });
        }

        /// <summary>
        /// Handles the PropertyChanged event of the context object.
        /// </summary>
        /// <param name="sender">The source of the event.</param>
        /// <param name="e">The <see cref="System.ComponentModel.PropertyChangedEventArgs"/> instance containing the event data.</param>
        private void DatacontextPropertyChanged(object sender, PropertyChangedEventArgs e)
        {
            // deserialize from name.
            if (e.PropertyName == "Value")
            {
                object value = sender
                    .GetType()
                    .GetProperty("Value", BindingFlags.Public | BindingFlags.Instance | BindingFlags.GetProperty)
                    .GetValue(sender, new object[] { });

                if (value != null)
                {
                    if (value is string)
                    {
                        CultureInfo setCulture = new CultureInfo(value.ToString());
                        _owner.SelectedItem = setCulture;
                    }
                }
            }
        }

        /// <summary>
        /// Called when the context is changed.
        /// </summary>
        /// <param name="sender">The sender.</param>
        /// <param name="e">The <see cref="System.Windows.DependencyPropertyChangedEventArgs"/> instance containing the event data.</param>
        private void CultureDatacontextChanged(object sender, DependencyPropertyChangedEventArgs e)
        {
            INotifyPropertyChanged old = e.OldValue as INotifyPropertyChanged;
            if (old != null)
            {
                old.PropertyChanged -= DatacontextPropertyChanged;
            }
            INotifyPropertyChanged newDataContext = e.NewValue as INotifyPropertyChanged;
            if (newDataContext != null)
            {
                newDataContext.PropertyChanged += DatacontextPropertyChanged;
            }
        }
    }
}

ExpandableObjectConverter

As discussed at the beginning, besides custom property value editors, sometimes you can use appropriate type converter to provide good editing experience and XAML serialization. One example is ColumnSeries.DependentRangeAxis: it is of IRangeAxis type, Blend doesn’t know how to edit it, so it shows DependentRangeAxis as read only in Properties Panel. By associating ExpandableObjectConverter to ColumnSeries.DependentRangeAxis:

b.AddCustomAttributes(
    Extensions.GetMemberName<ColumnSeries>(x => x.DependentRangeAxis),
    new TypeConverterAttribute(typeof(ExpandableObjectConverter)));
b.AddCustomAttributes(
    Extensions.GetMemberName<ColumnSeries>(x => x.IndependentAxis),
    new TypeConverterAttribute(typeof(ExpandableObjectConverter)));

Blend displays a New button next to this property in Properties Panel; when clicked, it pops up the Select Object dialog, filtered with the property’s type IRangeAxis:

Conclusion

Blend and Silverlight together allow designers to create amazing UI against real controls directly, so it is very important that control developers take designer experience as part of overall control design and implementation. Having a custom property editor that provides nice editing UI and generates correct XAML is an important part of the designer experience. Hopefully this post helps you understand how to create custom property editors. Thanks!

This is part of the series on design time implementation changes in Silverlight Toolkit March 2009 Release. This post focuses on the breaking changes in designer extensibility framework introduced in Silverlight 3/Blend 3/Visual Studio 2010, and how to develop Silverlight design time to support all designers: Visual Studio 2008/Blend 2, and Visual Studio 2010/Blend 3.

Silverlight 2 Design Time for Visual Studio 2008 and Blend 2

Visual Studio and Blend share the same designer extensibility framework, and use it for both WPF and Silverlight. WPF Designer Extensibility on MSDN is probably the best reference available for the designer extensibility framework. The December 2008 Release of Silverlight Toolkit is based on Silverlight 2 (aka SL2), and has designer support for Visual Studio 2008 (aka VS9) and Blend 2. It is a good real world example in demonstrating how to develop Silverlight 2 design time features for VS9 and Blend 2. My blog post Design Time Feature Implementation in Silverlight Toolkit explains in detail how it is done, and the implementation framework readers can use in their own design time implementation.

To recap, the Silverlight 2 design time framework for Visual Studio 2008 and Blend 2 in a nutshell:

• MWD: the design time extensibility framework is exposed through a set of assemblies, most notably Microsoft.Windows.Design.dll, Microsoft.Windows.Design.Extensibility.dll, and Microsoft.Windows.Design.Interaction.dll. Collectively those assemblies are called MWD. They are installed under %DevEnvDir%\PublicAssemblies (C:\Program Files\Microsoft Visual Studio 9.0\Common7\IDE\PublicAssemblies in 32bit OS, or  C:\Program Files (x86)\Microsoft Visual Studio 9.0\Common7\IDE\PublicAssemblies in 64bit OS). They are also GAC-ed. Most design time projects need to reference those MWD dlls. Visual Studio 2008 and Blend 2 use MWD version 3.5.
  
• Naming Convention: Visual Studio and Blend load design time assemblies using a naming convention: for control assembly Foo.dll, VS and Blend will find its design time assemblies with the name Foo.Design.dll, Foo.VisualStudio.Design.dll, and Foo.Expression.Design.dll, in the same directory where Foo.dll is, or the Design sub directory. Visual Studio will load Foo.Design.dll and Foo.VisualStudio.Design.dll, while Blend will load Foo.Design.dll and Foo.Expression.Design.dll. So it is advised to put design time features shared across all designers in .Design.dll, and put Visual Studio and Blend specific design time features in .VisualStudio.Design.dll and .Expression.Design.dll respectively.
• Entry Point: when Visual Studio or Blend loads a design time assembly, it uses reflection to find all classes that implement IRegisterMetadata, and calls its only method Register. Silverlight Toolkit December 2008 Release has a design time implementation framework detailed in previous blog post Design Time Feature Implementation in Silverlight Toolkit.

Below screenshots of Silverlight.Controls.Design.sln in Silverlight 2 Toolkit source in March 2009 Release demonstrates implementation of SL2 design time for VS9 and Blend 2 discussed above:

What Changed In Silverlight 3, Blend 3 and Visual Studio 2010

As stated in WPF Designer Extensibility Architecture on MSDN:

The WPF Designer supports the full extensibility framework. Expression Blend supports only property editors, metadata loading, and licensing. Blend does not support menu actions and adorners.

Blend 2 has above limited support for Silverlight design time too, but Visual Studio 2008 has little support for Silverlight design time (just icons, metadata loading for few attributes like ToolboxBrowsableAttribute): it is more a viewer than a designer. To have WPF parity for Silverlight design time support, Blend 3 and Visual Studio 2010 (aka VS10) have to introduce breaking changes to the designer extensibility framework (i.e. MWD), most notably:

• MWD: most of the designer extensibility framework API stay the same, but their physical packaging changes: Microsoft.Windows.Design.dll is gone, and the version of all MWD assemblies changes from 3.5 to 4.0. Before Visual Studio 2010 Beta1, the only way to get the new MWD is via Blend 3 Preview, and its version is 3.7 instead of 4.0 for now:
  
• Entry Point: instead of reflect through IRegisterMetadata implementations, Blend 3 and Visual Studio 2010 use a new assembly attribute ProvideMetadataAttribute, and the metadataProviderType must implement IProvideAttributeTable:
  
• Naming Convention: because of the breaking changes like MWD version and entry point, existing design time assemblies developed against 3.5 MWD will not load in Blend 3 and Visual Studio 2010, you have to write new design time against the new 4.0 MWD for Blend 3 and Visual Studio 2010. While this is OK for Blend (since you can only use Blend 3 with Silverlight 3 and Blend 2 with Silverlight 2), this creates a challenge for Visual Studio, since you can use Visual Studio 2008 for Silverlight 3 development, as well as Visual Studio 2010 for Silverlight 2 development.

Below table lists all supported scenarios and which version of MWD is used to load design time assemblies:

We can’t build one design time assembly against two incompatible MWDs, so we have to create two separate design time assemblies, one against each MWD. Design time assemblies are loaded by name, and we can’t have two assemblies with the same name in the same location, so the design time assembly loading mechanism (i.e., the naming convention) has to change, to allow multiple versions of the same design time assembly coexist.

While waiting for the new naming convention to come out with Blend 3 and Visual Studio 2010 RTM, we can do something clever now to support both VS9 and VS10. Remember current naming convention allows Visual Studio and Blend each to load two design assemblies:

so we can build the two assemblies against different versions of MWD:

• For Silverlight 3, we can have the shared .Design.dll build against MWD 4.0, so it can be loaded by both VS10 and Blend 3. We then have .VisualStudio.Design.dll build against MWD 3.5 and duplicate everything from shared .Design.dll, so it can be loaded by VS9. There is one minor issue though: we don’t have a place to put Visual Studio specific design time features for VS10, like using ToolboxBrowsableAttribute(false) to hide some controls from the increasingly crowded Visual Studio toolbox, since VS10 can’t load the .VisualStudio.Design.dll build against MWD 3.5. This will be solved with the new naming convention once Visual Studio 2010 RTM.

• For Silverlight 2, follow the same approach: have the shared .Design.dll build against MWD 4.0, but have both .VisualStudio.Design.dll and .Expression.Design.dll build against MWD 3.5 and duplicate everything in shared .Design.dll. This way, both VS9 and Blend 2 will work just fine, but with the  same issue that there is no place to put Visual Studio specific features for VS10. Again, that will be solved with the new naming convention in VS10.

Design Time Feature Implementation in Silverlight 3 Toolkit

MWD

The design projects in Silverlight 3 Toolkit in March 2009 Release followed above mentioned scheme to support both Visual Studio 2008 and Visual Studio 2010, as well as Blend 3.

Download the March 2009 Release, unzip the source code, load Silverlight.Controls.Design.sln into Visual Studio 2008. Use the simpler Control.Input.Design project as example:

• Design projects for VS9/Blend3 need to reference the new 4.0 MWD. Here we use pre-build event to invoke CopySystemWindows.bat to locate Blend 3 and copy the two  MWD dlls to Binaries directory.
• Please note the minor changes to CopySystemWindows.bat file: we need to quote “%THIS_DIR%\Binaries\Blend3” (lines in yellow) to handle cases where there is a space in the path to the directory the source code is unzipped to.

If you don’t like the fragile CopySystemWindows.bat file or using build events, you can set Reference Paths to help Visual Studio find where the new MWD is, as shown below. The only caveat is that you need specify both %programfiles% and %programfiles(x86)% to make it build on both x86 and x64 machines.

The reference paths setting is persisted into the .csproj.user file:

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <ReferencePath>c:\Program Files\Microsoft Expression\Blend 3 Preview\;c:\Program Files (x86)\Microsoft Expression\Blend 3 Preview\</ReferencePath>
  </PropertyGroup>
</Project>

Metadata.cs

I use the same implementation framework as described in Design Time Feature Implementation in Silverlight Toolkit, with some minor changes:

• I moved links to shared files Extensions.cs and MetadataBase.cs from Controls.Design.Common folder to under a solution folder with the same name;
• Metadata.cs in .Design and .Expression.Design projects use the new entry point: use ProvideMetadata assembly attribute, and implement IProvideAttributeTable interface;
• add note that everything in AddAttributes() method needs to be duplicated in corresponding .VisualStudio.Design project.

The .VisualStudio.Design projects still use the old IRegisterMetadata interface in MWD 3.5, but:

• under Controls.Design folder are links to all *Metadata.cs files in corresponding .Design project;
• AddAttributes() method duplicates the content of AddAttributes() method in corresponding .Design project.

Conclusion

While the breaking changes in MWD may cause some inconvenience, it is necessary to implement as rich a design time experience for Silverlight as for WPF. This post describes a way to handle the breaking changes and still support all existing designers: Visual Studio 2008, Blend 2, and Blend 3. Once Visual Studio 2010 is publicly available, I will blog about the new naming convention, and how Toolkit design time work in Visual Studio 2010. Stay tuned!

12/5/2009: Update for VS2010 Beta2

To solve above problem of supporting both Visual Studio 2008/Blend2 and Visual Studio 2010/Blend3, which use incompatible versions of MWDs (v3.5 vs.. v4.0), the naming convention for design time assemblies is enhanced from VS2010 Beta2 and Blend 3:

for a runtime assembly Foo.dll, the shared design time assembly is named Foo.Design*.dll, the Visual Studio specific design time assembly is named Foo.VisualStudio.Design*.dll, and the Blend specific design time assembly is named Foo.Expression.Design*.dll, where * can be zero or more valid characters for file names. When a designer (like Visual Studio or Blend) tries to load a design time assembly and several fit the naming convention, zero or one will be loaded:

• If the MWD version referenced by the design-time assembly has a different major version number than the designer’s MWD version, then the design-time assembly will not load and is bypassed.
• If more than one design-time assembly is compatible with the designer’s MWD version, the Designer loads the one compiled against the highest MWD version that is less than or equal to the designer’s MWD version.

Silverlight 3 SDK GDR 2 (also installed by VS2010 automatically) and Silverlight 3 Toolkit October 2009 Release use the new naming convention to support both VS2008 and VS2010. Take System.Windows.Controls.dll for example, System.Windows.Controls.VisualStudio.Design.dll is built against MWD 3.5 and is used by VS2008, which uses the old naming convention; a new System.Windows.Controls.Toolkit.VisualStudio.Design.4.0.dll built against MWD 4.0 is added for VS2010, which understands the new naming convention.  Please see Silverlight Design Time Assemblies for more information.

The March 2009 Release of Silverlight Toolkit has lots of new features and improvements. Among them, updates for design time features:

• a new msi based installer that provides tight integration with Visual Studio and Blend out of box, thus making Silverlight development with the Toolkit much easier;
• support both Silverlight 2 development with Visual Studio 2008 and Blend 2, and Silverlight 3 development with Visual Studio 2008 and Blend 3;
• add design time features for the six new controls (Accordion, DomainUpDown, LayoutTransformer, TimePicker, TimeUpDown, TransitioningContentControl);
• leverage the new design time extensibility framework in Blend 3 (and soon in Visual Studio 2010) and improve design time features for existing controls, like default intializers, AlternateContentPropertyAttribute, and custom editors, to provide a much better design experience, especially in Blend 3.

This post is an update for my prior post Design Time Features in Silverlight Toolkit.

Silverlight 2 Development with Visual Studio 2008 and Blend 2

Setup

• First, follow step 1 and 2 on http://silverlight.net/GetStarted to install Silverlight 2 and Blend 2:

• Then follow step 4 to Silverlight Toolkit CodePlex page, click “Download the latest release” link:

• Click the “Silverlight 2 Toolkit March 2009 Installer” link, and run the msi: (You can also save the msi to your computer and run it later)

After the installer finishes, you will see Silverlight 2 Toolkit installed on your computer:

Please note:

• there is a namespace (both CLR and xmlns prefix) and assembly name change from Microsoft.Windows.Controls in previous releases to System.Windows.Controls in this release. Please see Shawn Burke’s post Silverlight Toolkit March 2009 Release for a good explanation for the change and its implications for development with Silverlight Toolkit.
• besides the existing four toolkit assemblies (Controls, Controls.Input, Control.DataVisualization, and Controls.Theming) in previous releases, there is a new assembly added in this release: Controls.Layout, which contained Accordion, LayoutTransfer, and TransitioningContentControls.
• we still follow the same convention for design time assemblies: there are three design time assemblies for each run time assembly (.design, .expression.design, and .visualstudio.design), and all design time assemblies reside in the Design subfolder.

There is also a new Microsoft Silverlight 2 Toolkit March 2009 Start Menu item group to provide easy access to all Toolkit related information, like docs, samples, source code on local computer, and Silverlight Toolkit forums and CodePlex page on web:

Walkthrough

Let’s use a walkthrough on how to create a Chart control in Blend to demonstrate the design time features for Silverlight Toolkit:

• Create a new Silverlight 2 Application project in Blend:

• Add reference to the Toolkit assemblies: (Here I add all Toolkit assemblies, but only System.Windows.Controls.DataVisualization.Toolkit.dll is needed for this walkthrough)

• open Asset Library, click Custom Controls tab, and double click the Chart control:

• Add a Chart control to the design surface, set its Title property under Data Visualization category in Properties Panel:

• Click the New button next to DataContext property under Common Properties, select PointCollection from the Select Object dialog, and then click OK:

• In XAML editor, replace the generated XAML “<PointCollection />” to be like those highlighted in below screenshot, to provide some data for the Chart control to display:

• Click the … button next to “Series (Collection)” property under Common Properties category, click “Add another item” button in the Series Collection Editor dialog, select ColumnSeries in Select Object dialog, and then click OK:

• Back to the Series Collection Editor dialog, set properties for the newly created ColumnSeries in the right Properties pane:
  • Set DependeptValuePath to X and IndependentValuePath to Y, both in Common Properties category
    
  • Click the rectangle to the right of ItemsSource property, select Data Binding… from the popped up context menu:
    
  • Select the only item, PointCollection (Array) item, in Fields listbox in the Create Data Binding dialog, then click the Finish button:
    
  • Back to the Series Collection Editor dialog again, notice the ItemsSource property is now surrounded with a yellow rectangle, indicating it now has a changed data binding value. Click OK to close the Series Collection Editor dialog:
    

• We are back to Blend main window, and voila, we have a Chart control rendered nicely in the design view:

We can hit F5 to build and run the project from Blend, or open the project in Visual Studio to continue editing the xaml and code. Notice in below screenshot that the Visual Studio toolbox is auto populated with Toolkit controls:

Silverlight 3 Development with Visual Studio 2008 and Blend 3

Setup

Before you start, please read the Important developer notes on http://silverlight.net/getstarted/silverlight3/default.aspx#tools carefully (in below screenshot too).

• First, follow the first three steps on http://silverlight.net/getstarted/silverlight3/default.aspx#tools page to install Silverlight 3 Beta Tools, SDK (some of previous Toolkit controls, like DockPanel, WrapPanel, Expander, Viewbox, HeaderedContentControl, HeaderedItemsControl, TreeView, AutoCompleteBox etc, and their design time assemblies, have moved to SDK in Silverlight 3), and Blend 3 Preview:
• Then, follow the fourth step to Silverlight Toolkit CodePlex Project site, click Download the latest release link, then click and run the Silverlight 3 Toolkit March 2009 Installer:

After the installer finishes, you will see Silverlight 3 Beta SDK and Toolkit installed on your computer:

• SDK:

• Toolkit:

And the Microsoft Silverlight 3 Toolkit March 2009 start menu item group for easy access to all Toolkit information:

Walkthrough

Now let’s do the same create a Chart control walkthrough, but this time with Blend 3:

• Start Microsoft Expression Blend 3 Preview from Start menu, create a new Silverlight 3 Application + Website project:

• Click the Asset Library, notice the Controls tab is pre-populated with Silverlight 3 runtime and SDK controls, including those used to be in Toolkit, like DockPanel, Expander, TreeView etc. Blend 3 populates Asset Library asynchronously, so you may notice a few seconds delay before the Controls tab is fully populated.

• Click the Custom Controls tab, notice it is pre-populated with Toolkit controls:

• Double click the Chart control, click and drag on the design surface, and voila, a Chart controls is created, initialized with some sample data, and nicely rendered. We had to go through a lot manual steps in Blend 2 to create the same result:

Please note in above screenshot:

• in the projects panel on the right, reference to System.Windows.Controls.DavaVisualization.Toolkit.dll is automatically added;
• in the xaml editor, the xmlns:chartingToolkit definition is automatically added
• also notice a few Blend 3 new features, like custom icon for Chart control (in both Object and Timeline pane and Properties pane), default initializer that generates the initial xaml for the Chart control.

Since the Chart control is so easily created, let’s do a bit more in Blend 3 walkthrough.

• Click Properties Tab on the right, and expand the Chart control in Objects and Timeline pane on the left:

Please note in above screenshot:

• In Properties Panel, the little white dots to the right highlight the properties initialized by Chart control’s default initializer;
• In Objects and Timeline Panel, there are LegendItems and Axes properties under Chart object, and IndependentAxis and DependentRangeAxis properties under ColumnSeries object. Those are called alternate content properties. Displaying them in the object hierarchy allows easy access to those properties at design time. For example, we can drag and drop a LinearAxis to the Axes property:

So comparing the same create a Chart control walkthrough in Blend 3 and Blend 2, we can see that Blend 3 a much better designer, and our design time assemblies for Blend 3 have leveraged many of the new design time extensibility capabilities, like default initializer and alternate content property, to greatly improve the design experience for Toolkit controls.

Now open the project in Visual Studio:

Please notice that:

• The toolbox on the left is pre-populated with SDK and Toolkit controls.
• The output windows at bottom right displays an error message about failed to load design assembly. Ignore it safely.

Design Experience in Visual Studio 2008 (Both Silverlight 2 and 3)

Toolkit design experience in Visual Studio is pretty much the same for both Silverlight 2 and Silverlight 3, so we can continue the following from either of above the two walkthroughs. For convenience sake, we will continue from the Silverlight 3 walkthrough immediately above.

Now drag and drop the Accordion control from toolbox to the XAML editor:

We can see that:

• In XAML editor
  • xmlns:layoutToolkit="clr-namespace:System.Windows.Controls;assembly=System.Windows.Controls.Layout.Toolkit"  is automatically added
  • <layoutToolkit:Accordion></layoutToolkit:Accordion> is automatically added
• In Solution Explorer
  • references to System.Windows.Controls.Layout.Toolkit assembly, and the two assemblies it depends on, System.windows.Controls.Toolkit in Toolkit and System.Windows.Controls in SDK, are added automatically to the project

Now drag and drop a few controls from toolbox to XAML editor.

Please notice in above screenshot that:

• in XAML editor
  • we can see that we dragged and dropped Calendar, AutoCompleteBox and NumericUpdown to the Accordion
  • appropriate xmlns definitions and xaml code are added automatically
• In the Preview window
  • XAML code is properly rendered as we edit in XAML editor
• In Code editor
  • notice the intellisense and infotip
  • Safely ignore the errors in Errors Window as we type in XAML or code editors before we finish the statement
• In Solution Explorer:
  • references to needed assemblies are automatically added

Hit F5, and it builds and runs fine:

Credits

I certainly hope you are excited about the design experience improvements, since I implemented most of it Jeff Wilcox implemented the installer, and Justin Angel wrote the spec for both the design time experience and installer. Many of my other colleagues contributed to the design experience too, especially RJ Boeke, Jafar Husain, and David Anson. Many thanks to the folks in Blend and Cider teams, particularly Unni Ravindranathan, Gary Linscott, Peter Blois; Brian Pepin, and Eric Fisk. Without them, none of the design experience improvements would be possible. And to Shawn Burke, for his support and emphasis on design time features, and deep involvement in solving key hard technical problems.

I will write a follow up post on design time implementation updates in March 2009 release. Stay tuned!

• first published on 1/21/2008 for Silverlight 2/VS2008/Toolkit December 2008 Release.
• updated on 12/5/2009 for Silverlight 4/VS2010/Blend3/Toolkit November 2009 Release.

Controls in Silverlight runtime (ex. system.windows.dll) and SDK (ex. system.windows.controls.dll) have nice toolbox icons in Visual Studio and Blend. December 2008 release of Silverlight Toolkit added that for Toolkit controls too, as described in my previous post Design Time Features in Silverlight Toolkit:

This post explains how it is done in Silverlight 2 SDK, and in December 2008 release of the Silverlight Toolkit.

Control Icons in Run Time Assembly

The December 2008 Release of Silverlight Toolkit demonstrated how to embed toolbox icons for controls without using a design time assembly.

Open Silverlight.Controls.sln in Visual Studio (see previous post Design Time Feature Implementation in Silverlight Toolkit for more information on how to download the toolkit source):

Or open Controls.csproj in notepad:

<ItemGroup>
  <EmbeddedResource Include="Microsoft.Windows.Controls.AutoCompleteBox.Icon.png" />
  <EmbeddedResource Include="Microsoft.Windows.Controls.DockPanel.Icon.png" />
  <EmbeddedResource Include="Microsoft.Windows.Controls.Expander.Icon.png" />
  <EmbeddedResource Include="Microsoft.Windows.Controls.Label.Icon.png" />
  <EmbeddedResource Include="Microsoft.Windows.Controls.TreeView.Icon.png" />
  <EmbeddedResource Include="Microsoft.Windows.Controls.Viewbox.Icon.png" />
</ItemGroup>

Or open Microsoft.Windows.Controls.dll in reflector:

All three show that the custom toolbox icons are embedded resources in the run time assembly Microsoft.Windows.Controls.dll, with a particular naming convention. Take above Microsoft.Windows.Controls.Microsoft.Windows.AutoCompleteBox.Icon.png as an example:

• The first Microsoft.Windows.Controls is the root namespace, specified in controls.csproj file with line: <RootNamespace>System.Windows.Controls</RootNamespace>
• The next Microsoft.Windows.Controls.AutoCompleteBox is the fully qualified name of AutoCompleteBox class, including namespace but not assembly.
• The rest of the name, Icon.png, specify the icon resource type, as will be explained more later.

Control Icons in Design Time Assembly

The Silverlight 2 SDK demonstrated the approach of embedding control icons in design time assembly.

Open System.Windows.Controls.Design.dll in reflector (it is installed under %ProgramFiles%\Microsoft SDKs\Silverlight\v2.0\Libraries\Client):

Take above Controls.Design.Icons.Calendar.bmp as an example:

• Controls.Design is the root namespace, specified in its csproj file with line <RootNamespace>Controls.Design</RootNamespace>
• Icons is the subfolder where the Calendar.bmp file is in source tree
• Calendar.bmp is the name of the icon resource file in source tree

Control Icon Resource Naming Convention

So from above two examples, we can see that custom toolbox icons for controls are embedded resources in either run time assembly (so you don’t need to ship a design time assembly), or design time assembly (so you have flexibility to change icons, like localize it for a different culture, without touching the run time assembly). The tools (Visual Studio 2008 SP1 for now) try to find the icons based on a special naming convention:

1. Search for resources whose file name without extension matches the type name of the control, including the namespace, with a “[.icon*].{XAML | BMP| PNG | GIF | JPG | JPEG}” .
   1. Note that subdirectories affect the namespace in which embedded resources are found. For example, the Toolkit icons are put under a Microsoft.Windows.Controls subfolder, to avoid putting this long string in all icon file names; while the SDK put all icons under a Icons subfolder.
   2. Supported extensions and file types are: XAML, BMP, GIF, JPG, JPEG and PNG
   3. Recommended image size for Bitmap based file formats is 64×64.
   4. The [.icon*] in the naming convention is optional and allows you to specify multiple sizes of the image that is used as the icon. The match follows the following algorithm:
      1. Vector XAML
      2. If there is an exact match on size (both dimensions) use it
      3. Use the closest match based on size and aspect ratio
   5. If a given resource file is not valid XAML or a valid image file, the next match will be used until one is found.
2. If an image is not found in the same namespace as the control, a loose match based on the type name alone will be searched for against all of the resources, as in the SDK case.
3. Different hosts use different image sizes for their toolbox icon.
   1. Blend uses 24×24 for their large size and 12×12 for their small size (I don’t think this is working in Blend 2 SP1) .
   2. Cider (Visual Studio) uses 16×16 bmp files.

The blog post Specifying a Toolbox Icon for a Control in WPF Designer describes the naming convention in more details.

Update for Blend3 & VS2010

Since this post was first published on 1/21/2008, we’ve made two key improvements regarding control icons:

• Blend 3 shows icons for controls too: big icons (24×24) in Asset Library, and small icons (12×12) in Objects and Timeline.  See Silverlight Design Time: Toolkit July 2009 Release Update for more information.
• You can register your controls (and their associated icons) with Blend 3 and Visual Studio 2010. See Register Silverlight Controls with Visual Studio and Blend for more information.
• The naming convention for icon resource is revised together with the naming convention for design time assemblies. See Silverlight Design Time Assemblies for more information on the enhanced naming convention for design time assemblies. Please note that the search for icon resource is in reverse order of the loading order of design time metadata, i.e., Blend will search for embedded icon resource for a control with above icon resource naming convention in *.Expression.Design*.dll first; only if it fails will Blend search the shared *.Design*.dll second; and only if if fails again will it search the corresponding runtime dll for the embedded icon resource; and if all have failed, Blend will display the default icon for the control. Visual Studio 2010 does it in similar way, but searches *.VisualStudio.Design*.dll first.
• Blend and Visual Studio now support more icon format, and will scale the icon if the desired sized resource (24×24 and 12×12 for Blend, and 16×16 for VS) isn’t found.

Silverlight Toolkit use following naming conventions for embedding icon resources:

• use full names (namespace+type, ex. System.Windows.Controls.Calendar) instead of just type names (ex. Calendar) to avoid ambiguity.
• put icons for Blend in shared .design.dll, and icons for Visual Studio toolbox in .VisualStudio.Design*.dlls. This way, VS2010 can display the right toolbox icon if one exists in .VisualStudio.Design*.dll; if not, VS2010 can load the icon for Blend, scale it to 16×16, and display it in toolbox.
• put icon resource in runtime dll only as last resort (ex, to avoid shipping a design time assembly with only icon resource).

You can see the control icon resource naming convention in Silverlight Toolkit source code: