As I do some app development for Windows 8 I wanted to share my thoughts around localization and what it really means to me to provide a ‘world-ready’ application.  The three areas of focus are 1) how the platforms support a localized app, 2) what technical tools you have to automate localization 3) getting culture-correct localization and 4) testing your localized app.

Platform support for localization

The first thing you have to understand is how the platform you are targeting enables support for your app to easily be localized.  This may be in how you organize your content, how you name certain things, and how you write code.  For most platforms there is a pretty predictable method of doing this.  I would argue not all platforms make this extremely intuitive, but also state that inferring how (and what) you want to localize your app isn’t something a platform can predict well for every app.  It is important for the app developer to plan for a global market and fully understand the models before writing a line of code to understand how to make the app localized more easily later in the process.

For Windows 8, a new resource model is introduced for WinRT that is common across the entire platform regardless of the UI framework choice.  The areas you should understand are Windows.ApplicationModel.Resources and Windows.ApplicationModel.Resources.Core.  These two areas are where most Windows 8 developers will spend most of their time with regard to localization of UI strings (and other content).  For most, the GetString() method is probably where you’ll spend your time when using code.  String values are indexed during the build process of your application.  Your strings will either reside in a RESJSON (for HTML/JS) or RESW (for XAML) file.  Both of these are essentially name/value collections for your strings.  An example of the process of naming and managing your string resources can be found here: How to manage string resources.

NOTE: Yes the Consumer Preview version of that documentation shows only Javascript right now, but will be updated.  The naming conventions are the same.

In XAML we created a new way to do XAML UI localization in your markup, by moving some functionality into the platform for you.  Previously in platforms like Silverlight people used techniques like data binding to accomplish the mapping from the RESX-generated class to the UI.  Because the indexing of the string resources changed a bit (i.e., currently no strongly-typed resource class representation), we wanted to have the platform do some more heavy lifting for you.  We already load the index file (resources.pri) automatically during load of the app, so we’re aware of the resources and all the context the app may have (i.e., what locale, screen resolution, etc.).  Because of this we enabled a markup mechanism in XAML for you to provide easy string localization.  Let’s use a simple example of a TextBlock that you might have a static string:

   1: <TextBlock x:Uid="MyTextBlock" FontSize="24.667" Text="Design Placeholder" />

Notice the x:Uid value here.  This now maps back to the key in your RESW file.  Anything with that starting key will have properties merged into it.  So we can have a key in our RESW for “Text” using the key name MyTextBlock.Text with a value of “Hello World” and the runtime will do the replacement for you.  This applies to properties other than text (i.e. width) as well as attached properties.  While we think this is a great new method, it may not work for everyone’s situations and you still have control over retrieving strings using the Windows.ApplicationModel.Resources WinRT APIs.  You can read more about this method with some examples here: QuickStart: Make your Metro style app world ready and an SDK Sample here: Application Resources.

Tools to help with localizing content

Once you have understood what your platform provides and you have taken the effort to prepare your app for easy localization, the next step is to actually use tools/process to perform the localization.  I’ve come across a few tools that I think are helpful for XAML developers who are ‘small shops’ and don’t have an existing process for app localization.

The easiest thing for a developer to do is to use machine translation using automated services.  There are a few tools out there that I think can be helpful for this method.  It is important to note we are talking about machine translation here…I will get to that point later on in the post.

RESX Translator with Bing

Since the RESW format is identical with RESW (restriction is that RESW only supports string values currently), you can use a lot of existing RESX tools.  There is a RESX Translator with Bing project on CodePlex that was done by Microsoft UK Consulting Services.  This allows you to select a file and source language and translate to any language that Microsoft Translator supports. 

Since the current project supports (and only loads) .resx files, I had submitted some patch files to quickly make it support the .resw file extension.  The contributor hasn’t accepted these patches, but you can find them on the patches section for the project.

Multilingual App Toolkit

Released with the Visual Studio 11 Beta, the Multilingual App Toolkit from Microsoft provides an integrated method for generating resources for your app.  One of the benefits of this app is that it produces some standards-based files that are used to send to localizers and can be used in other tools.  This includes the TPX and XLIFF file formats.  Once installed the tool is integrated within visual studio and your flow would be something like the following.

First you’d have your app and an initial RESW file containing your default language (in my case en-US) resources.  Once I have that I can right-click on the project and choose Add translation languages and when doing so, launches:

which I can select the languages I would prefer.  Notice the translator icon next to some of them indicating that these could be machine-translated.  Once you select the languages you want, you’ll see a folder within your app that contains the configuration information:

Now if you open the XLF files you’ll basically see some XML that contains configuration information but initially won’t see any of your string values.  You need to do a build to populate those files.  After building you’ll see the XLF files regenerated with the keys to be localized:

   1: <?xml version="1.0" encoding="utf-8"?>

   2: <xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:oasis:names:tc:xliff:document:1.2 xliff-core-1.2-transitional.xsd">

   3:   <file datatype="xml" source-language="en-US" target-language="de-DE" original="LocTesting_Multilingual.prilog.xml" tool-id="MAT" product-name="LocTesting" product-version="Version 1" build-num="1.0.0.0">

   4:     <header>

   5:       <tool tool-id="MAT" tool-name="Multilingual App Toolkit" tool-version="1.0" tool-company="Microsoft" />

   6:     </header>

   7:     <body>

   8:       <group id="Resources">

   9:         <trans-unit id="Resources\SomeTextBlock\Text" translate="yes" xml:space="preserve">

  10:           <source>Good morning!  Have a nice day!</source>

  11:           <target state="new">Good morning!  Have a nice day!</target>

  12:         </trans-unit>

  13:         <trans-unit id="Resources\SomeButton\Content" translate="yes" xml:space="preserve">

  14:           <source>Click to Save</source>

  15:           <target state="new">Click to Save</target>

  16:         </trans-unit>

  17:       </group>

  18:     </body>

  19:   </file>

  20: </xliff>

Now you send those off for translation by right-clicking on the XLF file and choosing Send for translation which will give you a dialog to choose if you want to mail them or save to a folder and which format (TPX/XLIFF).  At this point your translation process can begin.  If you don’t have a translation process where you would normally send the XLIFF files, you can use the MAT Localization Editor that is installed with the toolkit.  Launching this tool and opening your XLIFF file will allow you (or the person doing translations) to edit the files with the correct value.  The MAT editor also has the Microsoft Translator capability as well.  Here’s an example of the above German file in the editor with one value translated by the Microsoft Translator:

Once you have the edited XLIFF file you import that back into your project.  Notice there are some other workflow-related properties in the XLIFF (i.e., Signed off, ready for review, etc.) that you can enforce.  Right-click on the XLF file in your project and choose Import translation and the XLIFF file that was modified.  Once imported, when I build next the signed-off items will be indexed within my app’s resource lookup (resources.pri) and packaged.  You will not see any new RESW files generated as using this process does the indexing during the build process with the XLF file and a build task.

Amanuens

