The update to the Windows Phone OS (build 8773) is a minor update to improve user experience on devices with 256MB of memory. Windows Phone has always supported devices with 256MB, but this update is about having the experience “buttery smooth”. This means the update is primarily about supporting lower cost devices.

Most applications will run seamlessly on lower cost devices and to verify your application on these devices please refer to the test case below. The test case starts with brief description of the changes in the Windows Phone Platform on 256MB devices and follows up with the test scenarios to verify.

Marketplace FAQ:

Q: My application is already in Marketplace, will the application be visible in Marketplace on lower cost devices?

A: Yes, however some applications which exceed the allowed memory limit will be opted out by default from Marketplace on lower cost devices to avoid user’s dissatisfaction.

Q: How are failing apps determined?

A: Opt-out is based on anonymous memory usage statistics, which are received from users that take part in a feedback program (source, section Windows Phone SDK Update & Preview)

Q: My app is opted out from Marketplace on lower cost devices. How do I opt the app in?

A: Submit an updated app to App Hub, the app will be re-tested on lower cost devices. Once the application passes certification, the application will become available.

Q: My application will not be able to work on lower cost devices how do I opt out?

A: Add requirement ID_REQ_MEMORY_90 to the WMAppManifest.xml file.

Resources:

Developing for 256-MB Devices
Optimizing Apps for Lower Cost Devices
Best Practice Tips for Delivering Apps to 256 MB Devices
Get Ready for 60% More Potential Customers
Windows Phone at Mobile World Congress 2012
Video: Inside Windows Phone #33 | Windows Phone 7.5 Refresh & 60% more Opportunity!
Tools: Windows Phone SDK 7.1.1 Update

Written by Petr Sedlacek

Marketplace has specific requirements (5.2.4) for use of hardware back button, which can be referenced here, however there are few scenarios where it is easy to overlook these requirements. This article describes some common issues related to back button which we have come across while testing showcase apps for Windows Phone.

Back Button and Secondary Tiles

When user presses the back button after launching the application from secondary tile, the application should exit and should not navigate to the home page/panorama. The main principle for deep linking is to be able to easily access a particular piece of content as opposed to be an alternative method of entering the application. The user has the option to pin the application to the start if they choose - this provides the primary entry point to the application. If the user pins a secondary tile, this is a deliberate action to pin the piece of content and is clearly distinct from pinning the application.

For example: Open the People hub and scroll through a list of contacts then select a contact and open the context menu to 'pin to start menu'.

• You can now use the contact as a separate entity on the main start menu.
• If you click on the contact you can edit it or use the contact card to call/email/etc.
• Clicking back on the contact brings you back to the start menu and not into the People Hub.

Similarly, if you pin a game to the start menu, it's because you want to have quick access to the game.

• The user doesn’t expect to be taken to the Games hub when he/she backs out of the game, as they were never there.

This is because the user expects 'back' to take them back to the previous place (back means back).

It is more confusing if 'back' takes you to a page you have not been on i.e. the panorama or home page of the app.

It is important that quality applications follow the same model as the main hub on the device which the user is already familiar with.

Back Button and Search Extensibility

In Mango, applications can use App Connect to extend the Search experience on Windows Phone. With App Connect, users who search the web with the Search button can launch a relevant page in your application from Bing search results. If your app makes use of this feature then you should ensure that when user presses the back button after launching the app from the search results then then he/she should be returned back to the search results and not to the home panorama of the application. For more details on Search Extensibility refer here

Back Button and Very Deep Page Navigation

Very deep page navigations will make it difficult for the user to get back to the main page without restarting the app. For example consider apps which have search option in each page. When user makes a search, it opens a new page with results and provides option for another search. When the search action is performed repeatedly it leads to multiple pages in back stack resulting in a very deep navigation. To prevent such a navigation loop, the application should not provide the search option in the search results page. User must press hardware back button and modify his/her search criteria to initiate a new search.

Back Button and Games

When the Back button is pressed during gameplay, the game can do one of the following

• The game can choose to present a dialog which provides user the option to pause or exit the game. Pressing the back button again should dismiss this dialog.
• Navigate the user to the prior menu screen. Pressing the back button again should continue to return the user to the previous menu or page.

Outside of gameplay, such as within the game's menu system, pressing back button must return to the previous menu or page.

At the game’s initial (start) screen, pressing back button must exit the game.

Back Button and Dialog Boxes

If the current page displays a dialog or context menu, then pressing the Back button must close the menu or dialog and return the user to the screen where the context menu or dialog box was opened. For example refer back button behaviour for the context menu and dialog which pop up on application list page of the native device.

• Tap and hold on any application listed on application page of the phone. A context menu, as in screenshot below, is shown. Press the hardware back button and the context menu gets dismissed.
• Tap and hold on any application listed on application page of the phone. Select “uninstall” from the context menu. A dialog box, as show in screenshot below, is shown. Press the hardware back button and the dialog box gets dismissed.

If the application does not dismiss dialog box or context menu when user presses hardware back button or if the application navigates the user to some page other than the one from which dialog box or context menu was invoked then it an issue.

For more good content on back button and to know few implementation tips please refer a related post here

Written by Amit Jain

While testing applications on Windows Phone we have often come across scenarios where application crashes when user clicks buttons or links in the app in quick succession. These type of crashes generally occur due to two main reasons

1) Controls for user inputs don’t get disabled once user taps on them and until a response has been processed. Example while the app is processing user’s selection choice from the list, it takes some time to process the request and user changes his mind and clicks on another item, or submit button for app is enabled even while the app is signing the user into the application on the first click of the button by the user, like below.

