Feeds:
Posts
Comments

Async tips and best practices

Async/await is arguably one of the most important language improvement to ever come to C#. But with most great powers comes great responsibility. Designing APIs that leverage async/await can seem easy at first but if you don’t impose a few standards during the power dev phase of a project, when it comes time to support things like suspend/resume & robust navigation, you may quickly find yourself in a quagmire with a host of clean-up work to do. Here are a few tips me and my teams have come up with over the years to help start off on the right foot when building APIs.

Naming conventions

This is a simple and somewhat superficial one but worth mentioning. WinRT has defined a naming convention for async methods by always using the “Async” suffix at the end of a method name. This helps inform consumers of an API that it is asynchronous without having to look at the return type. It is also nice for auditing an app before shipping to ensure there are no hard to duplicate race conditions and that an app will suspend properly at any moment. More on these concerns later.

Should I add a cancellation token parameter?

Assuming you are returning a Task rather than IAsyncAction or IAsyncOperation (more on these later). Assume the answer is always yes. Async API take time to run. Maybe you already know that an async API will never take more than a few milliseconds, but this is an implementation detail that should never be imposed by the method signature. My advice is to always assume when designing an API that it might take many seconds and that the caller may want to abort the operation. This helps future proof your APIs in the following ways:

  1. Ultimately you may abstract your class and support different implementations that take longer than the original implementation.
  2. Some APIs like file system IO may always be quick in your dev bubble, but you never know when someone is loading from a network location or USB 1.0 thumb drive. Plan for the worst.

Furthermore, the consumer of the API should never need to care about how long an API will take to run. Consumers should always design with “what happens if this takes 2 seconds to run” in mind and having a consistent pattern to work with will help ensure this mind set.

WinRT compatibility: Cancellation tokens with IAsyncOperations and IAsyncActions

You should never need a cancellation token param when you are returning an IAsyncOperation or IAsyncAction. Note: These WinRT types that are required when exposing async operations from WinRT compatible components; Task is not permitted since it is a .NET specific type. The good news is, IAsyncOperation and IAsyncAction both provide cancellation token internally as part of the type. The easiest way IMO to build async WinRT components is to create a public method that returns the IAsync* type, and a private method that returns Task. Use the AsyncInfo static type to help convert a task into an IAsync* type AND supply the cancellation token. For example:

public IAsyncAction DoSomethingAsync()

{

return AsyncInfo.Run(c => DoSomethingAsync(c));

}

private async Task DoSomethingAsync(CancellationToken cancellationToken)

{

await Task.Delay(1000, cancellationToken);

}

The consumer of the public API should then always supply a cancellation token via the .AsTask(CancellationToken) extension method overload. For example:

await DoSomethingAsync().AsTask(myCancellationToken);

Optional parameters and cancellation tokens

Optional parameters can be convenient but the CancellationToken parameter should always be last. However, as you know, optional parameters cannot be followed by non-optional parameters. Fortunately, there’s a way to also make the CancellationToken parameter optional.

Don’t do this:

async Task DoSomethingAsync(CancellationToken cancellationToken, int waitTimeInSec = 1)

{

await Task.Delay(TimeSpan.FromSeconds(waitTimeInSec), cancellationToken);

}

Do this instead:

async Task DoSomethingAsync(int waitTimeInSec = 1, CancellationToken cancellationToken = default(CancellationToken))

{

await Task.Delay(TimeSpan.FromSeconds(waitTimeInSec), cancellationToken);

}

Note: this is getting pretty picky and you may chose to ignore this advice but it is my personal preference to stick with the established Microsoft convention by keeping CancellationToken at the end.

To throw or not to throw, that is the question.

This is the most important tip of all IMO. If your method accepts a cancellation token, it should always throw an OperationCancelledException if that token is cancelled during the operation. NEVER swallow that exception. If the consumer cancels the operation via the supplied cancellation token, assume they need to know and do this by throwing. The easiest way is to just let the exception bubble back up stream from any async methods you are calling. For example, here, we can assume Task.Delay will throw if the cancellation token is cancelled. We don’t need to do anything except not catch the exception.

async Task DoSomethingAsync(TimeSpan waitTime, CancellationToken cancellationToken)

{

await Task.Delay(waitTime, cancellationToken);

}