Another tool that I’ve come across is Amanuens, which is more of a service/tool than anything that integrates into Visual Studio or runs on your machine.  This service acts as a broker to translators.  You basically create a project and then upload files to be localized.  After you login and create a project (specifying the type as Metro as they now support Windows 8 application file types) then you upload your “master” RESW/RESJSON file.  After doing that you can assign a translation and this is the core of their service.  You can assign a file for translation to a person that is a user on the system as you may have a German speaking friend who might help you out.  Or you can assign to an agency and get a quote:

This way you can send it off and wait.  Either way when the translation comes back you just download the file, put it in your project in the appropriate folder and rebuild your app.  Amanuens is a pay service with a free option, but if you have an app and want to manage the workflow of that process, it seems like a pretty cool service.  They also have automatic source control synchronization that you can opt-in for so as your translations come in, they are automatically in your app via a repo sync.

Culture-correct localization

While all the above tools are awesome and fast to get you started, to build a really targeted localized app it is highly recommended you do more than machine translation, or at a minimum verify that machine translation.  Many times, especially for east Asian languages, the machine translation can be grammatically incorrect or sometimes culturally insensitive as most do dictionary-based translation rather than really understanding any context.

I recall a time in high school where a classmate went to Germany for exchange.  Having taken 6 semesters of German she felt pretty confident in her skills.  Little did she know her hoch Deutsch would prove to be a problem.  Upon arrival she went to a café with some friends and proclaimed she was hot.  However, her dictionary translation was bad and she effectively said “I’m horny” which immediately caught the attention of all the men in the room.  So it is key to understand context and culture when translating!

For this services like Amanuens really help out in both the flow and identifying a person to do the translation.  If you don’t know anyone who speaks Swedish, but want to target that market, using a service could help you get more culturally-correct translations for your app over just machine translation.  This, of course, does not come without a cost, but usually it is minimal and is a one-time translation.

One thing I’d love to see happen is somewhat of a co-op of software developers from around the world to offer translation help.  Working at Microsoft I had the chance to get correct translations of my Sudoku app for German, Japanese, Korean and French.  It was helpful to just send off the RESW file and get back the translation from a human who speaks the language and understands technology terms as well.  A service like Amanuens can help facilitate that co-op having a bank of users that are willing to donate their translation services for your project.  I think the struggle is that it is mostly English apps that need the help and hard for an English person to really reciprocate the value.  But if you are willing to help out other software developers perhaps we can start this co-op idea?

Testing your localized app