To avoid such crashes, controls that require user action should not be available for the user to interact with again after a user initially interacts with them until a response is posted.

2) Click events are handled when app is being removed from the foreground but before the app completely transitions to deactivated state. This happens when a user interaction causes the app to navigate the user out of the app. An example of this would be when invoking the EmailComposeTask, SmsComposeTask or WebBrowserTask, for instance if the user taps the email link in the below page multiple times in quick succession then the app is likely to crash.

The crash log in this case would resemble something as below

System.InvalidOperationException: Navigation is not allowed when the task is not in the foreground. Error: -2147220990

   at Microsoft.Phone.Shell.Interop.ShellPageManagerNativeMethods.CheckHResult(Int32 hr)

   at Microsoft.Phone.Shell.Interop.ShellPageManager.NavigateToExternalPage(String pageUri, Byte[] args)

   at Microsoft.Phone.Tasks.ChooserHelper.Navigate(Uri appUri, ParameterPropertyBag ppb)

   at Microsoft.Phone.Tasks.EmailComposeTask.Show()

   at AppName.View.SharePage.mailHyperlinkButton_Click(Object sender, RoutedEventArgs e)

   at System.Windows.Controls.Primitives.ButtonBase.OnClick()

   at System.Windows.Controls.HyperlinkButton.OnClick()

   at System.Windows.Controls.Primitives.ButtonBase.OnMouseLeftButtonUp(MouseButtonEventArgs e)

   at System.Windows.Controls.Control.OnMouseLeftButtonUp(Control ctrl, EventArgs e)

   at MS.Internal.JoltHelper.FireEvent(IntPtr unmanagedObj, IntPtr unmanagedObjArgs, Int32 argsTypeIndex, Int32 actualArgsTypeIndex, String eventName)

The happy path is that EmailComposeTask is invoked when user taps the email link, the email dialog opens and the application gets deactivated i.e. sent to the background. However in above case as the email link was tapped multiple times, the second click is being handled after the email dialog is being opened, but before the app moves to deactivated state. Solution is to put a try/catch around the EmailComposeTask and handle the InvalidOperationException.

EmailComposeTask
emailComposeTask = new EmailComposeTask();
emailComposeTask.To = "test@test.com";
emailComposeTask.Subject = "Feedback for wpdps";
try
{
  emailComposeTask.Show();

}

catch(InvalidOperationException)
{
  // can fail if link is pressed twice in quick succession -
  do nothing as the application has already navigated away
}

The above solution also holds good for SmsComposeTask and WebBrowserTask.

Written by Amit Jain

In the first part of this series on Background Audio the Background Audio feature was introduced.

In the second part of the series various ways to pass information between the application and the audio agent were outlined, including how to specify a playlist from the main application that the agent will play.

Where we are now

In this third part of the series we will focus on the challenges when using Background Audio when streaming from a remote server.

Challenges with streaming audio

As discussed in the last blog post, the events that are raised in the app code are not complete and as full as the events raised in agent code. Taking the example of a track coming to an end, the app code only sees the “Unknown” and “Playing” events in its “App Side BackgroundAudioPlayer” object (BAP):

For a non-streaming item being played (e.g. an MP3 in the app’s Isolated Storage) this is not a big issue – to keep the user informed of the brief period before audio starts the app code can watch for the “Playing” event. In the interim it can display an appropriate message or a ProgressBar to the user.

However for streaming audio this becomes trickier. There are several things to watch for:

Handling not being able to play the remote media

Catching the error and stopping the agent from getting into a bad state

In the case of the agent not being able to find the file to play, the “TrackReady” event will not be raised, but OnError() will be called in your agent. This is a challenge as your agent will then need to decipher the error and communicate this back to your app code. Assuming that you can communicate this error back to your app code using a static class called “BackgroundErrorNotifier”, you would need to add the following lines to your agent.

protected override void OnError(BackgroundAudioPlayer player, AudioTrack track, Exception error, bool isFatal)
{
    if (isFatal)
    {
        

BackgroundErrorNotifier.AddError(error);

        Abort();
    }
    else {
        

BackgroundErrorNotifier.AddError(error);

        // force the track to stop 

player.Track = null;

        NotifyComplete();
    }            
}

The BackgroundErrorNotifier.AddError() method would have to use either Isolated Storage or Local Database to communicate back to the app code as discussed in the previous blog post – the details of this aren’t shown here.

The most important thing to note is that you must set player.Track to null. If you don’t do this the agent thinks that there is still a track to play and future calls to agent side BAP’s Play() or Pause() methods will cause the agent to crash. Setting the current track to null puts the agent back in a known good state – however this isn’t implemented for you in the Background Audio project template code.

What does this error mean anyway?

In this case the Exception is always of type System.Exception with an Exception.Message which corresponds to an error code.

There are a few different error messages you can get depending on what actually went wrong, but they need translating from number form into something more useful if you’re going to try and describe to your users what went wrong:

Handling slow communications or low bandwidth

If the server is slow to respond and/or there is only low bandwidth available the “TrackReady” event will be raised after a few seconds, and the data will take a long time to buffer. One of the apps that came through our Depth Partner Support program has exhibited this problem. The server was based in a different continent from where the app was being tested. Under test we were seeing it took 7-8 seconds before “TrackReady” event fired and a further 70 seconds before the audio started playing due to the length of time it was taking for the audio to buffer. Once the buffering had stopped the audio stream was playing fine.

