Friday, April 20, 2012

Windows 8 Quick Tip: Debugging Managed Code Referenced by HTML 5 Applications

You can write libraries in Managed C# or VB, or native C++ that can be used from Windows 8 HTML5 applications as long as they are exported as WinMD libraries and conforms to WinMD rules. This is very useful especially if you want to use features in the managed world like Linq or consume SOAP services with the strongly typed WSDL proxy generator.

While I was trying to debug the managed code referenced by the HTML applications, no breakpoints were hit. After some poking around I discovered a setting that can enable debugging managed code in HTML applications.

In the HTML project properties navigate to the “Debugging” section and select “Managed Only” or “Mixed”. Please note that this will disable JavaScript debugging, so you have to choose between debugging managed libraries or Scripts at a time. The following screenshot shows this setting.


Friday, April 6, 2012

PRI Files Deep Dive - Building Global Windows 8 Metro XAML Apps Part 3

In Part 1 we explored localizing strings, and in Part 2 explored localizing images, styles and custom layouts. In this post we will dig deeper into PRI files. All resource metadata is compiled into binary PRI files using a tool called makepri.exe. PRI files store all string resources and files metadata to a tree structure that can be navigated using Windows.ApplicationModel.Resources.Core.ResourceManager. This is unmanaged WinRT class different from the managed System.Resources.ResourceManager. It is not recommended to use the managed ResourceManager unless you are building a portable class library that is not targeting WinRT only.

Dumping PRI Files

You can use makepri.exe tool to dump the PRI binary into XML following these steps
- Open “Developer Command Prompt”
- Navigate to the bin directory.
- You should see a resources.pri file
- Type “makepri dump”
- The tool will generate a “resource.pri.xml” file.
The following snippet shows a very basic PRI dump.
   1: <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   2: <PriInfo>
   3:     <ResourceMap name="8f615d67-84d4-474a-8d44-04f3482dc045" version="1.0" primary="true">
   4:         <Qualifiers/>
   5:         <ResourceMapSubtree name="Files">
   6:             <NamedResource name="App.xaml" uri="ms-resource://8f615d67-84d4-474a-8d44-04f3482dc045/Files/App.xaml">
   7:                 <Candidate type="Path">
   8:                     <Value>App.xaml</Value>
   9:                 </Candidate>
  10:             </NamedResource>
  11:             <ResourceMapSubtree name="Assets">
  12:                 <NamedResource name="SplashScreen.png" uri="ms-resource://8f615d67-84d4-474a-8d44-04f3482dc045/Files/Assets/SplashScreen.png">
  13:                     <Candidate type="Path">
  14:                         <Value>Assets\SplashScreen.png</Value>
  15:                     </Candidate>
  16:                 </NamedResource>
  17:             </ResourceMapSubtree>
  18:             <ResourceMapSubtree name="Common">
  19:                 <NamedResource name="StandardStyles.xaml" uri="ms-resource://8f615d67-84d4-474a-8d44-04f3482dc045/Files/Common/StandardStyles.xaml">
  20:                     <Candidate type="Path">
  21:                         <Value>Common\StandardStyles.xaml</Value>
  22:                     </Candidate>
  23:                 </NamedResource>
  24:             </ResourceMapSubtree>
  25:         </ResourceMapSubtree>
  26:     </ResourceMap>
  27: </PriInfo>

The root of resource trees is the ResourceMap. The ResourceMap begins with a definition of Qulaifiers list. Qualifiers include Languages, Contrasts, and Scales as explained in Part 2 of this series. For example the following project structure generates the following qualifier list.


   1: <Qualifiers>
   2:  <Language>FR-FR, EN-US</Language>
   3:  <Contrast>WHITE</Contrast>
   4:  <Scale>100</Scale>
   5: </Qualifiers>

Resource Subtrees

Resource are grouped into ResourceMapSubTree elements. Knowing the resource map tree structure is essential for navigating the map using ResourceManager. As shown in Part 1 and Part 2 of this series, you can use ResourceLoader or ms-appx Uri to load a resource with simple API. But in case you need to load a resource based on custom ResourceContext, which is really useful in situations like Unit Testing or custom configurations independent of the system settings.
Typically there are two main ResourceMapSubtree in a ResourceMap, one is named “Files” for images, xaml, and media files. The other is named “Resources” for string resources. The following screenshot shows the ResourceMapSubtree hierarchy for the SplashScreen.png file in the previous example.