[!!_Śò ẃĥâт đõ Уôú ďó įƒ ўôú đõи'ť ћãνê тŕáйşłâţêď ţę×т ýęţ áйď ẅàήт тó тęšť ÿòµѓ ãрρ?_!!!!!!!!!!!!!!!!!!!!!!!!]

Could you read that?  Squint a little more.  It is what we call Pseudo Language.  Not a ‘real’ language but something that simulates a lot of different characteristics of localized language challenges.  Using the Multilingual Toolkit you can have all your strings translated to this Pseudo Language (sometimes called “ploc” within the walls of Microsoft) to test your app before your real language translations come in.  Using ploc helps you identify various artifacts that may exist in localizing an app.  Let’s take a simple example from above.  We had a button that said “Click to Save” in English and we translated it to German.  When rendered it would look like this respectively:

Notice that the German translation didn’t fit within the Button MaxWidth we had set because the translation of the text was longer than our English version.  Testing this is important for us to realize we need to change the constraint of the XAML sizes to accommodate our languages that we are targeting.

Historically testing localized versions of apps may have been challenging requiring you to install a language pack, try to navigate menus that you may not understand, or relying on others to verify for you.  In Windows 8, this process has become easier using the language list preferences.  The Building Windows 8 blog had a post called “Using the language you want” which talks about this concept in detail. 

NOTE: If using the Pseudo Language option and you want to test, when in the Language panel search for “qps-ploc” and you’ll see it under English (qps-ploc) as an option and then you can really test the boundaries of your app with the ploc strings!

Effectively as a developer I can go into the Language panel, add German, set it as my first language and run my app.  Now I’ll get my German resources first and I can visible verify things that need to be changed without installing any language pack on my machine…and I can quickly change back without any reboots.

Summary

Developing your application to be world-ready doesn’t have to be a huge undertaking and can turn out not to be difficult at all for your app.  While not every app is going to be the same and how you choose to architect your code may dictate how you get your resources, the concepts are still the same and starting with the mindset that your app may be localized at some point is the right thing to do.  Using RESW/RESJSON from the start and understanding the options you have for extracting those resources will make localization later very easy…in fact in some cases as easy as just putting in the updated RESW file and recompiling.

Start smart from the beginning and think global even if you aren’t ready for it just yet.  You never know when your German friend might help out translating for you and then you can instantly expand to that market within a day!

Hope this helps!

Let’s assume I have a basic class Person:

   1: public class Person

   2: {

   3:     public int Age { get; set; }

   4:     public string FirstName { get; set; }

   5:     public string Gender { get; set; }

   6: }

And in my application I have a list of that Person type that I somehow received.  In this example, I’m just hard-coding it right now.

   1: List<Person> people = new List<Person>();

   2: people.Add(new Person() { Age = 38, FirstName = "Tim", Gender = "Male" });

   3: people.Add(new Person() { Age = 9, FirstName = "Zoe", Gender = "Female" });

   4: people.Add(new Person() { Age = 5, FirstName = "Zane", Gender = "Male" });

I can then decide I want to bind to a ListView control which has a particular template:

   1: <ListView x:Name="PeopleList" Width="500" Height="300">

   2:     <ListView.ItemTemplate>

   3:         <DataTemplate>

   4:             <StackPanel Orientation="Horizontal">

   5:                 <TextBlock Text="{Binding TheName}" Margin="0,0,10,0" />

   6:                 <TextBlock Text="{Binding GuysAge}" />

   7:             </StackPanel>

   8:         </DataTemplate>

   9:     </ListView.ItemTemplate>

  10: </ListView>

Notice that I’m binding to properties (TheName and GuysAge) that don’t exist on my Person class?  In my code, I can then create a LINQ query to filter out only the “dudes” from my list and bind that result:

   1: var onlyGuys = from g in people

   2:                where g.Gender == "Male"

   3:                orderby g.FirstName descending

   4:                select new

   5:                {

   6:                    GuysAge = g.Age,

   7:                    TheName = g.FirstName,

   8:                    Gender = "Dude"

   9:                };

  10:  

  11: PeopleList.ItemsSource = onlyGuys;

The result is that my ListView now shows 2 people in the list.  Nice.

Get in the real world

Now I would probably agree that since you already have a strongly-typed class this is probably not the use case here.  It certainly might be helpful, but you already have a class (and in this example, one that you completely control so you could shape it to be what you really need).  What about those times you don’t have a class or you don’t own the type coming back?  JSON ring a bell?  Using the sample JSON response (I’m not focusing on how to retrieve data here just how to bind to it) from Twitter APIs, we can demonstrate how this might be more helpful.  Here’s the Twitter JSON data I’m referring to in this example: Twitter Mentions API.

My app wants to retrieve and bind to Twitter data but I don’t really want to have a “TwitterResponse” data type that I have to serialize in/out in my code.  The mention data is an array of mentions.  For the sake of simplicity I’ve basically put my JSON string in a file rather than confuse this sample in how to work with Twitter.  My code looks like this (assume that ‘data’ is the resulting Twitter mentions JSON string:

   1: // parse the data into a JsonArray object

   2: var mentions = JsonArray.Parse(data);

   3:  

   4: // build the query out of the mentions

   5: var qry = from m in mentions

   6:           select new

   7:           {

   8:               MentionText = m.GetObject()["text"].GetString(),

   9:               FromUser = m.GetObject()["user"].GetObject()["screen_name"].GetString(),

  10:               ProfilePic = m.GetObject()["user"].GetObject()["profile_image_url"].GetString()

  11:           };

  12:  

  13: MentionData.ItemsSource = qry;

Notice the LINQ query for creating a “new” type that I will bind to my ListView.  In my XAML I have a simple DataTemplate to demonstrate:

   1: <ListView x:Name="MentionData" Width="500" Height="300">

   2:     <ListView.ItemTemplate>

   3:         <DataTemplate>

   4:             <StackPanel>

   5:                 <TextBlock Text="{Binding FromUser}" />

   6:                 <TextBlock Text="{Binding MentionText}" TextWrapping="Wrap" />

   7:             </StackPanel>

   8:         </DataTemplate>

   9:     </ListView.ItemTemplate>

  10: </ListView>

The result is me being able to create a LINQ query and create a new anonymous type and directly bind to it.

Voila!  Perhaps you already discovered this little gem and are using it.  It is a welcome addition to the data binding story for Metro style app development with XAML and .NET!  Of course the same benefit can be had for XML data using XLINQ queries, so while this example is for JSON data, really any source data applies…it is all about that new anonymous type you create!

Hope this helps!

A while back I heard about the change in price for some Windows Azure services and the one that piqued my interest was the SQL Azure.  At the time it hit me right as I needed to move around some of my hosting aspects of my site.  The lure of the $5/month SQL Azure database (as long as it was < 100MB) was appealing to me.  The SQL server aspect of my site has always been a management headache for me as I don’t want to have to worry about growing logs, etc.

Stung by marketing

I followed the announcements to the http://www.windowsazure.com site and read the descriptions of the services.  I was immediately convinced of the value and heck, it was a service from my company so why shouldn’t I give it a try and support it?  When I began to set it up, however, there were questions being asked during setup and I started to get concerned.  I asked around about if this $5 fee was really the only fee.  I didn’t want to get surprises by things like compute time.  Perhaps I wasn’t asking specific enough questions, but all answers I got was that signs pointed to yes, that would be my only fee.

NOTE: As of this writing yes I am a Microsoft employee, but this is my own opinion and I realize that peoples’ expectations and results vary.  This is only my experience.  I’m not only an employee but also a customer of Microsoft services and in this instance a full paying customer.  No internal benefits are used in my personal Azure hosting accounts.

Yesterday I learned that wasn’t the case.  I received my first Azure billing statement and it was way more than I expected.  Yes my $5 database was there as expected, but also was suddenly “Data Transfer” charges of $55.

Trying to make sense of billing

I immediately tried to make sense of this billing.  I immediately remembered that I had created a storage account as well for a quick test and perhaps I forgot to disable/delete that service.  I logged into the management portal and saw that my storage account was properly deleted and nowhere to be seen.  But how to make sense of these charges from the past week then?  Luckily Azure provides detail usage download data so I grabbed that.  The CSV file I download did indeed provide some detail…perhaps too much as some of it I couldn’t discern, namely the one piece that I had hoped would help me: Resource ID.  This ID was a GUID that I thought pointed to a service that I used.  It did not, or at least that GUID was nowhere to be seen on my Azure management portal.

I contacted the billing support immediately to help.  I was able to talk with a human fairly quickly which was a plus.  The gentleman explained to me that I had a lot of outgoing data leaving the Azure data centers and that was the source of the costs.  He asked if I knew if anything was connecting to my SQL Azure instance externally.  Well, duh, yes it was my site!  He went on to explain that this constitutes “Data Transfer” and I’m billed at a per GB rate for any data that leaves the Azure data center. 

I took a deep breath and asked where this was documented in my SQL Azure sign-up process.  We walked through the site together and he agreed that it wasn’t clear.  After being put on hold for a while, I was assured I would receive a credit for the misunderstanding.  Unfortunately for Azure, the damage was done and they lost a customer.

Where the failure occurred

For me the failure was twofold: me for not fully understanding terms and Azure for not fully explaining them in context.  I say “in context” because that was the key piece that was missing in my registration of my account.  Let me explain the flow I took (as I sent this same piece of internal feedback today as well) as a customer once I heard the announcement about the SQL Azure pricing changes:

• I received notice of updated SQL Azure pricing
• I visited the site http://www.windowsazure.com for more information
• I clicked the top-level “PRICING” link provided as that was my fear
• I was presented with a fancy graphical calculator.  I moved the slider up to 100MB and confirmed the pricing on the side (no asterisks or anything)
• I notice a “Learn more about pricing, billing and metering” link underneath the calculator and click it to learn more
• I’m presented with a section of 10 different options all presented at the same level giving the appearance as unique services.
• I choose the Database one and again read through and confirm the charge for the 100MB database option.
• I click the “More about databases” link to double-verify and am presented with another detailed description of the billing

Not once during that process was context provided.  Not at any of the steps above (3 different pricing screens) was there context that additional fees could also apply to any given service.  Data transfer, in fact, doesn’t even describe itself very well.  As I was assured in asking folks involved in Azure about my concern on pricing, this “Data Transfer” wasn’t brought up at all.  I’m not sure why at all it is listed along side services and almost presented as a separate service as it appears all Azure services are subject to data transfer fees.  This is not made clear during sign up nor marketing of the pricing for each service.  SQL Azure should clearly state that the fees are database *plus* any additional fees resulting from data transfer.  Heck Amazon does this with S3 which also makes it so confusing to anticipate the cost of billing there as well…but at least it is presented that I need to factor that into my calculation.

I’m to blame, so why am I whining

I said I’m to blame as well for not understanding better what I’m getting into.  It is unfortunate because I really did like the service and felt an assurance of more reliability with my database then I had before.  The management portal was great and the uptime and log management was something I didn’t have to think about anymore. 

So why, you might ask, am I complaining about a service fee for something that was providing me value? 

NOTE: You may ask why I didn’t just move my site within Azure as well so that no data would be leaving the data centers.  This is a fair question, but unfortunately my site won’t run on any Azure hosting services and additionally I manage a few sites on a single server so it is cost prohibitive to have multiple Azure hosting instances for me right now.

Well it is simple.  I’m not made of money.  This blog has no accounting department or annual budget and such, I have to be smart about even the smallest cost.  I already have sunk costs into the server that hosts this site as well as a few others.  A $5/month database fee was nothing and justifiable easily with the value I was getting and the minor additional cost.  $50 (and growing) just wasn’t justifiable to me.  It was already at the same cost as my dedicated server and just no longer made sense for my scenario here.  In this instance I’m the “little guy” and need to think like one.  Perhaps cloud services are not for me.

Summary

So what did I learn?  Well, I really need to understand bandwidth and transfer data better for the sites I have.  Unfortunately this isn’t totally predictable for me and as such if I can’t predict the cost then it isn’t something that I should be using.  If you are considering these types of services regardless of if they are from Azure or Amazon (or whomever) you need to really plan out not only the service but how it will be used.  Don’t be lured by those shiny cost calculators that let you use sliders and show you awesome pricing but don’t help you estimate (or alert you) to that some of those sliders should be linked together.

I think Azure (and other similar services) have real customer value…there is no doubt in that.  For me, however, it just isn’t the time right now.  The services, based on my configuration needs, just don’t make sense.  Had I had a clearer picture of this when signing up, I wouldn’t have been in this situation of frustration.  Choose your services wisely and understand your total usage of them.  For me it currently doesn’t make sense and I’m moving back to a SQL Express account on my server.  Yes I’ll have to manage it a bit more, but my costs will be known and predictable.

Hope this helps.

There wasn’t a vote, but if there was: I don’t like narrow, fixed width web designs. Use media queries, scale intelligently on widescreen.

— Jon Galloway (@jongalloway) March 30, 2012

Now when I saw this I figured it was another nudge.  I did also have some time this weekend without any distractions so I took it as an opportunity to do some ‘work’ on this here blog.  Now a while back I was inspired by what Scott Hanselman had done on his site with a designer.  I reached out to a few designers that I admired, but frankly never heard back .  I figured that was okay as I wasn’t in a position to really pay what I know it is worth for a good designer.  So I went looking for things on the web that I could do myself.  I did want some subtle design tweaks to represent some things I’m currently passionate about.

Bootstrap your CSS

After some digging I saw a ton of pointers to Bootstrap.  This is an Open Source Javascript/CSS library that sets your site up for styling success and layout goodness.  The documentation was some of the better docs I’ve seen for a library.  Each aspect of the library/styles where in the docs that I could visually see, interact with and see the code that produced the behavior.  I liked what I saw and went to work.

When I got all the styles configured (using the basic setup from Bootstrap) I went to work on some of my own minor tweaks.  One of the things I really liked is the responsive layout options, not only for the grid but also for different screen sizes.  By adding a simple class I can specify certain aspects that shouldn’t be displayed when viewing the site on a tablet or phone.  There were other cool responsive options for this such as the main menu will switch to a drop-down approach when on a smaller device.  Using Firebug, IE F12 tools and real devices I was able to get the precise tweaks that I wanted.  Here’s what my site looks like on an iPhone as an example:

Notice the menu at the top is gone but replaced with a little icon (which is a drop-down).  Also notice the sidebar area is no longer visible (it is on the bottom of the site in this device view).  I like this subtle configuration that was really easy to do with just adding a class name to the area I wanted to collapse.

The other thing I wanted was to implement my primary navigation links in a little-more-than-text style.  I used the CSS sprite method by creating a single image that I would then define styles that used clips within that image to pull out the right area.  Here is the image in entirety:

Notice how the normal and hover states are the same image. 

NOTE: I put this on a black background so you can see them but it is actually a transparent background so the theme’s background shows through.

What I do then is just define a style for the <a> tag like:

   1: #follow {

   2:     background-image: url("navbarglyphs.png");

   3:     background-position: -195px 0px;

   4: }

   5:  

   6: #follow:hover {

   7:     background-image: url("navbarglyphs.png");

   8:     background-position: -195px -70px;

   9: }