If you can’t rely on the async calls you are making internally within your method to throw or you need to handle cancellations manually such as in the case of transactions, simply call cancellationToken.ThrowIfCancellationRequested(). However, usually this is not required.

Should I throw even if the method finishes?

What if a method successfully completes but the cancellationToken is flagged after the last async operation? For example:

async Task<int> GetAverageGradeAsync(CancellationToken cancellationToken)

{

var allScores = await GetAllScoresAsync(cancellationToken);

int total = 0;

int sum = 0;

foreach (var score in allScores)

{

// SHOULD I THROW HERE?

total++;

// OR HERE?

sum += score;

}

// WHAT ABOUT HERE?

return sum / total;

}

This depends… is the method intended to be thread-safe? Does it take a long time to run?

In most cases, one can assume that the cancellation token will be flagged on the same thread as the loop is running on. If this is the case, there is no benefit to monitoring the cancellation token once the original async operation has completed. IF you can make these assumptions, there is no possible way that the cancellation token could even be set to a cancelled state in between these lines of code since everything is happening on the same thread. Yes, I know that ideally one would design an API to be thread-safe and not make assumptions about what thread the cancellation token is flagged from. However, there is a performance cost to checking the cancellation token and there’s a productivity and maintenance cost to inserting a bunch of ugly cancellationToken.ThrowIfCancellationRequested() calls in your code. My vote in most cases is to favor readability and leave out the calls to ThrowIfCancellationRequested.

That said, if you have a billion scores in the example above, ignoring the potential for an overflow, this could take a long time to calculate. In this case, you may want to run your calculation on another thread and handle cancellations during the calculation.

First, the best way to do this is on the same thread as the async operation. Creating new threads and hopping between synchronization contexts can be expensive. To prevent a new thread from being created, use Task’s ContinueWith method. This ensures that the same thread that the async operation was ran on is used for your subsequent code. Additionally, call cancellationToken.ThrowIfCancellationRequested() in your continuation code but call sparingly to improve performance. For example:

async Task<int> GetAverageGradeAsync(CancellationToken cancellationToken)

{

return await GetAllScoresAsync(cancellationToken).ContinueWith(t =>

{

int total = 0;

int sum = 0;

foreach (var score in t.Result)

{

total++;

sum += score;

if (total % 1000 == 0) cancellationToken.ThrowIfCancellationRequested();

}

cancellationToken.ThrowIfCancellationRequested();

return sum / total;

}, TaskContinuationOptions.OnlyOnRanToCompletion);

}

Please note that in the above example, it is possible that the cancellationToken was flagged as cancelled after the last call to cancellationToken.ThrowIfCancellationRequested was made but before or during sum / total was executed. This could result in your method successfully returning even though cancellationToken was set. This is OK and consumers of your API should expect that cancellation tokens are not always honored by async methods when dealing with multi-threaded scenarios.

Should I throw internal cancellation tokens?

No. If your async API creates and flags its own cancellation token, do not surface this to the consumer of your API by throwing an OperationCancelledException. A great example of this is for a timeout. Imagine you have an API that makes a web request with a 5 sec timeout. Also imagine that the timeout is something we want to handle internally within the API. A great way to impose timeouts is to create a CancellationTokenSource object and supply a timeout via the constructor. Build a linked cancellation token that marries the cancellation token supplied to the method with the timeout token created within the method and use during your web request operation. Then, check to see which one was cancelled and only bubble up OperationCancelledException if the token passed to your method was cancelled. Otherwise, throw a new exception type or handle as you see fit. For example:

static async Task<string> GetWebResponseAsync(Uri uri, CancellationToken cancellationToken)

{

// Adding a Cancellation token to time out the network request

CancellationTokenSource timeoutTokenSource = new CancellationTokenSource(TimeSpan.FromSeconds(5));

CancellationToken requestCancellationToken = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken, timeoutTokenSource.Token).Token;

using (var httpClient = new HttpClient())

{

try

{

return await httpClient.GetStringAsync(uri).AsTask(requestCancellationToken);

}

catch (OperationCanceledException) when (timeoutTokenSource.IsCancellationRequested)

{

// request timed out

throw new TimeoutException();

}

}

}

What exception should be caught?

When catching cancellation exceptions, always catch OperationCanceledException, not TaskCanceledException. TaskCanceledException inherits OperationCanceledException but there are other exception types that can derive from it as well. OperationCanceledException is safer to catch unless you know you only want to TaskCanceledException.