Bear the above in mind if you are expecting users of your application to be using audio streams which are hosted on servers which are physically a long way from them.

In this case once “TrackReady” has been received you know that the Background Audio Zune Media Queue is happy with the file (as otherwise one of the errors described above would have been triggered). That means that there is a valid AudioTrack object that can be used to pass information from agent to the app.

In this scenario you can use the AudioTrack.Tag property string to indicate if the media is buffering or not. Start by setting the Tag to “Buffering” as soon as the track is created and passed back to the agent side player…

private AudioTrack GetNextTrack()
{     // This is an extremely simple agent which plays a single track AudioTrack track = new AudioTrack(
        new Uri(
            "https://traffic.libsyn.com/wpradio/WPRadio_52.mp3"), 
            "WP Radio #52", 
            "WP Radio", 
            "", 
            null);        
    // set buffer flag track.BeginEdit();
    track.Tag = "Buffering";
    track.EndEdit();                                        
    return track;
}

… and then once the agent finally stops buffering change the Tag to “Playing” and the app code can tell the track is *really* playing.

protected override void OnPlayStateChanged(BackgroundAudioPlayer player, AudioTrack track, PlayState playState)
{
    switch (playState)
    {
        case PlayState.TrackEnded:
            player.Track = GetNextTrack();
            break;
        case PlayState.TrackReady:
            player.Play();
            break;
        case PlayState.Shutdown:
            // TODO: Handle the shutdown state here (e.g. save state) break;
        case PlayState.Unknown:
            break;
        case PlayState.Stopped:
            break;
        case PlayState.Paused:
            break;
        case PlayState.Playing:                 
            break;
        case PlayState.BufferingStarted:
            break;
        case PlayState.BufferingStopped:
            track.BeginEdit();
            track.Tag = "Playing";
            track.EndEdit();   
            break;
        case PlayState.Rewinding:
            break;
        case PlayState.FastForwarding:
            break;
    }
    NotifyComplete();
}

A couple of things to watch for:

• firstly you must call BeginEdit() and EndEdit() on the AudioTrack before you modify it.
• secondly I found you need to set an actual string for the Tag, and can’t just use null or the empty string.

Joining this all together in the app code

In the app code, you will clearly only be able to pick up errors and changes in the AudioTrack.Tag property if the app is in the foreground and running. In fact due to the cost of polling for these changes it is only worth checking for errors when the “Now Playing” experience of your app is being shown.

In this final sample, it is assumed that you are implementing your “Now Playing” UI in a dedicated PhoneApplicationPage. That allows you to set up a timer to poll for agent errors and buffering state in OnNavigatedTo. This timer will be stopped in OnNavigatedFrom.

It is assumed that the UI contains a progress bar (progressBar), and a TextBlock for each of the following:

• Track title (txtTitle)
• Track position (txtPosition)

The errors are assumed to be retrieved as a single string from a helper class BackgroundErrorNotifier.GetError()

public partial class NowPlayingPage : PhoneApplicationPage {
    DispatcherTimer playTimer;
    EventHandler playTimerTickEventHandler;
    EventHandler playStateChangedEventHandler;

    public NowPlayingPage()
    {
        InitializeComponent();
        // create timer and event handlers playTimer = new DispatcherTimer();
        playTimer.Interval = TimeSpan.FromMilliseconds(1000);
        playTimerTickEventHandler = new EventHandler(playTimer_Tick);
        playStateChangedEventHandler = new EventHandler(Instance_PlayStateChanged);
    }
    
    protected override void OnNavigatedTo(System.Windows.Navigation.NavigationEventArgs e)
    {
        base.OnNavigatedTo(e);
        // register event handlers and start timer BackgroundAudioPlayer.Instance.PlayStateChanged += playStateChangedEventHandler;
        playTimer.Tick += playTimerTickEventHandler;
        playTimer.Start();

        // force a UI refresh of the current state of the background audio Instance_PlayStateChanged(this, null);            
    }

    protected override void OnNavigatedFrom(System.Windows.Navigation.NavigationEventArgs e)
    {
        // stop timer and unregister event handlers playTimer.Stop();
        playTimer.Tick -= playTimerTickEventHandler;
        BackgroundAudioPlayer.Instance.PlayStateChanged -= playStateChangedEventHandler;
        base.OnNavigatedFrom(e);
    }

    void playTimer_Tick(object sender, EventArgs e)
    {
        // check for errors string errorString = BackgroundErrorNotifier.GetError();
        if (errorString != null)
        {
            MessageBox.Show(errorString, "Audio error", MessageBoxButton.OK);
            progressBar.IsIndeterminate = false;
        }

        // update UI if audio is active var player = BackgroundAudioPlayer.Instance;
        AudioTrack currentTrack = player.Track;
        PlayState bapState = player.PlayerState;
        if ((bapState != PlayState.Unknown)
            && (currentTrack != null))
        {
            TimeSpan position = player.Position;
            txtPosition.Text = position.ToString(@"hh\:mm\:ss");
            if ((bapState == PlayState.Playing) && 
                (currentTrack.Tag == "Buffering"))
            {
                progressBar.IsIndeterminate = true;
            }
            else {
                progressBar.IsIndeterminate = false;
            }                
        }            
    }

    void Instance_PlayStateChanged(object sender, EventArgs e)
    {
        var player = BackgroundAudioPlayer.Instance;
        PlayState bapState = player.PlayerState;
        AudioTrack track = player.Track;
        if (track != null)
        {
            txtTitle.Text = track.Title;
        }
        else {
            txtTitle.Text = "No track information!";
        }
        switch (bapState)
        {
            case PlayState.Unknown:
                break;
            case PlayState.Playing:                    
            default:
                progressBar.IsIndeterminate = false;
                break;
        }
    }