Now I was having a bit of difficulty with this because I was misunderstanding the background-position value in CSS.  A quick set of second eyes with Shawn Wildermuth (who is doing a bunch of HTML dev posts right now) helped me realize my math was wrong and I needed to use the negative value instead of what I was using.  Once that forehead-slap moment was done, I was set. 

I still have a few tweaks to go (need to re-work the comments sections but didn’t have the time to think about a design more) but I’m happy with the quick re-design.  It is very simple for sure, but I like it.  I tried on a few different screen sizes and I think I have met Jon’s challenge to adapt to the available space for the screen.  If you are working with a new site and aren’t a CSS/JS guru I highly recommend looking at Bootstrap as a solid starting point for your efforts.

Picture of the AppBar in the Bing Maps application

Most of the applications use the standard AppBar button concepts that clicking invokes some action for the app.  There may be times, however, where that button serves as a “toggle” to something in your app.  Using the Bing Maps app as an example, the “Show Traffic” command is actually a toggle command that, well, shows traffic.  You want to give your users some visual indication whether that toggle selection is on/off.  This can be accomplished in XAML by using 2 buttons and toggling their visibility, but that may be overkill for what you simple want to do.

The Visual Studio project templates provide a set of styles for the AppBar for you, but more importantly a base style AppBarButtonStyle that serves as the core design.  Altering this just slightly and you can have a ToggleAppBarButtonStyle for your project.  Here’s the style for that base:

   1: <Style x:Key="ToggleAppBarButtonStyle" TargetType="ToggleButton">

   2:     <Setter Property="Foreground" Value="{StaticResource AppBarItemForegroundBrush}"/>

   3:     <Setter Property="VerticalAlignment" Value="Stretch"/>

   4:     <Setter Property="FontFamily" Value="Segoe UI Symbol"/>

   5:     <Setter Property="FontWeight" Value="Normal"/>

   6:     <Setter Property="FontSize" Value="21.333"/>

   7:     <Setter Property="AutomationProperties.ItemType" Value="AppBar ToggleButton"/>

   8:     <Setter Property="Template">

   9:         <Setter.Value>

  10:             <ControlTemplate TargetType="ToggleButton">

  11:                 <Grid Width="100" Background="Transparent">

  12:                     <StackPanel VerticalAlignment="Top" Margin="0,14,0,13">

  13:                         <Grid Width="40" Height="40" Margin="0,0,0,5" HorizontalAlignment="Center">

  14:                             <TextBlock x:Name="BackgroundGlyph" Text="" FontFamily="Segoe UI Symbol" FontSize="53.333" Margin="-4,-19,0,0" Foreground="{StaticResource AppBarItemBackgroundBrush}"/>

  15:                             <TextBlock x:Name="BackgroundCheckedGlyph" Visibility="Collapsed" Text="" FontFamily="Segoe UI Symbol" FontSize="53.333" Margin="-4,-19,0,0" Foreground="{StaticResource AppBarItemForegroundBrush}"/>

  16:                             <TextBlock x:Name="OutlineGlyph" Text="" FontFamily="Segoe UI Symbol" FontSize="53.333" Margin="-4,-19,0,0"/>

  17:                             <ContentPresenter x:Name="Content" HorizontalAlignment="Center" Margin="-1,-1,0,0" VerticalAlignment="Center"/>

  18:                         </Grid>

  19:                         <TextBlock

  20:                         x:Name="TextLabel"

  21:                         Text="{TemplateBinding AutomationProperties.Name}"

  22:                         Margin="0,0,2,0"

  23:                         FontSize="12"

  24:                         TextAlignment="Center"

  25:                         Width="88"

  26:                         MaxHeight="32"

  27:                         TextTrimming="WordEllipsis"

  28:                         Style="{StaticResource BasicTextStyle}"/>

  29:                     </StackPanel>

  30:                     <Rectangle

  31:                         x:Name="FocusVisualWhite"

  32:                         IsHitTestVisible="False"

  33:                         Stroke="{StaticResource FocusVisualWhiteStrokeBrush}"

  34:                         StrokeEndLineCap="Square"

  35:                         StrokeDashArray="1,1"

  36:                         Opacity="0"

  37:                         StrokeDashOffset="1.5"/>

  38:                     <Rectangle

  39:                         x:Name="FocusVisualBlack"

  40:                         IsHitTestVisible="False"

  41:                         Stroke="{StaticResource FocusVisualBlackStrokeBrush}"

  42:                         StrokeEndLineCap="Square"

  43:                         StrokeDashArray="1,1"

  44:                         Opacity="0"

  45:                         StrokeDashOffset="0.5"/>

  46:  

  47:                     <VisualStateManager.VisualStateGroups>

  48:                         <VisualStateGroup x:Name="CommonStates">

  49:                             <VisualState x:Name="Normal"/>

  50:                             <VisualState x:Name="PointerOver">

  51:                                 <Storyboard>

  52:                                     <ObjectAnimationUsingKeyFrames Storyboard.TargetName="BackgroundGlyph" Storyboard.TargetProperty="Foreground">

  53:                                         <DiscreteObjectKeyFrame KeyTime="0" Value="{StaticResource AppBarItemHoverBackgroundBrush}"/>

  54:                                     </ObjectAnimationUsingKeyFrames>

  55:                                 </Storyboard>

  56:                             </VisualState>

  57:                             <VisualState x:Name="Pressed">

  58:                                 <Storyboard>

  59:                                     <DoubleAnimation

  60:                                     Storyboard.TargetName="OutlineGlyph"

  61:                                     Storyboard.TargetProperty="Opacity"

  62:                                     To="0"

  63:                                     Duration="0"/>

  64:                                     <ObjectAnimationUsingKeyFrames Storyboard.TargetName="BackgroundGlyph" Storyboard.TargetProperty="Foreground">

  65:                                         <DiscreteObjectKeyFrame KeyTime="0" Value="{StaticResource AppBarItemForegroundBrush}"/>

  66:                                     </ObjectAnimationUsingKeyFrames>

  67:                                     <ObjectAnimationUsingKeyFrames Storyboard.TargetName="Content" Storyboard.TargetProperty="Foreground">

  68:                                         <DiscreteObjectKeyFrame KeyTime="0" Value="{StaticResource AppBarItemPressedForegroundBrush}"/>

  69:                                     </ObjectAnimationUsingKeyFrames>

  70:                                 </Storyboard>

  71:                             </VisualState>

  72:                             <VisualState x:Name="Disabled">

  73:                                 <Storyboard>

  74:                                     <ObjectAnimationUsingKeyFrames Storyboard.TargetName="OutlineGlyph" Storyboard.TargetProperty="Foreground">

  75:                                         <DiscreteObjectKeyFrame KeyTime="0" Value="{StaticResource AppBarItemDisabledForegroundBrush}"/>

  76:                                     </ObjectAnimationUsingKeyFrames>

  77:                                     <ObjectAnimationUsingKeyFrames Storyboard.TargetName="Content" Storyboard.TargetProperty="Foreground">

  78:                                         <DiscreteObjectKeyFrame KeyTime="0" Value="{StaticResource AppBarItemDisabledForegroundBrush}"/>

  79:                                     </ObjectAnimationUsingKeyFrames>

  80:                                     <ObjectAnimationUsingKeyFrames Storyboard.TargetName="TextLabel" Storyboard.TargetProperty="Foreground">

  81:                                         <DiscreteObjectKeyFrame KeyTime="0" Value="{StaticResource AppBarItemDisabledForegroundBrush}"/>

  82:                                     </ObjectAnimationUsingKeyFrames>

  83:                                 </Storyboard>

  84:                             </VisualState>

  85:                         </VisualStateGroup>

  86:                         <VisualStateGroup x:Name="FocusStates">

  87:                             <VisualState x:Name="Focused">

  88:                                 <Storyboard>

  89:                                     <DoubleAnimation

  90:                                         Storyboard.TargetName="FocusVisualWhite"

  91:                                         Storyboard.TargetProperty="Opacity"

  92:                                         To="1"

  93:                                         Duration="0"/>

  94:                                     <DoubleAnimation

  95:                                         Storyboard.TargetName="FocusVisualBlack"

  96:                                         Storyboard.TargetProperty="Opacity"

  97:                                         To="1"

  98:                                         Duration="0"/>

  99:                                 </Storyboard>

 100:                             </VisualState>

 101:                             <VisualState x:Name="Unfocused" />

 102:                             <VisualState x:Name="PointerFocused" />

 103:                         </VisualStateGroup>

 104:                         <VisualStateGroup x:Name="CheckStates">

 105:                             <VisualState x:Name="Checked">

 106:                                 <Storyboard>

 107:                                     <DoubleAnimation

 108:                                     Storyboard.TargetName="OutlineGlyph"

 109:                                     Storyboard.TargetProperty="Opacity"

 110:                                     To="0"

 111:                                     Duration="0"/>

 112:                                     <ObjectAnimationUsingKeyFrames Storyboard.TargetName="BackgroundGlyph" Storyboard.TargetProperty="Foreground">

 113:                                         <DiscreteObjectKeyFrame KeyTime="0" Value="{StaticResource AppBarItemForegroundBrush}"/>

 114:                                     </ObjectAnimationUsingKeyFrames>

 115:                                     <ObjectAnimationUsingKeyFrames Storyboard.TargetName="BackgroundCheckedGlyph" Storyboard.TargetProperty="Visibility">

 116:                                         <DiscreteObjectKeyFrame KeyTime="0" Value="Visible"/>

 117:                                     </ObjectAnimationUsingKeyFrames>

 118:                                     <ObjectAnimationUsingKeyFrames Storyboard.TargetName="Content" Storyboard.TargetProperty="Foreground">

 119:                                         <DiscreteObjectKeyFrame KeyTime="0" Value="{StaticResource AppBarItemPressedForegroundBrush}"/>

 120:                                     </ObjectAnimationUsingKeyFrames>

 121:                                 </Storyboard>

 122:                             </VisualState>

 123:                             <VisualState x:Name="Unchecked"/>

 124:                             <VisualState x:Name="Indeterminate"/>

 125:                         </VisualStateGroup>

 126:                     </VisualStateManager.VisualStateGroups>

 127:                 </Grid>

 128:             </ControlTemplate>

 129:         </Setter.Value>

 130:     </Setter>

 131: </Style>