How do I handle transactions?

If your async method throws an OperationCanceledException always be sure that your app’s state is not left broken. Either don’t throw at all and force the method to complete entirely or roll back your changes. A good example of this would be if you are writing 2 files to disk that both need to be completely written. In this case, if you threw an exception after writing 1 file but before writing the next, you would leave the app in a broken state. Tip: With C# 6 you can put additional async code in the catch block which makes it easier to roll back transactions if necessary.

To catch or not to catch

As mentioned earlier, you should always let OperationCanceledExceptions bubble up as long as they are the direct result of the CancellationToken supplied as a parameter being canceled. However, if you are creating or re-using a CancellationToken within your code and passing that to an async method, you should not throw OperationCanceledException from your method since the caller has an implicit guarantee that they are not responsible for cancelling the operation by virtue of not supplying a cancellation token. A simple scenario would be in the case of a button click event that needs to run an async operation. Here you might want to disable the button so it can’t get clicked again during the async operation, execute the async operation supplying it with a cancellation token of some kind (perhaps one that is set when the app suspends) and catch and ignore OperationCanceledException. In the finally clause you would restore the button state to ensure you always leave the app in a good state.

private async void Button_Click(object sender, RoutedEventArgs e)

{

var control = (Control)sender;

control.IsEnabled = false;

try

{

await DoSomethingAsync(((App)Application.Current).CancellationToken);

}

catch (OperationCanceledException) { /* ignore, suspending */ }

finally

{

control.IsEnabled = true;

}

}

Note, you may want to supply CancellationToken.None if there is never a scenario that should be captured. The async API will not need to be changed to support cancellations in other scenarios.

If you follow this guideline and the one from earlier about always accepting a CancellationToken parameter in your async APIs, you will have the net result of allowing cancellation tokens to be supplied at the highest level and also be caught at that same level. This gives you the greatest flexibility for code reuse. For example, you might have an API that is called from a button click and from a background task. The outcome of cancelling may be very different for these two scenarios. In the case of the button click, you may want to show the user an error. In the result of the background task you may want to just ignore it. Building your APIs in the ways described above gives your consumers the ability to choose how to handle cancellations.

async void

There are a lot of articles on the web that say “Don’t do it” so I won’t go into all the pitfalls here and completely agree as long as we’re talking about APIs that you are building. In other words, always return a Task (or IAsnycAction/Operation) if you have control over the signature of the method. The button click handler example above however is an example of one you don’t have control over and therefore can’t avoid on the other hand. Even if you never intend to await the task (e.g. you are building a method to be called from a constructor only), you should still return the task. Later you may want to call it from another place that you can await from or you may want to store the task object in a variable and await it later.

Async events

Awaiting an event handler is not something the language supports out of the box. All you can do is raise an event (without await) and carry on. However, there is a great pattern called “deferrables” that you can use in your own events to allow the code that raised the event to wait for an async operation that occurs in an event handler. To do this you need to create a custom EventArgs class that allows the event handler to request a deferral, perform its async operation and then signal back to the code that raised the event that it is complete. The code that raised the event can then await the collection of deferrals requested by one or more event handlers before continuing.

For a more detailed explanation and code samples, see my Custom async events in C# blog post.

Async properties

Async getters and setters are also not possible in C#. However, there are some tricks you can use to work around this as well. One approach is to simply get rid of the property and use Get and Set methods instead. However, this makes binding to a UI difficult. Another way that allows you to use the binding power of properties is to use the power of INotifiyPropertyChanged to your advantage.

For example, in a getter you could do something like this:

int? highScore;

public int HighScore

{

get

{

if (highScore.HasValue) return highScore.Value;

else

{

GetHighScoreAsync(CancellationToken.None).ContinueWith(t =>

{

highScore = t.Result;

PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(nameof(HighScore)));

}, TaskScheduler.FromCurrentSynchronizationContext());

return default(int);

}

}

}

In the case of a setter you can simply call an async method to set your value without awaiting the result.

In both cases, just be cognoscente about re-entrant scenarios where the getter or setter is called more than once before the internal async call returns. To help with this you can build a task queue in the case of the setter or store the active task in the case of a getter and do a null check first before continuing. For example:

int? highScore;

Task highScoreTask;

public int HighScore