    private void btnPlay_Click(object sender, RoutedEventArgs e)
    {
        var player = BackgroundAudioPlayer.Instance;
        if (player.PlayerState != PlayState.Playing)
        {
            player.Play();
        }
        else {
            player.Pause();
        }
        progressBar.IsIndeterminate = true;
    }

    private void btnNext_Click(object sender, RoutedEventArgs e)
    {
        BackgroundAudioPlayer.Instance.SkipNext();
        progressBar.IsIndeterminate = true;  
    }
}

Conclusion

Background audio is a great addition to the Windows Phone SDK in “Mango”. However as these blog posts have shown some of the implementation details require careful attention in order to get a great user-experience.

Hopefully this blog post series will be useful in helping you achieve that!

Full source code available for download here.

Written by Paul Annetts

The story so far

In the first part of this series on Background Audio the architecture of the Background Audio feature of the phone was introduced. The Marketplace Certification guidelines that are relevant to Background Audio were highlighted. Then a code sample explaining how to integrate with the Music and Videos Hub was presented.

Where we are now

This part of the series will cover the following topics:

• How to specify a playlist
• Playing your audio: what events occur
• Background audio and user feedback in the app

How to specify a playlist and other information

As we will see in more detail later in this blog post audio track information has to be provided from the agent side, not the app UI side of your code. However of course in most cases the app UI will gather information from the user to specify which audio to play. It is therefore inevitable that there needs to be some communication between the app UI and the agent code.

Why is data sharing different for background agents compared with normal apps?

The architecture for background audio application means that the app code and agent code run in different processes and don’t have any common memory where they can place shared C#/VB objects.

The advantage of this approach is that this allows the Windows Phone operating system to treat the background audio app UI part as any other app, with the same app lifecycle.

The OS can then call the background agent when required without needing to start the main app: usually when changing tracks or dealing with input from the Universal Volume Control (UVC). That also means that the OS is free to aggressively shutdown agents once the agent’s piece work is done - or if the agent is taking too long or using too much RAM or CPU for the OS’s liking.

Because of this it is also not possible to predict when the app code and the agent code will run simultaneously so care must be taken when sharing data between the two.

How to pass data between application code and agent

There are several ways to pass or share data between the app code and the agent:

1. You can read properties of the BackgroundAudioPlayer (BAP) object to determine the state of the audio agent and current track position and duration.
2. If the BAP is active for your application (you are playing or paused), then the AudioTrack.Tag property can be used to pass information between app and agent. This is the recommended approach in the Background Agent Best Practices for Windows Phone article on MSDN, however this only works if the background audio is active for your app.
3. Use Isolated Storage.
4. Use Local Database.

Challenges for data sharing

While choosing the right approach, we will face following challenges:

Challenge 1: Detecting when to read updated information sent from agent to the application:

(As discussed above the OS controls when the agent code runs so the reverse problem is not something you can do anything about)

For this there are two possibilities:

1. Use state change events raised in the BackgroundAudioPlayer to read information.
2. Poll the data you’re interested in.

Challenge 2: Avoiding accessing the data store at the same time from app code and agent code

As mentioned above it is possible for app and agent code to run simultaneously and care must be taken to guard against data corruption.

1. Use a Mutex to guard access to Isolated Storage.
2. Local Database is more robust to simultaneous access like this, but make sure to use a different DataContext every time your agent is launched.

How to share code between application code and agent

If you use isolated storage or local database APIs to communicate between app code and agent code you will typically need to share code between the app and the agent.

However care must be taken when doing this:

The agent code must not reference a class library which contains banned APIs (even if these are not called from the agent).

To check whether agents are using banned APIs, you can use the Marketplace Test Kit which checks for common faults in Windows Phone applications.

Playing your audio: what events occur?

Let’s explore how the background audio events are raised – to do this we will go back to the architecture diagram of background audio introduced in the previous blog post.

Remember, the BackgroundAudioPlayer (BAP) object appears to be the same from both the application side and agent side, however we will see there are some important differences in practice when we look at the events that flow from some common usage scenarios. Let’s look at these now:

App startup – check what state BAP is in

In this case no background audio is playing – the first surprise is that the app-side BAP returns “Unknown” state. Clearly there is no need to involve the agent side BAP to check the state of background audio.

Playing a new track

Understanding what is going on in this diagram is critical to understanding how the Background Audio player works. It seems quite complex but it is worth bearing in mind that all of this is implemented for you in the template background audio project. All that remains for the developer is to add their own logic for finding tracks for the agent to play.

Firstly, the app calls the BackgroundAudioPlayer.Instance.Play() method. This will cause the audio agent to start up (and if necessary to load into memory which can clearly be seen if you are using the debugger).

Once loaded the agent code will receive the Play user action – and it should respond by calling the Play method on the agent side BAP.

In response to a Play() request with no track set, the agent side BAP will raise the TrackEnded event on the agent. At this point your agent code should find the next track to play (if it is available). The agent then needs to set the Track property on the agent-side BAP.

Once the BAP has made the track ready to play the agent receives the TrackReady event. In response to this the agent should call Play() to start playback of the new track.

At this point, the app code should receive the Playing event (if it is registered to receive BAP events).

And the audio should start playing – there are a couple of further events on the agent side, BufferingStopped and Playing which are only significant for streaming audio scenarios which will be expanded upon in the next blog post.