Now with that style we can have a simple style that shows a toggle on and off for the same button:

   1: ...

   2: <Page.BottomAppBar>

   3:     <AppBar>

   4:         <ToggleButton Style="{StaticResource ToggleAppBarButtonStyle}" 

   5:                 AutomationProperties.Name="Search" 

   6:                 Content="" />

   7:     </AppBar>

   8: </Page.BottomAppBar>

   9: ...

The result would show:

ToggleButtonAppBarStyle in off/on state

This way we exhibit all the same behaviors of the AppBarButtonStyle, but just applied to the ToggleButton element in XAML.  Now we could probably refactor both to have an even more derivative base style and use more BasedOn styling, but how it is currently structured we couldn’t have a ToggleButton based on a Button style.  But thanks to the style/template engine in XAML we can re-use a lot and serve our needs!

Notice that you can set the Content to be whatever you want.  Since my base style uses the Segoe UI Symbol font, I’m setting the unicode value for a glyph here for Search.  A set of some cool glyphs you can use can be found in my previous post on XAML AppBar button styles.

You can get the ToggleAppBarButtonStyle from here: https://gist.github.com/2131230.

Hope this helps!

In a blog post announcing the update, Ian notes that if you were using the previous SDK that there have been breaking changes and to use the updated SDK.  This update includes support for XAML applications and adding the ad units couldn’t be easier.  After installing their SDK (which was developed using the same distribution concepts in my post about creating a distributable custom control previous post), you will be able to use Add Reference in Visual Studio, navigate to the Windows/Extensions area and add the SDK.  After that it is as simple as adding the control in your project:

   1: <Grid Background="{StaticResource ApplicationPageBackgroundBrush}">

   2:     <Border Background="Red" VerticalAlignment="Bottom">

   3:         <ads:AdControl xmlns:ads="using:Microsoft.Advertising.WinRT.UI" 

   4:                        VerticalAlignment="Bottom" Width="728" Height="90" 

   5:                        AdUnitId="YOUR_AD_UNIT_ID" 

   6:                        ApplicationId="YOUR_APPLICATION_ID" />

   7:     </Border>

   8: </Grid>