{

get

{

if (highScore.HasValue) return highScore.Value;

else if (highScoreTask == null)

{

highScoreTask = UpdateHighScoreAsync(CancellationToken.None);

}

return default(int);

}

}

async Task UpdateHighScoreAsync(CancellationToken cancellationToken)

{

try

{

highScore = await GetHighScoreAsync(cancellationToken);

PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(nameof(HighScore)));

}

finally

{

highScoreTask = null;

}

}

Other resources

https://blogs.msdn.microsoft.com/andrewarnottms/2014/03/19/recommended-patterns-for-cancellationtoken/

https://programmerpayback.com/2015/09/03/custom-async-events-in-c/

Async/await is arguably one of the most important language improvement to ever come to C#. But there are a few notable gaps that can leave developers scratching their heads. Chiefly among these is the inability to support async events and properties. Fortunately, there are some patterns that developers can employ to solve these problems. In this article I will demonstrate one such way to support async events.

The following pattern is actually based on Microsoft’s own WinRT deferrable APIs so if you’ve ever built a Windows Phone or Windows Store app, chances are you are already familiar with the consumer side of the pattern.

How it works at a high level

Event handlers merely need to request a deferral from the event argument, run async code, then tell the deferral when they are done (either by calling a .Complete() on the deferral or disposing it). Easy breezy.

Event raisers need to instantiate a DeferrableEventArgs object, raise the event passing along this object to the event handler and then wait until all deferrals requested by the event handlers complete.

How to build and consume

Let’s take a look how to accomplish this in our own custom events.

Event handlers: We will start by examining what the event handler will look like. As mentioned, this should already be familiar to Windows developers if you’ve ever handled a deferrable event such as the Windows.UI.Xaml.Application.Suspending event.

MyClass myClass = new MyClass();
myClass.DoingSomething += MyClass_DoingSomething;
async void MyClass_DoingSomething(object sender, DeferrableEventArgs e)
{
    using (var deferral = e.GetDeferral())
    {
        await Task.Delay(200); // run an async operation
    }            
}

Note: we could also call deferral.Complete() instead of .Dispose (by way of the using statement). Both have the same effect of signaling when the deferral has completed.

Event raisers: Next, let’s look at the code responsible for raising the event and awaiting all event handlers to complete work.

class MyClass
{
 public event EventHandler<DeferrableEventArgs> DoingSomething;

 public async Task DoSomethingAsync()
 {
 if (DoingSomething != null)
 {
 var args = new DeferrableEventArgs();
 DoingSomething(this, args);
 await args.DeferAsync(); // completes once all deferrals are completed.
 }
 }
}

The real magic: The real work happens in the DeferrableEventArgs object (which we need to create). I had hoped to find an existing .NET or WinRT base class already available but sadly, one does not exist. That said, Windows.Foundation.Deferral is available to reuse as the actual deferral object.

public sealed class DeferrableEventArgs
{
 readonly List<TaskCompletionSource<object>> taskCompletionSources;

 public DeferrableEventArgs()
 {
 taskCompletionSources = new List<TaskCompletionSource<object>>();
 }

 public Deferral GetDeferral()
 {
 var tcs = new TaskCompletionSource<object>();
 var deferral = new Deferral(() => tcs.SetResult(null));
 taskCompletionSources.Add(tcs);
 return deferral;
 }

 public IAsyncAction DeferAsync()
 {
 return Task.WhenAll(taskCompletionSources.Select(tcs => tcs.Task)).AsAsyncAction();
 }
}

Let’s dissect… Here we create and maintains a collection of TaskCompletionSource objects. Each time an event handler requests a deferral (by calling .GetDeferral), we create one TaskCompletionSource and mark it as complete (by calling .SetResult) when its associated deferral is signaled as completed by the event handler. The code responsible for raising the event calls DeferAsync to get a task that it can await. Here we use the Task.WhenAll method to combine all TaskCompletionSource tasks (ultimately converted to IAsyncAction to make WinRT compatible before returning it).

Hopefully this pattern will help you fully take advantage of the async await features in your app without compromising the architecture. There are other improvements that could be made here such as allowing event handlers to signal failures and cancellation, supporting deadlines, and sheltering event handlers from the DeferAsync method but hopefully this is ample to get you started with a nice reusable and robust pattern for supporting async events.

If you are a Windows 8 or Windows Phone developer you probably already know the importance of the Segoe UI Symbol font and how it provides a wealth of great “metro” icons that can be used in appbar buttons. If so, then you are also probably aware that finding the right character/glyph can be a laborious task.