All string resources are merged into a single Subtree as long as they are defined with same file name. The following project structure will generate only two Subtrees, one named Resources, the other named Custom.


Unit Testing Resources

Testing resources requires simulations of different settings like Languages, Contrasts, and Scales. Using the ResourceManager with custom ResourceContext enables customizing qualifiers. The ResourceMap.GetValue method returns the best match ResourceCandidate. The ResourceCandidate has Score property that can be used if the resource is an exact match. The following snippet demonstrates this technique.

   1: var ctx = new ResourceContext();
   2: ctx.QualifierValues["Contrast"] = "black";
   3: ctx.QualifierValues["Scale"] = "100";
   4: var c1 = ResourceManager.Current.MainResourceMap.GetValue("ms-resource:///Files/Assets/SplashScreen.png", ctx);
   5: var candidate = ResourceManager.Current.MainResourceMap.GetValue("ms-appx:///Resources/HelloWorld", ctx);
   6: foreach (var c in candidate.Qualifiers)
   7: {
   8:   Assert.AreEqual(c.Score, 1.0);
   9: }

Note that the GetValue method can receive a Uri with the path of the resource instead of navigating to the exact subtree. The Uri can be either qualified with ms-appx or ms-resource scheme.

Resource in Referenced Class Libraries

Resources in referenced libraries will be merged in the same PRI file, and in the main ResourceMap, and to load the resource you must include the Library name in the resource Uri as in the following snippet

   1: var c = ResourceManager.Current.MainResourceMap
   2:                .GetValue("ms-resource:///ClassLibrary1/Resources/HelloWorld");


In this post we explored the internals of PRI files, and how to inspect their structure. Also explored how to unit test resource based on custom contexts. In the following post we will explore localization for Culture specific values like Dates, and Currencies.

Wednesday, April 4, 2012

Building Global Windows 8 Metro XAML Apps Part 2 Localizing Files and Custom Layouts

In the previous post we explored string localization for WinRT XAML applications. In this post the focus will be on localizing files like Images, Styles, and Custom Layouts.

Image Localization in XAML

If you are referencing the image from XAML, localizing an image is as simple as creating folders for the locals you need to support and put localized versions of the image file into the local folder. The local folder must be named with ISO Culture Names. The following image shows an example for project hierarchy for localized images of country flags.


And referencing the image in XAML is the normal relative URL without the culture code as shown in the following example.


Image Localization in Code

Using a relative URI to reference package content is not permitted in Metro XAML apps. If you tried to reference a file in code with relative Uri, you will receive “The given System.Uri cannot be converted into a Windows.Foundation.Uri.” error. Instead you have to use an absolute URI using the ms-appx scheme. The simple form of ms-appx url is ms-appx///path. So in the example we used the flag image should be referred to as ms-appx:///images/flag.png. This is a shorthand for ms-appx://[package name]/path. The following example shows how to load the flag image from code.


Contrast and Scale Conventions

The resource loader does not only support conventions for local resources, but also conventions for high contrast to enhance accessibility, and different DPI conventions to support high resolution screens.
The supported modes are:
High Contrast : contrast-black and contrast-white
Pixel Density: scale-80(start screen only), scale-100 (normal DPI), scale-140 (HD DPI), scale-180 (ultra HD)
The following screenshot showing an example project hierarchy supporting different contrast and scale scenarios


The Windows 8 Simulator has good support for simulation different DPI scenarios. You can change the resolution of the simulator to 1920*1080 which corresponds to scale 140, 2560*1440 which corresponds to scale 180, or other resolutions that will reflect scale 100. High contrast can be modified from control panel accessibility.

Custom Layouts and Styles

The conventions listed for local, contrast and scale file names are not limited to images or resw files, but to any file regardless of the extensions. Which is really useful with XAML resource dictionaries, giving designers great flexibilities not only to localize strings and images, but create totally different layouts specific to a local, contrast, or scale.

All resources in Metro project are analyzed using a tool called makepri.exe, the tool generates a binary metadata file that can be dumped into XML with “makepri dump”. Inspecting PRI dumps is useful in debugging resource related issues, and  parsing resource maps. In the next post we will dig deeper into PRI files and their structure.