Now you do, of course, have to have a pubCenter account and create the ad units beforehand in order for this to work, but that setup time didn’t take long at all.

You may have some time for your own ad units to be provisioned and start serving ads, but the ad team created some test values you can use to see how things all work.  Download the Ads SDK today!

Hope this helps!

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.

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: }

   6:  

   7: public static readonly DependencyProperty ImagePathProperty =

   8:     DependencyProperty.Register("ImagePath", typeof(ImageSource), typeof(LabeledImage), new PropertyMetadata(null));

   9:  

  10: public string Label

  11: {

  12:     get { return (string)GetValue(LabelProperty); }

  13:     set { SetValue(LabelProperty, value); }

  14: }

  15:  

  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();

   4:  

   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">

  10:  

  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:

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:

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\

–SimpleCustomControl

—-1.0

——SDKManifest.xml (the file above)

——References\CommonConfiguration\neutral\SimpleCustomControl.dll

——Redist\CommonConfiguration\neutral\SimpleCustomControl.pri

——Redist\CommonConfiguration\neutral\Themes\generic.xaml

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:

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:

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:

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:

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:

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.

Summary

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:

• Windows SDK: XAML User and Custom Controls (shows the C++ custom control as well)
• Creating a Software Development Kit (refer to Extension SDK section)
• NuGet Packages
• VSIX Deployment

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

Hope this helps!

• Read their announcement here: Bing Maps for Metro style apps
• Download the bits: Bing Maps SDK for Metro style apps (VSIX)
• Read the reference API docs: Bing Maps SDK

If you are familiar with the Silverlight control, it is similar in nature to how you would use it in your XAML Metro style app.  Here’s some helpful tips that are in the docs but just wanted to elevate them because we have a tendency not to read docs .

Installing

Installing is simple for Visual Studio.  Download the VSIX file and double-click it.  If you have both Express and Ultimate installed it will prompt you to install it for both installations.  That’s it…you are done.  If you had VS running while you did this, it would be a good idea to restart VS.

Creating a .NET XAML application with maps

Once you restart VS, you can create a new C# Metro style application.  Once you have this, just right click on the project and choose Add Reference and then navigate to the Windows\Extensions section and you will see Bing Maps:

When you do this you will also want to add a reference to the VCLibs Extension at this time.  Why?  Well, the Map control is a native control.  Adding the VCLibs dependency at this time will add the necessary information in your app’s package manifest noting the dependency and it will install any required package dependencies from the store when your user’s install it.

If you compile your application immediately you will notice an exception during build:

   1: 1>------ Build started: Project: Application17, Configuration: Debug Any CPU ------

   2: 1>C:\Windows\Microsoft.NET\Framework\v4.0.30319\Microsoft.Common.targets(1667,5): error MSB3774: Could not find SDK "Microsoft.VCLibs, Version=11.0".

   3: 1>C:\Windows\Microsoft.NET\Framework\v4.0.30319\Microsoft.Common.targets(1667,5): error MSB3778: "APPX" attributes were found in the SDK manifest file however none of the attributes matched the targeted configuration and architecture and no "APPX" attribute without configuration and architecture could be found. If an appx is required then the project will fail at runtime.

   4: ========== Build: 0 succeeded, 1 failed, 0 up-to-date, 0 skipped ==========

This is because by default the managed applications are “AnyCPU” configuration and the native control doesn’t have that configuration.  Change your app to be either x86 or amd64 and your build will succeed.  This means that yes, you will want to create multiple architecture-specific packages for your app.  The good thing is during package creation, the tools in Visual Studio make this easy for you.

Creating a C++ XAML application with maps

For C++ the step is to just reference the Bing Maps extension SDK and you are done.  C++ projects are always architecture-specific so you don’t have the AnyCPU situation here.

Using the Map control

You’ll need to get set up with an API key, which the getting started docs inform you about.  Once you have that you are ready to use the control.  I’m a fan of putting the API key in my App.xaml as a resource:

   1: <Application.Resources>

   2:     <ResourceDictionary>

   3:         <ResourceDictionary.MergedDictionaries>

   4:             <ResourceDictionary Source="Common/StandardStyles.xaml"/>

   5:         </ResourceDictionary.MergedDictionaries>

   6:         <x:String x:Key="BingMapsApiKey">YOUR KEY HERE</x:String>

   7:     </ResourceDictionary>

   8: </Application.Resources>

And then in my Map control I can just refer to it:

   1: <Page

   2:     x:Class="Application17.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:Application17"

   6:     xmlns:d="http://schemas.microsoft.com/expression/blend/2008"

   7:     xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"

   8:     xmlns:bing="using:Bing.Maps"

   9:     mc:Ignorable="d">

  10:  

  11:     <Grid Background="{StaticResource ApplicationPageBackgroundBrush}">

  12:         <bing:Map x:Name="MyMap" Width="640" Height="480" 

  13:             Credentials="{StaticResource BingMapsApiKey}" />

  14:     </Grid>

  15: </Page>