There are a number of helpful, but incomplete lists on the web, and of course there is the dated ancient character map tool that comes installed with Windows but all have serious shortcomings.

After wasting a fair number of hours myself trying to hunt for glyphs, we at Vertigo set out to build the ultimate character map tool with developers in mind.

screenshot1

Download Character Map for free from the Windows Store

 

Easy to browse: scroll through the list of available glyphs in any font installed on your system. The icons are large enough to easily see so you won’t ruin your eye sight trying to find one😉

All glyphs are accounted for: the app queries the OS (DirectWrite actually) to find the unabridged list of glyphs for the given font. You might be surprised to see what you’ve been missing.

Filter by Unicode range: Want to exclude certain Unicode ranges to reduce the number of glyphs for a given font? We’ve got that too.

Dark and light theme: You can tap on the large glyph on the right to toggle foreground and background colors – or – you can go to the settings charm to change the theme of the entire app from dark to light.

Get the enumerated named: Some of the Segoe UI Symbol fonts have names. This is the preferred way to reference the icon in code and also helps give you an indication of the intended meaning for that glyph.

Get the Unicode name: sometimes glyphs have a defined meaning and name in Unicode that can be useful to know.

Get hex, decimal, and markup. Markup is especially useful for referencing the glyph in code, Xaml, or HTML when an enumerated name does not exist.

Search: Type in what you’re after into any of the fields on the right to find the glyph you’re looking for. For example: search by enumerated name by just typing into the “Enum” text box.

Save as transparent image: Save the given glyph as a transparent png of any size. Remember, you can simply tap the icon to reverse the colors before saving if you needed.

Copy to clipboard: No character map tool would be complete without the ability to easily copy the selected character to the clipboard.

 

Complete source code is also available

Since both this post and the app were written with developers in mind and because we developers tend to be a curious bunch, I’m guessing a few of you might also be interested in how this app was built. Therefore, we decided to fully open source Character Map to offer a way to see what’s under the hood or even contribute if you come up with a must-have feature.

 

Happy icon hunting and I hope you enjoy! Please rate the app in the store if you like it and please post suggestions, bugs and requests in the discussion forum on CodePlex to make them easy to track.

Back at the dawn of .NET I wrote a useful little tool for myself called Seeker. Seeker is just a simple GUI Windows app that could search for text in your file system and optionally replace it with other text. To this day I still use this tool on a regular basis and have often thought about updating, open sourcing and sharing it with the world. Today’s the day!

screenshot

Install Seeker now

 

What does it do?

  • Search files of any type for text.
  • Optionally replace text found with different text.
  • Optionally use regular expressions.
  • Search for multiple entries in a file.
  • Control the encoding used to search and replace files. By default, encoding is automatically detected and preserved.

Aren’t there already other tools out there that do the same thing? Certainly, there are a number of great options out there already. Windows Explorer itself allows you to search for text in files and the first grep tool was probably invented before my time.

So why did I write yet another search and replace tool for Windows? A few reasons: 1) Way back in the day, it served a fun little weekend project to help me learn .NET 2) I needed all the features listed above and was having trouble finding a free version that did everything I needed. Yes, I’m cheap😉 3) I wanted to be able to easily modify it if special needs arose.

Warning: Seeker is a very powerful tool and can be configured to change text in any file that you have permission to modify. Therefore, Be VERY careful when doing replace operations to ensure you don’t accidentally modify files you don’t intend to. There’s no ability to undo so use at your own risk.

Seeker is also 100% open source and can be found at seeker.codeplex.com.

Please post feedback either here or on CodePlex and enjoy!

The Kinect sensor that comes with all Microsoft Xbox One units needs to be set up either just below or above your screen. The Kinect sensor has a nice flat base that makes it easy to set on a level surface.

However, depending on how your entertainment system is organized, it may be necessary to mount the Kinect sensor to your wall. For example, if your TV is hung on a wall (as opposed to in a cabinet or on a table) or if you use a projector instead of a TV.

It is worth noting that the Xbox 360 Kinect had a number of accessories to mount your Kinect to a wall, TV, or even use a floor stand. Additionally, you can buy an Xbox One Kinect sensor mounting kit for $20.00. but it sadly appears to be made for clipping the sensor to a TV, not attaching to a wall.