Play/Pause during playback

These actions are fairly straightforward as expected.

Skip to next track

Track comes to an end: find new track (no user action)

These diagrams is similar to the initial playback case – when the agent receives the SkipNext user action or TrackEnded event it should find the new track to play, and set the Track property on the agent-side BAP.

However note that there is an Unknown state reported to the app when there is a change of tracks. This creates a potential challenge for the app UI to display the correct currently playing track information.

Background audio and user feedback in the app

The MSDN docs which state that the audio agent gives no guarantee as to how long it will take for a command like Play() to be processed. It could take a few seconds to get the Playing event after the play command (even for non-streaming audio).

This is a challenge in the context of Marketplace Certification requirement 5.1.3

5.1.3 Application Responsiveness

If an application performs an operation that causes the device to appear to be unresponsive for more than three seconds, such as downloading data over a network connection, the application must display a visual progress or busy indicator.

In this case if no steps are taken the user will likely think that the app has ignored the tap which they were expecting to start or pause the audio. In our Depth Partner Support program we have seen a few such applications which use the Background Audio feature which suffer from this.

For good user experience once a play/pause control has been pressed:

• the app should display a ProgressBar in the Indeterminate state immediately to indicate to the user that the app has registered your command. It should turn off the ProgressBar once the Playing/Pausing event has been received.
• the app should disable or “grey out” any controls that will lead to commands to BackgroundAudioPlayer object – if multiple commands are sent these will be queued and this can become tricky to deal with given the delay in response from the BAP, leading to the app code getting in the wrong state or even crashing.

Telling the user the track position

If you are in the “Now Playing” experience of your app you may want to have a control on your page which tells the user the current track location. This can be simply achieved by calling BackgroundAudioPlayer.Instance.Position method in the callback of a DispatcherTimer.

What next?

The next part of this blog series will deal with challenges with streaming audio.

Written by Paul Annetts

Summary

Using background audio for Windows Phone 7.5 is a great way of playing audio content such as internet radio stations, podcasts and music tracks even when your application is no longer in the foreground and when the phone is locked.

This series of blog posts will help you get the most of the capabilities of this new “Mango” feature and to avoid several gotchas associated with it.

What are we covering in these blog posts

This first post will start with some introduction to the Background Audio, how to get started, the Marketplace Certification requirements and how to integrate your background audio app with the Music+Videos Hub on the phone.

The second post will deal with some implementation advice on how to specify a playlist and look in more detail at how a Background Audio app works.

The third post will discuss particular challenges of keeping a great user experience when playing audio files which are streamed from a remote server.

Getting Started with Background Audio

A good first place to look for advice if you’re new to a Windows Phone feature is on MSDN. In particular there is a great overview of background audio here. This includes a code-walkthrough which will get you to create a simple project with a foreground application and a background audio agent which is responsible for providing audio to the Zune Media Queue. The Windows Phone 7.1 SDK sample for background audio can be found here. And the sample for this article series can be downloaded from this location.

This MSDN article also has a good architectural diagram for Background Audio as shown below.

For the purpose of these blog posts, it is assumed that you are writing “Background Audio Playlist Application” rather than the more complex “Background Audio Streaming Application”.

BackgroundAudioPlayer (BAP)

(BackgroundAudioPlayer MSDN class reference link)

As can be seen from the architecture diagram the BackgroundAudioPlayer (BAP) is the key to understanding the background audio feature.

However notice from the diagram that the Application UI code (“app code”) is isolated from the AudioPlayerAgent code (“agent code”), via the Zune Media Queue. This is easy to overlook as from both app code and agent code perspective, it appears they are sharing the same BAP object.

Universal Volume Control (UVC)

The Universal Volume Control (UVC) allows the user to control any audio playing in the background (whether it is from Zune, IE or your app). It allows users to play, pause, rewind, fast-forward and skip and also launch your application for more in-depth control of the audio that is playing. It also displays the current playing track title and author. In the case of the picture of the UVC above it can be seen from the icon before the title that the phone is streaming audio content from a remote server. This streaming icon is automatically added by the phone OS if you are playing from a remote server, rather than playing from your app’s Isolated Storage.

Background Audio Marketplace Certification requirements

As with any other Windows Phone feature it’s worth checking out the Marketplace Certification Requirements early in your development to check what you are allowed to do and what is required of your application which uses a particular feature. The Marketplace certification requirements can be found on MSDN here. For the Background Audio feature, the relevant sections are under “Additional Requirements for Specific Application types”.

Music and Videos Hub integration

Firstly you have a choice to make for your application: should it be registered to the Music and Videos Hub or not? Summarizing this choice focusing on technical issues:

In this series we will focus on music application which implements background audio playback and integrates into Music and Video hub on the phone.

Background Audio Marketplace Certification Requirements

The additional requirements for Background Audio in section 6.9 are fairly straightforward to adhere to if you follow a few key design principles for the Background Audio player.

These aren’t technical issues so we won’t cover them any more in these blog posts – however it is clear that your application design should meet all of these requirements.

Integrating with the Music+Videos Hub on the phone

If you have decided to integrate with the Music+Video hub,  the following MSDN link contains details how to achieve that: “How to: Integrate with the Music and Videos Hub for Windows Phone”.

To summarize this page you will need to:

1. Test the integration on a physical Windows Phone device (the emulator doesn’t have the Music + Videos Hub).
2. Update your Application Manifest file to be able to test the Hub integration.
3. Update the ‘Now Playing’ tile (do this from the background agent when switching between tracks as it’s the only way to keep it accurate)
4. Update the ‘History’ list
5. Update the ‘New’ list