Once I have those pieces in place, I’m done and can run my app and get full map interactivity.  Notice the xmlns declaration in my Page with the “using:Bing.Maps” notation.  Now when I run:

I can quickly add location to my app by setting the capability in the Package.appxmanifest and then wiring up the map to center on my current location…

   1: async protected override void OnNavigatedTo(NavigationEventArgs e)

   2: {

   3:     Geolocator geo = new Geolocator();

   4:     geo.DesiredAccuracy = PositionAccuracy.Default;

   5:     var currentPosition = await geo.GetGeopositionAsync();

   6:  

   7:     Location loc = new Location() { Latitude = currentPosition.Coordinate.Latitude, 

   8:         Longitude = currentPosition.Coordinate.Longitude };

   9:  

  10:     MyMap.SetView(

  11:         loc, // location

  12:         13, // zoom level

  13:         true); //show animations)

  14:  

  15: }

I’m excited about what the Bing team has done here and you should go grab it, read the docs and start incorporating location visualization into your Metro style XAML apps today!

Hope this helps!

What is Settings?

When I refer to Settings here I’m referring to that consistent experience in Metro style apps when the user invokes the charms bar and chooses settings.  By default every application will respond to that Settings charm.  If you do nothing you will get the default experience that you may have seen:

The text items underneath your app title are referred to as commands.  Each application will always get the Permissions command.  When the user clicks this they will get some “about” information on your app (name, version, publisher) as well as the permissions the app has requested.  As an app developer, you have to do nothing to get this experience.  In addition to that the Settings pane shows some OS-level options like volume, Wi-Fi, brightness, etc. that the user can manipulate.  But you, my fellow app developer, can also implement custom settings options in your app.

The custom SettingsCommand

The first thing you have to do to customize your experience is implement a custom SettingsCommand.  These are implemented by first listening to when the SettingsPane will request if there are any additional commands for the current view.  Settings can be global if you have something like a “master” page setup in your XAML application, but can also be specific to a currently viewed XAML page.  It is not an either/or but a both.  I’ll leave the exercise up to you and your app on when you need which (or both).

First thing you have to do is listen for the event.  You would likely do this in your XAML view’s constructor:

   1: public BlankPage()

   2: {

   3:     this.InitializeComponent();

   4:  

   5:     _windowBounds = Window.Current.Bounds;

   6:  

   7:     Window.Current.SizeChanged += OnWindowSizeChanged;

   8:  

   9:     SettingsPane.GetForCurrentView().CommandsRequested += BlankPage_CommandsRequested;

  10: }

Notice the SettingsPane.GetForCurrentView().CommandsRequested event handler that I am using.  This will get triggered whenever the user invokes the Settings charm while on this view.  It is your opportunity to add more commands to that experience.  In your method for this you would create your new SettingsCommand and add them to the ApplicationCommands:

   1: void BlankPage_CommandsRequested(SettingsPane sender, SettingsPaneCommandsRequestedEventArgs args)

   2: {

   3:     ResourceLoader rl = new ResourceLoader();

   4:  

   5:     SettingsCommand cmd = new SettingsCommand("sample", 

   6:         rl.GetString("SoundOptionCommandText"), (x) =>

   7:         {

   8:             // more in a minute

   9:         });

  10:  

  11:     args.Request.ApplicationCommands.Add(cmd);

  12: }

You are able to add the text-based commands to the SettingsPane at this time.  The second argument I provided above will be the text that will display as the menu.  Notice how here I’m using ResourceLoader to get the string value for the text to be displayed.  This is a best practice to ensure you give your user’s the best experience.  Even though you may not localize now, setting this up in the beginning makes it way easier to just drop in localized strings and not have to change code.  The “SoundOptionCommandText” exists as a key/value pair in a file in my project located at en/Resources.resw.

Now that I have this enabled and my CommandsRequested wired up, when I invoke the charm while my app is running you see my new command:

Yippee!  Your custom commands will show before the Permissions one.  The next step is to actually add something valuable to the user when they click on this new command…and that means some UI.

The custom Settings UI

When your user clicks your new shiny command you want them to see some shiny, but relevant UI.  If you were using HTML/JS you would use the WinJS.UI.SettingsFlyout control to do a lot of this for you.  There is a sample of this for comparison located in the Windows 8 developer samples.  In XAML there isn’t the literal ‘SettingsFlyout’ control equivalent, but a set of primitives for you to create the experience.  There are a few pieces you will need in place.

First I create a few member variable helpers to store some items away:

• _windowBounds – this is the Rect of the current Window size.  I will need this for proper placement
• _settingsWidth – The UX guidelines suggest either a 346 or 646 wide settings flyout
• _settingsPopup – the Popup that will actually host my settings UI

The Popup is the important piece here.  It is the primitive that provides us with the “light dismiss” behavior that you see a lot in the Windows 8 experience.  This is where you have a menu/dialog and you simply tap away and it dismisses.  Popup.IsLightDismissEnabled gives us that functionality in our control that we will need in XAML.  Now let us go back to where we created our custom SettingsCommand and add back in the creation of our Popup and custom UI:

   1: SettingsCommand cmd = new SettingsCommand("sample", rl.GetString("SoundOptionCommandText"), (x) =>

   2: {

   3:     _settingsPopup = new Popup();

   4:     _settingsPopup.Closed += OnPopupClosed;

   5:     Window.Current.Activated += OnWindowActivated;

   6:     _settingsPopup.IsLightDismissEnabled = true;

   7:     _settingsPopup.Width = _settingsWidth;

   8:     _settingsPopup.Height = _windowBounds.Height;

   9:  

  10:     // more to come still

  11: });

Notice that we are creating the Popup, setting the width to the value specified in _settingsWidth and the height to whatever the current height of the active Window is at this time.  We are also listening to the Activated event on the Window to ensure that when our Window may be de-activated for something that a user may not have done via touch/mouse interaction (i.e., some other charm invocation, snapping an app, etc.) that we dismiss the Popup correctly.  here is the OnWindowActivated method definition:

   1: private void OnWindowActivated(object sender, Windows.UI.Core.WindowActivatedEventArgs e)

   2: {

   3:     if (e.WindowActivationState == Windows.UI.Core.CoreWindowActivationState.Deactivated)

   4:     {

   5:         _settingsPopup.IsOpen = false;

   6:     }

   7: }

   8:  

   9: void OnPopupClosed(object sender, object e)

  10: {

  11:     Window.Current.Activated -= OnWindowActivated;

  12: }

Notice we are also listening for the Popup.Closed event.  This is so that we can remove the OnWindowActivated method to avoid any reference leaks lying around.  Great, now let’s put some UI into our Popup.