Kinect Sensor TV Mounting Clip view 1

Good news: upon further examination, I discovered that the Kinect has a standard camera tripod mount on the base (this is just a standard 1/4 inch screw hole). Yes, this does means that you could easily put your Kinect on any standard tripod, although for most I’m guessing this is probably not a very cost effective nor aesthetically pleasing option.

image

…just to prove it will attach to a standard tripod.

OK, so how do I mount it to a wall? The fact that the Kinect for Xbox One has a standard tripod mount opens the door to attaching your Kinect sensor to the myriad of 3rd party camera equipment readily available on the market. For example, just by searching the web you can easily find a number of affordable “camera wall mount” accessories available (I’m guessing these products may be sold primarily for security cameras).

For my living room I wanted something discrete, solid (metal not plastic), with an adjustable head, and be black to match the color of my Kinect. I chose the VideoSecu Camera Mounting Bracket on Amazon for only $6.99 with my Amazon Prime account.

Viola!

image

Note: I also looked in my local Best Buy, Radio Shack for an option but came up empty handed. For me, the VideoSecu Camera Mounting Bracket was a great option and so far I have no complaints!

Know of a better option? Let me know!

Happy Xbox One-ing!

The other day I was looking at the Google Analytics data for my Windows 8 app and discovered that almost 5% of my users were running a resolution of 1371.42858886719 x 771.428588867188. Huh!?

The bad news is, this was due to a bug in the Google Analytics SDK for Windows 8 and Windows Phone — which I wrote!🙂

The good news is, I have since fixed it, learned a lesson (that I should have already known), and can now share my findings with you.

The point of this post is to walk through the subject of detecting physical screen resolution from within your Windows 8 and Windows Phone apps. Although not terribly complicated, it is slightly more involved than you might expect. The cruxes are 1) there is no single API to query the size of the screen your app is running on and 2) you need to understand how a certain magical feature called scaling works.

First, what not to do:

You might be tempted to determine screen resolution via the following mechanisms…

For Windows Phone 8:

Size resolution = new Size(

    Application.Current.Host.Content.ActualWidth,

    Application.Current.Host.Content.ActualHeight);

For Windows 8:

Size resolution =

    new Size(Window.Current.Bounds.Width, Window.Current.Bounds.Height);

The problem with this code (there are actually 2 issues for Windows 8 but I’ll get to that next) is that it doesn’t account for scaling.

Scaling is an awesome feature built into the platform where the OS attempts to stretch everything on the screen so an app will display at an ideal and consistent DPI regardless of the physical screen size and resolution. It does this by fooling the app into thinking that it’s running at a lower resolution than it actually is, but internally scales everything up to the real resolution before showing it on the screen. Also important to know: assets will not lose quality when they have more pixels than the pre-scaled size (this will make sense after my example below).

An example of scaling:

Let’s take an example of a 10.6” 1080p monitor (note: this is one of the screen resolutions you can set the Windows 8 simulator to).

Because this resolution is fairly high but the physical screen size is fairly small, Windows will automatically enable scaling and fool your app into thinking it is running on a lower resolution monitor. To re-iterate, this is a good thing because it means you as a developer or designer don’t have to worry about your UI looking really tiny on this particular device. To your app, the dimensions of the app (as reported by the APIs above) will actually be 1371.42858886719 x 771.428588867188 and so fonts and icons and shapes, …etc in your app will conveniently layout nicely and end up appearing at a similar size and position as it would on a 10.6” 720p monitor. Scaling gives you this little gift for free without you as the developer writing special code to change font sizes, …etc depending on physical screen DPI.

Avoiding pixilation!

I won’t get too much into the weeds about pixilation or best practices but I feel obligated to discuss 2 important things:

1) If you build your UI using a vector language (Xaml & HTML are vector languages), Windows and Windows Phone will be able to scale your UI to get the most out of every pixel without pixilation. Your app doesn’t need to do anything extra; scaling will automatically occur when visual elements are rendered and every pixel will be used. Learn more about vector graphics if that doesn’t make sense.

2) Assets like images and videos will automatically scale to fit the final resolution, not the fake application resolution. This one might be a little counter-intuitive. Imagine the following Xaml to display a 300×300 image:

<Image Source="/img300.png" Stretch="Uniform" Width="214" Height="214"/>