It is worth noting that when providing icons for your audio to the Music + Videos Hub these must be local to the device, and therefore be either part of the application XAP or be found in the application’s Isolated Storage. This ensures that the phone will always be able to show an image in the Music + Videos Hub, even if your device is disconnected from the internet, or if images are not available on a remote server.

Integration between the Music hub and your app’s “playback experience”

A lot of the technical detail you will need to integrate your app and the Music Hub is covered in the MSDN page above, however it is worth expanding on how to achieve the integration between the Music and Video hub and your application’s “playback experience”.

Consider Marketplace Requirement 6.4.2:

When a user taps a tile associated with the application in the History or Now Playing list of the Music + Videos Hub, the application must either (a) launch the playback experience for the content identified in the tile, or (b) launch a view that provides information about the previously played media content and allows the user to resume. The application must not launch to the main or default landing page when the user taps on a content tile in the History, Now Playing, or New list of the Music + Videos Hub.

It is worth breaking down the Now Playing scenario:

1. User initiates playback from the UI
2. The agent code will provide an AudioTrack to the BAP which describes the audio to play. This will be used to set up the UVC and start playback.
3. At the same time the agent code should inform the Music and Videos Hub about the track that is currently playing (and add it to the history).
4. User can at a later time tap the Now Playing tile (or the UVC track title which will use the same information).

If you skip step 3 then your application will launch, but only on the main page, and your app will fail requirement 6.4.2.

To fix this you will need to pass in PlayerContext to the MediaHistoryItem so that you can detect on application launch that this is a special launch from the Music + Videos Hub or the UVC.

For example, for a very simple agent which just plays a single episode of a web radio, and uses a file “Image.png” as the media image to be displayed in the Music + Videos Hub:

protected override void OnPlayStateChanged(
    BackgroundAudioPlayer player,
    AudioTrack track,
    PlayState playState)
{
    switch (playState)
    {
        case PlayState.TrackEnded:
            player.Track = GetNextTrack();
            break;

...

private AudioTrack GetNextTrack()
{
    // set the next track - in this case one hardcoded track
    AudioTrack track = new AudioTrack(
        new Uri("https://traffic.libsyn.com/wpradio/WPRadio_52.mp3"),
        "WP Radio #52",
        "WP Radio",
        "",
        null);
           
    // get the stream of "Image.png" which is in the application XAP as Content
    StreamResourceInfo sri = Application.GetResourceStream(
        new Uri("Image.png", UriKind.Relative));
    using (Stream imageStream = sri.Stream)
    {
        MediaHistoryItem nowPlayingItem = new MediaHistoryItem();
        nowPlayingItem.Title = track.Title;
        nowPlayingItem.PlayerContext.Add("LaunchNowPlaying", "true");
        nowPlayingItem.ImageStream = imageStream;
        MediaHistory.Instance.NowPlaying = nowPlayingItem;

        // reuse the same image stream for recent item, need to reset it first however
        imageStream.Seek(0, SeekOrigin.Begin);
        MediaHistoryItem recentItem = new MediaHistoryItem();
        recentItem.Title = track.Title;
        recentItem.PlayerContext.Add("LaunchRecentItem", "1");  // put an ID of the recent item to add
        recentItem.ImageStream = imageStream;
        MediaHistory.Instance.WriteRecentPlay(recentItem); 
    }
    return track;
}

To complete the integration, in main application’s initial page code-behind (e.g. MainPage.xaml.cs) you need to detect that the application was launched from the Music + Videos Hub or the UVC. Here is a simple example which works with the PlayerContext set in the agent code sample above.

protected override void OnNavigatedTo(System.Windows.Navigation.NavigationEventArgs e)
{
    var queryString = NavigationContext.QueryString;
    string queryStringValue;
    if (queryString.TryGetValue("LaunchNowPlaying", out queryStringValue))
    {
        MessageBox.Show("LaunchNowPlaying is " + queryStringValue, 
            "Launch from UVC / Hub Now Playing!", 
            MessageBoxButton.OK);
        // TODO: navigate to "Now Playing" experience }
    else if (queryString.TryGetValue("LaunchRecentItem", out queryStringValue))
    {
        MessageBox.Show("LaunchRecentItem is " + queryStringValue,
            "Launch from Hub Recent item",
            MessageBoxButton.OK);
        // TODO: Find the item specified, start playing it, navigate to "Now Playing" experience }
    else {
        MessageBox.Show("Normal launch", "Normal launch", MessageBoxButton.OK);
    }
}

In an application using the MVVM pattern you should pass down the navigation query string from the View to the ViewModel in a message – this will stop you having too much application logic in the View class.

What next

This blog post explained the principles needed to implement a Background Audio agent which will meet the Marketplace Certification requirements and will be integrated to the Music and Videos Hub on the phone.

The next blog post in this series will tackle further implementation strategies for a background audio player application.

Written by Paul Annetts

In this blog post we’ll review three of the most common errors seen by developers when submitting their applications to App Hub. The errors are:

Error: "An update cannot support fewer languages than the previous app instance supported (1047)"

Error: “The [NeutralResourcesLanguage] attribute is missing on the entry assembly. (2003)”.

Error: “An error occurred connecting to the server”.

When you submit your application to App Hub, it is immediately run through a series of static tests. If your application passes these tests, App Hub will navigate to the next step in the submission process. If it fails, you will see the static validation error message(s), for example:

Some of the tests done by App Hub are the very same tests you can and should do yourself using the Marketplace Test Kit. The Marketplace Test Kit is installed as a Visual Studio extension when installing the Windows Phone SDK. You can start it by right clicking on your project and selecting ‘Marketplace Test Kit’.

Error: "An update cannot support fewer languages than the previous app instance supported (1047)"

One of the static tests not run by the Marketplace Test Kit is for application update language consistency. When you update an application, your update must contain at least the same languages supported by the original. This applies even if your application is not localized. That is, you can add to the number of languages supported, but you cannot remove languages. One side effect of this requirement is that many developers have hit the error, "An update cannot support fewer languages than the previous app instance supported (1047)". This error is often caused by an incorrect English setting. In App Hub there are two English locale groups, North American English and International English. (See here for more information: https://forums.create.msdn.com/forums/t/87638.aspx). North American English includes Canadian English and American English. All other ‘English’ languages fall under International English. You will get this error if you update an application that was designated as North American English originally and was updated as International English.

So how is the language specified? The language is specified in your project settings. Note that all applications must specify a neutral language or your app will fail the static test with the error: “The [NeutralResourcesLanguage] attribute is missing on the entry assembly. (2003)”. This is the ‘Neutral Language’ assembly setting in Project settings as shown below.

1. Right Click on your project in Solution Explorer

2. Application | Assembly Information. . .

3. Neutral Language

4. Pick a specific default language. For example for English:

In the above example, the neutral language is ‘English’. English without any modifier, is interpreted as ‘International English’ by App Hub.

The July 2011 Marketplace Update. If you are updating a 7.0 application that was published prior to July 2011, you may run into the ‘fewer languages’ error since applications were not required to specify a default language. The default language was specified by the developer in App Hub. This setting is now automatic. For example, your 1.0 version may be specified as North American English. Therefore, in your update, the neutral language should be specified as

English (Canada)          [assembly: NeutralResourcesLanguage("en-ca")]

or

English (United States)  [assembly: NeutralResourcesLanguage("en-us")]

If specified as [assembly: NeutralResourcesLanguage("en")], you will see the error, "An update cannot support fewer languages than the previous app instance supported (1047)". This is because ‘en’ denotes International English and your update is North American English. Note that English is the only language divided into two groups within App Hub.

You can also see the 'fewer languages' error, if you have a custom build step which uses a macro to modify the AssemblyInfo.cs file. For example: [assembly: NeutralResourcesLanguage("$currentVsCulture$")]

Error: “An error occurred connecting to the server”.

You may see this error while uploading your XAP file to App Hub and any of the following are true:

1. Your XAP filename has a period in it. For example: My.App.XAP.
2. Your application contains support for languages which are not supported, or are not properly specified. For example, the Arabic and Hindi languages are currently not supported. Submitting an app with these resources, will generate this error.
3. The neutral language set to one that is not supported by Windows Phone. For example, setting the neutral language to ‘et’ (Estonian) which is not supported in Windows Phone. Here’s a list of the supported languages updated for Windows Phone 7.5: https://msdn.microsoft.com/en-us/library/hh202918

Note that in a future update of App Hub, this error message will more accurately reflect the cause of the error.

Written by Mike Francis

A common problem in Windows Phone app design is the poor use of touch targets, i.e. the area of the screen which responds to user interaction (usually a tap). When designing on the emulator, this is easy to overlook as the mouse gives a very precise ‘touch’. However, when the application is run on a device the user’s finger or thumb is normally used to tap on the screen. This is the ‘fat finger’ problem and can mean that items are difficult to hit accurately (user accidentally taps the item next to the desired one) or items that can be tapped on don’t always respond.

SIZE AND SPACING

When touch targets are very small and close together, the user has to take care when tapping to make sure that they accurately hit the item they want. This can be very frustrating and slows down the interaction with the app.

For more detailed guidance for designing touch targets, visit Interactions and Usability with Windows Phone.
However, here is a simple walk-through you can try out yourself for an idea of how this works in practice.

Let’s use the ListPicker control from the Silverlight Toolkit for Windows Phone as an example.
On the left is the full screen view where the list uses default TextBlocks to display the items. On the right is the same list, but this time with the FontSize set to “40” and the Margin set to “0,12”.

Here’s the code for the ListPicker:

While items in both lists are easy to hit with a mouse on the emulator, the list items on the right are much easier to tap accurately on the device. Test this by holding the device in one hand and using your thumb to pick from the list.

SCOPE

Sometimes when tapping on items in a list the application does not respond. Despite the item itself appearing large enough to be an easy hit target, in practice the user has to tap several times to get the item to action.

The simple rule is to place the tap event at the highest meaningful control level. Let's look at an example. Suppose our list item uses the following code:

This means only a small part of the ListBoxItem is actually listening for the tap event, but this is not obvious to the user. The red boxed area below shows the part of the item the user has to tap on:

To make the list items feel more responsive, move the tap event up to the top level component of the ListBoxItem:

This now means the tap event now more closely matches the visual area of the list item as shown in red below:

This can apply to other areas too. The image on the right is a sample contact from the People hub, again with red boxes to mark out the touch target area for each key/value pair. Here the tap action does not only apply to the contact detail, instead the touch target area extends to include the associated heading.

By carefully considering the best size, spacing and scope for the tap event, the application will feel more responsive and easier to use.

Written by Fiona Bell

When an application enters the dormant state, the OS will take away certain system resources from the application. For instance, the camera resource is exclusive and it will be made available for other applications. But what happens when your application is reactivated? The OS will try to return the resources to your application wherever possible. The tricky bit is that some resource types will be returned to your application seamlessly and some resources will have to be reclaimed by the application itself. See list below.

I want to specifically call out networking, because almost all applications are connected nowadays and that’s where the first bugs can often be found when implementing fast application switching.

Networking

For example, let's explore what happens to a WebClient during a fast application switch. We already know that after FAS, the application’s state is retained and objects remain instantiated. Similarly, the WebClient object and its event handlers remain wired up. The only trouble is that during FAS, our network calls will get cancelled. The good news is, this is easy to detect. After the application is reactivated, the WebClient will be notified about the network request cancellation. In particular, the WebClient’s “Completed” handler will be triggered with “Cancelled” flag set. To get your application going again, re-issue the WebClient request and that’s it, your application now supports fast application switching.

Note that the application has to re-issue only network requests made explicitly. Silverlight controls that use network behind the scenes will download the content correctly. For instance <Image> control pointing to an http source will seamlessly complete image download after fast application switching.

Detecting cancelled WebClient request

Detecting cancelled HttpWebRequest

Tips for implementing and testing fast app switching with networking:

• Distinguish between no network availability and a cancelled network request due to fast app switch. Quite often applications incorrectly show error messages that the network is not available; instead the applications should re-issue the network request.
• Do not show any popups or MessageBoxes, fast application switching is not an error state.
• In cases where an action is triggered by a user and the application is unable to complete the user’s request, inform the user with an error message. For instance, the user is sending a message and the device moves to an area without network coverage. Please do inform the user that the transaction couldn’t be completed. (The reason for failure is no network coverage, not fast app switching)
• On the contrary, upon successful message delivery, no confirmation would be shown to user. It is expected that all actions will complete successfully.

Example step-by-step FAS testcase

Imagine phone application accessing an online store. User can browse products using his Windows Phone 7 application. A FAS testcase can go like this: 

1. Tap on Electronics section of the online store
2. As soon as “Loading…” starts, press the Start button on Windows Phone
3. Wait a second and press hardware back button to return to the application

Commonly observed bug:
No results found or the application throws an exception

Expected result:
List of products in electronics section is loaded when user returns to the application

Resources

Get Ready for Fast Application Switching in Windows Phone

Written by  Petr Sedlacek

Aside from knowing our RenRens and Immowelts from our Magic Seaweeds and Univisions, we’ve also noticed some common issues that many partners fall foul of when they submit their designs to us for review.

The good news is they’re easy to fix.

So here are the top three issues we see at design review. Please have a look through these and check your apps to make sure they don’t suffer from these design no-nos before you send your docs on for review.

Alignment and spacing

This is an easy one. Everyone can tell if something isn’t properly aligned. In fact, if you’re not sure, you can do something as simple as attaching a sticky note to your monitor or mobile screen and see if everything lines up. As a general rule, everything in Windows Phone should be left aligned.

For those of you who prefer some more concrete guidance, the default page margins we suggest are 24 pixels from the left and right of the page. List items should be spaced 12 pixels apart, both horizontally and vertically. You should space controls either 12 or 24 pixels apart (or a multiple thereof). Use whichever looks best.

You can download Photoshop templates with the grid on them from https://go.microsoft.com/fwlink/?LinkId=196225

Back, close, cancel buttons

As every Windows Phone ships with a handy hardware back button, you don’t need to create your own just to take up space on the screen. Plus, why bother with all the hassle of managing the back stack yourself?

People will use the back button:

· To navigate backwards

· To dismiss a dialog

· To cancel

So if you’ve got buttons on the UI that perform those functions, you might as well scoop them out!

There’s an exception to cancelling a process though, and I use the word process carefully. In this context I mean a discrete process that has a very obvious beginning and end, such as the checkout process of a shopping experience. You’ve tapped the checkout button, entered a shipping address, pressed next, entered a billing address, pressed next, entered payment details, and pressed confirm. The process has completed.

Normally you’d use the back button to navigate within this process. But say you were at the payment details screen and wanted to cancel the process to go back and add another product to your basket. Rather than making the user press back a bunch of times, we would recommend they use a cancel button which cancels the checkout process and drops them back at the basket. The whole checkout process would then need to be removed from the backstack. If this is something you want to do, then the cancel button should not be visible on the first page of the process (because the user can just as quickly tap the back button), but should appear on subsequent pages.

Mixing metaphors

If you see this button, what do you expect it to do?

The chances are you said ‘play’. That’s a reasonable assumption. Wherever you see this icon in Windows Phone, it always means play and tapping it always plays media. Effectively, you’re used to this being a metaphor for playing media. If you saw that icon and tapping it didn’t play media, it would be confusing, right?

We often see this being used to mean ‘next’. In Windows Phone, we use this icon for next:

Both of these icons have shipped with the Silverlight Toolkit for Windows Phone (which can be downloaded here: https://silverlight.codeplex.com) and can be found on your hard disk here: C:\Program Files (x86)\Microsoft SDKs\Windows Phone\v7.x\Icons on 64bit Windows, or C:\Program Files\Microsoft SDKs\Windows Phone\v7.1\Icons on 32bit Windows.

We’ve seen a load of apps that mix up what the icons mean just because it’s easier to reuse an existing icon than it is to create one appropriate for the use case. Please don’t do this. There are plenty of resources online, and using a more accurate icon will make for a much nicer experience, and your users will thank you for that.

Written by Dave Crawford