For my example here I’m using a UserControl that I created to exhibit my settings needs.  Your use may vary and you may just need some simple things.  As we know in XAML there is more than one way to implement it in this flexible framework and this is just an example.  Going back to our custom SettingsCommand we now create an instance of my UserControl and set it as the Child of the Popup, setting appropriate Width/Height values as well:

   1: SettingsCommand cmd = new SettingsCommand("sample", rl.GetString("SoundOptionCommandText"), (x) =>

   2: {

   3:     _settingsPopup = new Popup();

   4:     _settingsPopup.Closed += OnPopupClosed;

   5:     Window.Current.Activated += OnWindowActivated;

   6:     _settingsPopup.IsLightDismissEnabled = true;

   7:     _settingsPopup.Width = _settingsWidth;

   8:     _settingsPopup.Height = _windowBounds.Height;

   9:  

  10:     SimpleSettingsNarrow mypane = new SimpleSettingsNarrow();

  11:     mypane.Width = _settingsWidth;                    

  12:     mypane.Height = _windowBounds.Height;

  13:  

  14:     _settingsPopup.Child = mypane;

  15:     _settingsPopup.SetValue(Canvas.LeftProperty, _windowBounds.Width - _settingsWidth);

  16:     _settingsPopup.SetValue(Canvas.TopProperty, 0);

  17:     _settingsPopup.IsOpen = true;

  18: });

Now when the user clicks the “Sound Options” they will see my custom UI:

And if the user taps/clicks away from the dialog then it automatically dismisses itself.  You now have the fundamentals on how to create your custom UI for settings.

Some guiding principles

While this is simple to implement, there are some key guiding principles that make this key for your user’s experience.  First and foremost, this should be a consistent and predictable experience for your users.  Don’t get crazy with your implementation and stay within the UX design guidelines to ensure your app gives the user confidence when using it.  Additionally, here are some of my other tips.

Header Elements

You’ll notice above that the header of the custom UI is specific and contains a few elements.  The title should be clear (and again be ideally localized) in what the settings is doing.  The background color would match your app’s branding and likely be the same as the value of BackgroundColor in your app’s package manifest.  Putting your logo (use the same image you use for your SmallLogo setting in your package manifest) helps re-enforce this is the setting only for this app and not for the system.  Additionally providing a “back” button so the user can navigate back to the root SettingsPane and not have to invoke the charm again if they wanted to change other app settings.  In my example, the button simply just calls the SettingsPane APIs again to show it:

   1: private void MySettingsBackClicked(object sender, RoutedEventArgs e)

   2: {

   3:     if (this.Parent.GetType() == typeof(Popup))

   4:     {

   5:         ((Popup)this.Parent).IsOpen = false;

   6:     }

   7:     SettingsPane.Show();

   8: }

You may be curious to see the XAML used for my custom UI and I’ve included that in the download at the end here as not to take up viewing area here on the key areas.

Immediate Action

Unlike some modal dialog experiences, the Settings experience should create immediate change to your application.  Don’t put confirmation/save/cancel buttons in your UI but rather have the changes take effect immediately.  For instance in my sound example, if the user invokes the Settings charm, clicks/taps on my Sound Options and toggles the Sound Effects option on/off, then the sound should immediately turn on/off.  Now implementing this philosophy may change the way you create your custom UI and/or UserControl, but take that into account when designing.

Light Dismiss

This concept of light dismiss is about honoring the user’s action and not requiring interruption.  This is why we use the Popup.IsLightDismissEnabled option as we get this capability for free.  By using this if the user taps away to another part of the application or Window, then the Popup simply dismisses.  Don’t hang confirmation dialogs in there to block the user from doing what they want, but rather honor the context change for them.

Summary

The Windows platform has afforded us developers a lot of great APIs to create very predictable and consistent user experiences for the common things our apps will need.  Settings is one of those simple, yet effective places to create confidence in your application and a consistent Windows experience for your users.  Stick to the principles:

• Set up custom commands that make sense for the context of the view and/or for the app as a whole
• Create and show your UI according to the UX design guidelines
• Have your settings immediately affect the application
• Ensure that you use the dismiss model

Combine all these and you will be set.  Everything I talk about above is supported in XAML and WinRT.  My example is in C# because I’m most proficient in that language.  But this 100% equally applies in C++ as well and should be identical in practice.

You may be saying to yourself wouldn’t this make a great custom control?  Ah, stay tuned and subscribe here !

Hope this helps!

Download Sample: SettingsExample.zip

Adam has two posts:

• (WinJS) Windows 8 AppBarIcons enumerated and visualized
• (XAML) Windows 8 AppBarButtonStyles enumerated and visualized

Basically what these do is define a set of styles, both in CSS and XAML, that map back to unicode values in the Segoe UI Symbol font.  This contains a set of glyphs that are well-suited for use within an AppBar.  As an example in WinJS you would use:

   1: <button data-win-control="WinJS.UI.AppBarCommand" 

   2:         data-win-options="{icon:'back', label:'Back'}"><button>

And in XAML you would use:

   1: <Button Style="{StaticResource PreviousAppBarButtonStyle}" />

One thing that Adam points out is that WinJS includes definitions for a LOT of styles while the included StandardStyles.xaml file (provided for you when you create a new project in Visual Studio) defines a much smaller subset.  When determining what styles to include in the XAML set, we opted for choosing the most common rather than to bloat the ResourceDictionary with things you may not use.

NOTE: Even within the provided one, you should always make it a best practice to REMOVE styles/templates that you aren’t using so the parser doesn’t have to worry about them.

Adam also notes that he likes the style of defining the WinJS ones a bit better as he mentions the XAML syntax feels heavy.  I commented on his blog that WinJS is doing a lot of work for him here that has already defined the style.  If WinJS didn’t exist, surely it would be ‘heavy’ in defining them.  I’m still not sure why the XAML one feels heavy (once you just assume that a definition has been made for you in the ResourceDictionary provided – especially when I look above, they basically both look the same…but I digress.

One thing that I wanted to point out was how the tools, Visual Studio and Blend, help make it way easy to choose and quickly visualize these styles on the design surface.  For HTML/JS apps you need to use Blend for this as VS doesn’t support this feature at this time.  When in Blend in your HTML/JS app you can open up the control palette and see a helper for AppBar Command Button:

And this produces a generic button definition much like above:

   1: <button data-win-control="WinJS.UI.AppBarCommand" 

   2:         data-win-options="{label:'Button', type:'button'}"></button>

What you can’t do from now (that I could see) is quickly pick from a set of those data-win-options to choose which one you want…so you still have to know what the definition is that you want for the icon/label.  Let’s contrast that with the XAML experience with strongly-defined styles.  In VS or Blend I can use the resource picker to pick from a set of styles that apply to my control type, in this case button:

I can quickly change and see the option on the design surface.  Now again, if you don’t need all these styles, then please delete what you aren’t using from your ResourceDictionary.

It is great that we have design-time implementations of these styles and of course I’m partial to the XAML one as more familiar to me.  Adam pointed out the discrepancy of not having all the styles defined.  As I note, you shouldn’t have defined what you don’t need, but in the spirit of adding value, here’s an updated StandardStyles.zip with all the 150 icons defined.

Hope this helps!