Because we set the width and height on the image control explicitly, your first impression might be that the image will always be stretched (Stretch = Uniform after all) to 214×214. The correct answer is: it depends.

If Windows has determined not to scale (because your monitor and resolution are close enough to the ideal DPI), then yes, the image above will be shrunk down to 214×214 when displayed on the screen.

However, if Windows scaling is occurring (lets assume at 1.4x), the image will actually be displayed on the screen in it’s full 300×300 glory. (214 * 1.4 = ~300)

To prove it, here are 2 images I created in Photoshop from the same vector source. One is saved at 214×214 pixels and the second is saved at 300×300 pixels. Using the following Xaml:

<StackPanel Orientation="Horizontal" Background="White">

 <Image Source="///img214.png" Stretch="Uniform" Width="214" Height="214"/>

 <Image Source="///img300.png" Stretch="Uniform" Width="214" Height="214"/>

</StackPanel>

When scaling is turned off (1x scaling):

image

Notice, the images look identical. This is because Windows will shrink the 2nd image (300×300) down to 214×214 before displaying it on the screen just like the Xaml says to do.

When Windows is scaling at 1.4x:

image

If you look closely, you can see that the second image is crisper. This is because the 300×300 pixel image is actually being displayed on the screen at 300×300 pixels despite what our Xaml’s height and width say will happen. The first image is actually being stretched to 300×300 when it is rendered to the screen.

Back to detecting resolution. And the correct answer is…

Easy, simply get the scaling factor (accessible via an API) and multiply it by the dimensions we gathered earlier.

For Windows Phone 8:

var content = Application.Current.Host.Content;

double scale = (double)content.ScaleFactor / 100;

int h = (int)Math.Ceiling(content.ActualHeight * scale);

int w = (int)Math.Ceiling(content.ActualWidth * scale);

Size resolution = new Size(w, h);

For Windows 8:

var bounds = Window.Current.Bounds;

double w = bounds.Width;

double h = bounds.Height;

switch (DisplayProperties.ResolutionScale)

{

    case ResolutionScale.Scale140Percent:

        w = Math.Ceiling(w * 1.4);

        h = Math.Ceiling(h * 1.4);

        break;

    case ResolutionScale.Scale180Percent:

        w = Math.Ceiling(w * 1.8);

        h = Math.Ceiling(h * 1.8);

        break;

}

Size resolution = new Size(w, h);

Almost there, don’t forget about snapped mode and orientation.

…I warned earlier that there was a 2nd problem with the Windows 8 code at the top.

For the Windows Phone, you actually don’t have to do anything. There is no such thing as snapped mode on the phone and Application.Current.Host.Content.ActualHeight and .ActualWidth always return values as if the app is running in portrait mode (even when it’s landscape).

For Windows 8, you do need to account for both snapped mode and orientation.

To help with this, you can compensate based on the ApplicationViewState. For example, here is the code I use to calculate the actual screen size, even when in portrait mode or filled mode (filled mode is when another app is in snapped mode next to your app).

if (ApplicationView.Value == ApplicationViewState.FullScreenLandscape){

    resolution = new Size(w, h);

}

else if (ApplicationView.Value == ApplicationViewState.FullScreenPortrait)

{

    resolution = new Size(h, w);

}

else if (ApplicationView.Value == ApplicationViewState.Filled){

    resolution = new Size(w + 320.0 + 22.0, h); // add the width of snapped mode & divider grip

}

The only thing lacking here is detecting the screen size when the app is snapped mode. While this bothers the purist in me, I find that most users don’t start apps in snapped mode so as long as you get the resolution at the beginning of your app’s lifetime and remember it, 99.9% of the time you will be able to accurately determine the actual screen resolution.

Worthy of mention…

Apparently it is possible using DirectX and C++/CX to determine the actual screen size. I haven’t tried this for myself but there is a blog post on how to detect screen resolution from a C++ WinRT component here.

Additional resources

Scaling to different screens

Guidelines for scaling to screens (Windows Store apps)

Multi-resolution apps for Windows Phone 8

The Windows 8 and Windows Phone developer dashboards offer some fantastic and useful metrics without developers having to lift a finger. This is great for tracking the basics such as purchases, downloads, & crashes but if you’re serious about understanding your users and improving your apps, you’ll quickly realize there are easily dozens of questions this data fails to answer. Or maybe you just want near real time information.

In a quest to improve my own apps: PuzzleTouch for Windows Phone and PuzzleTouch for Windows 8, I created the Google Analytics SDK for Windows 8 and Windows Phone and am excited to share my work with other developers. This SDK is a full featured Google Analytics client-side open source library to help your app report data to the new Google Analytics service just released last month. It supports both Windows 8 store apps and Windows Phone 7 & 8 apps and includes the same features offered in the Google Analytics SDKs for iOS and Android.

ga_realtime

Aren’t there already some great open source Google Analytics libraries out there for Win8 and WP developers?

The short answer: Yes, but they don’t work with the latest version of Google Analytics. If you want all the great new features supported today by Google Analytics or if you are setting up Google Analytics for your app for the first time, you are are required to use an SDK that supports the new Google Analytics Measurement Protocol. This new protocol is completely different from the older UTM protocol and is not backward compatible. As far as I am aware, no others libraries exist at the time of this post.

Find out more on the Google Analytics for Windows 8 and Windows Phone SDK CodePlex page about how and if this affects your existing apps.

What additional features does the new Google Analytics service include?

The ability to track and filter by app name and version.

This is extremely powerful and allows you to:

  1. Create one property for all your apps (Windows 8, Windows Phone, Android, iOS, …etc) and use filters to view them separately.
  2. On the flip side, it also allows you to compare all apps against each other.
  3. Create arbitrary filters to allow you to group certain apps (for example, you could see data for both the WP7 and WP8 version of your app as well as see that data separately.
  4. Radically change what data you track from one version to the next and create a new filter to only view data from newer versions of your app without loosing old data or having it pollute new data.
  5. Track different editions of the same app. For example, you might have a free and a paid version that you want to track together yet be able to filter on.

Track exceptions and crashes

The Windows Phone and Windows Store dashboard both offer a way to see stack traces from crashes. However, the Windows store requires some effort to see your stack traces (for Xaml based apps) and both take at least two days before data data shows up (often much longer from my experience).

When you release a new version of your app, one of the most valuable things you could possibly know is “did I break something”? The new Google Analytics service offers a great way to capture errors (handled and unhandled) in near real-time so you can analyze what went wrong and try to ship a fix before more users are affected. Don’t think you’re immune to needing this!🙂

Custom dimensions and metrics

Custom dimensions and custom metrics are like default dimensions and metrics (e.g. sessions and page views), except you create them yourself. You can use them to collect up to 200 data points that Google Analytics doesn’t automatically track. These offer numerous advantages to the old custom variable feature. Read more about custom dimensions and metrics.

Screen views and more

If you’re familiar with the classic version of Google Analytics, you may remember that screen views were displayed as page views. Google Analytics classic tried to treat your app like a website and with it came irrelevant information such as bounce rate and referrers. The new version of Google Analytics knows if you’re tracking an app and the reporting tools have been overhauled to easily help you find information relevant for apps, not websites.

Additionally, there are some additional improvements to allow you to tie custom events to specific screens in your app. No longer will you have to create 2 different events and prefix the name with the name of the page from whence it came.

E-Commerce

Possibly the best new feature of all is E-Commerce tracking. Now you can treat transactions like transactions and not have to stuff them in custom events with overloaded point values. Google Analytics easily shows you how much money you’re making in your currency of choice and information about what lead up to a purchase.

Much More

Plus, there are many other new features in Google Analytics like app timings (e.g. how long did it take my game play screen to load?), social network tracking (e.g. do users like sharing on FaceBook or Twitter more?), and much more.

How do I get started?

If you have an iOS or Android app, Google has already built SDKs for you.

If you want to track a Windows Phone (7 or 8) or Windows 8 Store app (JavaScript, C++, or .NET), go to CodePlex to learn more about the Google Analytics SDK for Windows 8 and Windows Phone or download it from NuGet.

Google Analytics itself is free (at least until you reach its quota). It’s extremely easy to spin up a new account, property and profile and start testing immediately.

The Google Analytics SDK for Windows 8 and Windows Phone is free and open source under the Ms-PL license (basically don’t sue me and use it for whatever you want).

What about other 3rd party analytics services?

There are other 3rd party analytics services available today with their own SDK. Some of these might be better than Google Analytics but I haven’t had a chance to check them out personally. Feel free to post a comment from your own experience with another analytics services.

Follow

Get every new post delivered to your Inbox.

Join 52 other followers