Windows Phone Developer Blog

Windows Phone 8 XAML LongListSelector

2013-05-23T19:47:22Z

This blog post was authored by Rohan Thakkar, a Program Manager on the Windows Phone team.

- Adam

Last year we evangelized the use of the LongListSelector control to provide smooth infinite scrolling scenarios. The LongListSelector control is so useful that we decided to enhance it and move it to the SDK for Windows Phone 8. In this post we discuss the improvements we’ve made to the control, and provide a mapping guide for Windows Phone developers who are already using the Windows Phone Toolkit 7.1 version of the LongListSelector.

If you prefer to read XAML instead of plain text, you can go straight to the samples and explore them:

For more info about how to use the LongListSelector, see How to display data in a grouped list in LongListSelector for Windows Phone 8.

Let’s dig a little deeper into various enhancements we’ve made to the control. Skip to the sections that interest you.

LongListSelector moved to Windows Phone 8 SDK and to ROM

The LongListSelector control is now a part of Microsoft.Phone.Controls namespace in Microsoft.Phone.Controls.dll assembly. This means it’s now a fully supported, high-quality control shipped by the Windows Phone Development team. We also moved the assembly to ROM to take advantage of the internal off-thread input and the render thread architecture. This means the control is optimized for the full potential of Windows Phone.

The Microsoft.Phone.Controls.dll assembly also contains other phone-specific controls, such as Panorama and Pivot. These controls also get the performance benefits of being in ROM, including reduced memory consumption (~50% reduced memory for a basic app) and improved touch performance, especially when you have data being loaded in the panorama view.

Sticky headers

The native Windows Phone grouped list has the headers stick to the top as you scroll. The LongListSelector control in Windows Phone 8 has the same smooth effect.

Note the headers in the following screenshots.

Figure 1 - Notice group header "a"

Figure 2 - Scrolling up, notice how "a" sticks to top

Figure 3 - Notice how the group header "b" pushes "a"

Figure 4 - Now "b" is sticky, same as "a"

Grouped grid layout

In Windows Phone 8, LongListSelector supports grid layout, which is more than just the WrapPanel that’s available in the Windows Phone Toolkit. The LongListSelector grid layout is virtualized, which provides better performance. The following screenshots are from the PhotoHub sample.

Figure 5 - LongListSelector's Grid layout

Figure 6 - Jumplist's List layout.

The following code is an excerpt of the XAML for the LongListSelector from the PhotoHub sample.

C#
 <phone:PhoneApplicationPage.Resources>
 <phone: JumpListItemBackgroundConverter x:Key="BackgroundConverter"/>
        <phone:JumpListItemForegroundConverter x:Key="ForegroundConverter"/>
 
        <Style x:Key="JumpListStyle" TargetType="phone:LongListSelector">
            <Setter Property="LayoutMode" Value="List" />
            <Setter Property="Margin" Value="12,12,0,0"/>
            <Setter Property="ItemTemplate">
                <Setter.Value>
                    <DataTemplate>
                        <Border Background="{Binding Converter={StaticResource BackgroundConverter}}" 
                            Width="470" 
                            Height="70" 
                            Margin="6">
                            <TextBlock Text="{Binding Key}"
                                Foreground="{Binding Converter= {StaticResource ForegroundConverter}}"
                                Font Family="{StaticResource PhoneFontFamilySemiBold}"
                                  FontSize="28"
                                Padding="2"
                                VerticalAlignment="Bottom"/>
                        </Border>
                    </DataTemplate>
                </Setter.Value>
            </Setter>
        </Style>
</phone:PhoneApplicationPage.Resources>
<phone:LongListSelector Name="PhotoHubLLS" Margin="13,-30,0,0"
    ItemsSource="{Binding GroupedPhotos}"
                         ItemTemplate="{StaticResource ItemTemplate}"
    GroupHeaderTemplate="{StaticResource GroupHeader}"
    JumpListStyle="{StaticResource JumpListStyle}" 
    IsGroupingEnabled="True"
    LayoutMode="Grid" 
    GridCellSize="108,108"/>
 

Let’s look at some examples of interesting properties found in this code.

LayoutMode – Indicates whether the collection in the context should be displayed as a list or as a grid. In the preceding XAML example, LayoutMode is set to Grid as a property on the LongListSelector, and set to List as a property on JumpListStyle.

JumpListStyle – Provides the style for the jump list items.

GridCellSize – Indicates the size of each cell in the grid. This property has to be set on the LongListSelector or the JumpListStyle wherever the grid layout is to be rendered.

Converters - Note that the JumpListItemBackgroundConverter and JumpListItemForegroundConverter are needed to convert the foreground and background colors of the jump list item (group header of a group) whether or not it has items in the group. These converters also are part of the SDK and are in the same Microsoft.Phone.Controls namespace.

Figure 7 - Value converters shading empty group jump list items

The default foreground and background colors match the first-party app. You can customize it to align with your design needs using the Enabled and Disabled properties as shown here:

XAML
 <phone:JumpListItemBackgroundConverter Disabled="Bisque" Enabled="Aqua" x:Key="BackgroundConverter"/>
<phone:JumpListItemForegroundConverter Disabled="Azure" Enabled="BlueViolet" x:Key="ForegroundConverter"/>
 

Improvements to infinite scrolling scenarios

Earlier we spoke about infinite scrolling for the Windows Phone Toolkit 7.1 LongListSelector. As you approach the end of the visible list when scrolling, the LongListSelector automatically fetches more items and adds them to the list, which gives you a sense of infinite scrolling. We made this scenario simple to implement in Windows Phone 8. The following code from the Twitter Search sample demonstrates how easy it is to implement:

XAML
 <phone:LongListSelector Name="resultList" Grid.Row="1" 
    DataContext="{StaticResource viewModel}" 
    ItemTemplate="{StaticResource ResultItemTemplate}" 
    ItemsSource="{Binding TwitterCollection}" 
    ListFooter="{Binding}" 
    ItemRealized="resultList_ItemRealized"/>
 

C#
 void resultList_ItemRealized(object sender, ItemRealizationEventArgs e)
{
    if (!_viewModel.IsLoading && resultList.ItemsSource != null && resultList.ItemsSource.Count >= _offsetKnob)
    {
        if (e.ItemKind == LongListSelectorItemKind.Item)
        {
            if ((e.Container.Content as TwitterSearchResult).Equals(resultList.ItemsSource[resultList.ItemsSource.Count - _offsetKnob]))
            {
                _viewModel.LoadPage(_searchTerm, _pageNumber++);
            }
        }
    }
} 
 

The ItemRealized event is raised every time a LongListSelector item acquires a UI container to be displayed on the screen. In other words, every time an item enters the UI buffers above or below the current viewport, the ItemRealized event is raised. The event argument property ItemKind indicates whether the UI container is an Item, ListHeader, GroupHeader, or ListFooter. Using the property Container.Content you can get the actual object associated with the UI container that was realized. This way you can monitor the objects within the UI container buffer.

Note how the app code in this example contains a private variable _offsetKnob. This helps fine-tune the LongListSelector scrolling experience by helping to determine when to load more items depending on how heavy your item template is, or on how slow the response is from the service sending the data.

Globalization – SortedLocaleGrouping

When you group contacts in alphabetical order, you want to do this in all languages. You could provide your own globalized, sorted alphabet characters for group headers. However, using your own alphabet strings will not guarantee 100% matching with the phone first-party contacts list. So we introduced a class called SortedLocaleGrouping that provides a set of alphabets that are the same as those used by the first party. In the PeopleHub sample, SortedLocaleGrouping (from Microsoft.Phone.Globalization namespace) is used in one of the helper types, AlphaKeyGroup (which also is very highly recommended).

You get the group display names by using the SortedLocaleGrouping.GetGroupDisplayNames property to populate your groups. Then use the GetGroupIndex method to classify your contacts list.

SupportsPhonetics property

This is a unique property and we have included it in SortedLocaleGrouping. In some cultures, such as ja-JP, last names are written in a different script and are pronounced differently depending on the region or background.

Here’s an example:

String of LastName	Yomi/Pronunciation	Group based on Yomi	Group without Yomi
新井 (display string)	Nii --> にいい (in Hiragana) or ニイイ (in Katakana)	ナ	The Globe icon
	Arai --> あらい (in Hiragana) or アライ (in Katakana)	ア	The Globe icon
	Shinkyo --> しんきょ (in Hiragana) or シンキョ (in Katakana)	サ	The Globe icon

This is a common phenomenon catching on in different cultures, and the first-party contacts list will be grouped based on the Yomi that is passed in. If no Yomi is passed in, it will return the default, same group (equivalent to other or globe).

You usually would use the SupportsPhonetics property when classifying the contacts into groups and if you have the Yomi (pronunciation) database that you can access via a service or other means for the specific culture. The code between the //EXAMPLE comments in the following example is from one of the helper methods that shows how you would use it if you have a database of the pronunciations (Yomi) for various names.

C#
 /// <summary>
/// Create a list of AlphaGroup<T> with keys set by a SortedLocaleGrouping.
/// </summary>
/// <param name="items">The items to place in the groups.</param>
/// <param name="ci">The CultureInfo to group and sort by.</param>
/// <param name="getKey">A delegate to get the key from an item.</param>
/// <param name="sort">Will sort the data if true.</param>
/// <returns>An items source for a LongListSelector</returns>
public static List<AlphaKeyGroup<T>> CreateGroups(IEnumerable<T> items, CultureInfo ci, Func<T, string> keySelector, bool sort)
{
    SortedLocaleGrouping slg = new SortedLocaleGrouping(ci);
    List<AlphaKeyGroup<T>> list = CreateDefaultGroups(slg);
 
    foreach (T item in items)
    {
        int index = 0;
        // EXAMPLE
        if (slg.SupportsPhonetics)
        {
            //check if your database has Yomi string for item
            //if it does not, then do you want to generate Yomi or ask the user for this item.
            index = slg.GetGroupIndex(Yomiof(item));
        }
        // EXAMPLE
        else
        {
            index = slg.GetGroupIndex(keySelector(item));
        }
 
        if (index >= 0 && index < list.Count)
        {
            list[index].Add(item);
        }
    }
 
    if (sort)
    {
        foreach (AlphaKeyGroup<T> group in list)
        {
            group.Sort((c0, c1) => { return ci.CompareInfo.Compare(keySelector(c0), keySelector(c1)); });
        }
    }
 
    return list;
}
 

LongListSelector mapping guide – Differences between Windows Phone Toolkit 7.1 and Windows Phone 8.0 SDK

We modified and enhanced the Windows Phone Toolkit LongListSelector. In this section we briefly outline what has changed.

Properties modified from the Windows Phone Toolkit 7.1

Deleted

BufferSize
IsBouncy
IsScrolling
MaximumFlickVelocity
ShowListFooter/ShowListHeader

Modified

Windows Phone Toolkit 7.1	Windows Phone 8 ROM SDK
DisplayAllGroups Display all groups in the list whether or not they have items. Default is true.	HideEmptyGroups Hide all groups in the list without items. Default is false.
GroupItemTemplate	JumpListStyle
IsFlatList Gets or sets whether the list is flat instead of a group hierarchy. Default is true.	IsGroupingEnabled Gets or sets whether the list is flat instead of a group hierarchy. Default is false.

New concepts

GridCellSize
LayoutMode LongListSelectorLayoutMode { List, Grid };
ManipulationState
C#
1. public enum ManipulationState
2. {
3. Idle, // nothing is manipulating or animating
4. Manipulating, // Gesture is being recognized, finger is down and any delta is received, drag/pan or flick
5. Animating //No Gesture is currently happening, but there is some animation happening, like scroll animation or compression animation
6. }

Methods modified from the Windows Phone Toolkit 7.1

Deleted

AnimateTo(object item)
CloseGroupView()
DisplayGroupView()
GetItemsInView()
GetItemsWithContainers(bool onlyItemsInView, bool getContainers)
ScrollToGroup(object group)

Events modified from the Windows Phone Toolkit 7.1

Deleted

StretchingBottom
StretchingCompleted
StretchingTop

Modified

Windows Phone Toolkit 7.1

Windows Phone 8 ROM SDK

ScrollingCompleted

ScrollingStarted

ManipulationStateChanged

(coupled with ManipulationState property)

Link/Unlink

ItemRealized/ ItemUnrealized

With EventArgs including ItemKind

C#
 public class ItemRealizationEventArgs : EventArgs
{
    /// <summary>
    /// The ContentPresenter which is displaying the item.
    /// </summary>
    public ContentPresenter Container { get; }
 
    /// <summary>
    /// Gets the kind of item that is realized
    /// </summary>
    public LongListSelectorItemKind ItemKind { get; }
 
}
/// <summary>
/// Different kinds of items that exists in LongListSelector
/// </summary>
enum LongListSelectorItemKind
{
    ListHeader,
    GroupHeader,
    Item,
    GroupFooter,
    ListFooter
} 
 

FAQ

Why use IList instead of IEnumerable for ItemsSource?

You have to know how many elements there are and there is no Count property on IEnumerable. You also have to be able to access the items by index, not just in the forward-only, one-at-a-time way that enumerators do. If ItemsSource accepted IEnumerables or an IEnumerable of IEnumerables, you’d have to convert them to lists internally using the default method of iterating over every single item. This conversion would rule out data virtualization, which could cause poor performance without the app author knowing why. Worse yet, the author might think that it is the status quo and simply accept a longer start time. This was one of the complaints about the original toolkit LongListSelector. Now, if an app author has only an IEnumerable set of data, the developer can simply call ToList() for the default conversion to an IList but the developer also has the flexibility provide their own IList implementation.

Is LongListSelector recommended instead of ListBox?

Yes! We have designed the LongListSelector specifically for phone scenarios and we encourage people to use the LongListSelector instead of ListBox for phone apps.

Testing your Windows Phone app – Part 2

2013-05-21T20:07:00Z

This blog post was authored by Craig Horsfield, a Senior SDET on the Windows Phone Test and Operations team.

- Adam

Testing your app throughout the development process can help you create a really great Windows Phone app. Testing helps ensure that your app is effectively represented in the Windows Phone Store as an app that offers Windows Phone users a high level of performance and quality. A small investment in the key areas described in this post can help you bypass common errors early in the development process, and help you get positive results in the long term. This post is part 2 of a 3-part series that outlines key test areas that you should consider before submitting your app to the Store. See part 1 for additional details.

Push notification and Live Tiles

Live Tiles

Live Tiles are updated through push notification or through an app’s periodic background agent. When testing these areas, you should accelerate the update time so that you can test more rapidly. For more info, see Tiles for Windows Phone.

Test scenario	Details
1. Verify that your Live Tile updates.	Verify that the Live Tile updates after it has been pinned to Start.
2. Verify that your Live Tile stops updating.	If this setting is disabled in the app, make sure the Live Tile stops updating.
3. Verify that the Live Tile updates via a periodic agent.	If the Live Tile is updated via a periodic agent, verify the update on all network types, and verify that the Live Tile updates when there is no network, for example, in Airplane mode.
4. Verify that the Live Tile is working and present after an app upgrade.	None.
5. Verify that the Live Tile is working and present after an app upgrade and subsequent restarting the device.	If updating the app, make sure that you don’t change the TokenID in the WMAppManifest.xml file. This results in your Live Tile being removed from Start when the device is restarted.
6. If using a background agent, verify that the agent doesn’t crash or terminate.	This results in disabling the agent and Tile updates will fail.

Notifications

Apps that use notifications normally are used within background agents. Test these notifications to ensure that they work properly. For more info, see Notifications for Windows Phone.

Test scenario	Details
1. Verify that notifications are received.	None.
2. Verify what happens when you tap the notification.	Tapping the notification launches the user into the app in the correct state.
3. Verify that the app doesn’t overuse toast notifications.	None.

Agents

Background agents provide key abilities for an app, but they also introduce some specific test considerations. Agents can be disabled and enabled in the phone’s settings, on the Settings > Application > Background Tasks screen. The app needs to be aware of the state of the agent. Resources available to agents also are restricted. A key point to remember is that when running in the debugger, these restrictions are not enforced so it’s important to test your app outside of the debugger and track the resource that it is using. For more info, see Background agents for Windows Phone.

Test scenario	Details
1. Verify initial app start.	The agent starts when it’s needed.
2. Verify that the app handles state in which the agent has been disabled by the user in Settings\Application\Background Tasks.	Additionally, verify that the app performs as follows: App notifies the user that it’s not available and continues to work as expected. App notifies that the agent is needed and re-enables it.
3. Agents are disabled in low-battery conditions - test that the app can handle these states.	None.
4. Agents that crash or are terminated by the OS for exceeding resources, on two successive crashes will be disabled. Ensure your app handles this state.	In this state the foreground app has to reschedule the agent. This state can be queried from the agent API. For more info, see Background agent best practices for Windows Phone.
5. Resource-intensive agent only runs when on power and Wi-Fi. Ensure app handles this correctly.	None.
6. Verify that the agent stays below the required CPU and memory caps.	None.

This table lists the required CPU and memory caps, by agent on Windows Phone 8:

Agent	CPU	Memory
CBE	10%	N/A
GBA	10%	11 MB
BAP	10%	20 MB
FA	5%	10 MB
VoIP agent	20%	60 MB

Media, audio, and video

Media, audio, and video throughout your app should be tested. Consider these test scenarios in the table below. For more info, see Media for Windows Phone.

Test scenario	Details
1. Preserve audio state.	If your app plays an audio sound (clip) when it starts, your app should not pause the currently playing audio. The app should preserve and not interfere with the currently audio playing on the device. If your app plays back audio content from a background agent or a foreground app, your app should pause any currently playing audio.
2. Verify the Universal Audio Control during audio playback.	Verify Play. Verify Pause / Resume. Verify Skip Next / Skip Previous. Skip to last and back to the first track, etc. Some apps may take time to process these calls. Verify that the UI is set to disabled while the app is processing these calls to prevent multiple invokes. Verify volume controls. Audio continues under lock. Audio continues when app is on the back stack. Verify all expected codecsthat the app offers can be played back. Track info is displayed in the UI.
3. Verify audio playback via a background audio agent.	Test all of the above test cases. Audio continues when the app is terminated but the background agent is allowed to continue. Audio continues to play when device screen is locked. App agent remains below the app 20-MB cap.
4. Media Source	Verify media from a network stream. Verify media from the app’s ISO store. Verify media playing from the media library on the phone. (This case requires the correct capability in the app manifest.)
5. Video playback	Verify all states: Play from start Pause, resume Skip forward and back Change states rapidly
6. S-Video playback in FAS scenarios	On navigate away event, the app needs to record the current media stream location. Play media stream return to the phone start page and then switch back to the app. Verify the stream is preserved, should continue from the previous point. Play media stream and force the app to tombstone via Visual Studio. In this case, the app should continue from previous point but will have to load the stream and forward it to the location saved in navigate away and deactivated events.
7. Bandwidth	Verify media stream playback on different networks and bandwidth. App should adjust playback quality and codec as need. Verify network dropped scenario and the app handles this and informs the user correctly. Visual studio phone emulator can manipulate the network quality and type to aid in this testing.
8. Media hub integration	Verify app is visible in the Media hub, manifest must have HubType=1. App has to use MediaHistory and MediaHistoryItemclasses in this scenario. Verify post market place ingestion where the correct capabilities are set on the app manifest to enable it in the hub. (Use the App Beta submission process to test this.) App must update the, ‘now playing’ tile, ‘history’ and ‘new’ list. Verify app plays correct stream when launched from history or new list.
9. FM Radio	App is not compatible with all hardware and versions of Windows Phone. Test app on the correct platform. Verify that app sets the correct region based on the phone location; this enables the correct frequency stepping. If incorrect it will not tune well or find stations. Set the correct power modes. For example, verify that the user is not playing media from the FM radio, then set RadioPowerMode to off.

Geolocation

With Windows Phone 8, you can create apps that use info about the phone’s physical location. Scenarios for location-aware apps include checking the user into a web service using the user’s instantaneous location, and tracking the user’s location as it changes over a period of time. The location data the phone provides comes from multiple sources, including GPS, Wi-Fi, and cellular. The visual studio phone emulator can be used to simulate these location changes. The location can be moved manually or simulate a sequence of location changes. For more info, see Location for Windows Phone 8.

Test scenario	Details
1. Prevent PositionChange events from firing too often and placing CPU processing load on the app.	Set the MovementThreshold property to the appropriate value for the app needs and make sure that events fire only outside of that threshold.
2. Handle the unknown location state.	Ensure the app can handle NA values. Test the app when it has no location state.
3. Test a large change in location data so that any internal calculations in the app do not fail in these cases.	For example, position changes greater than 1 degree. This can happen if the phone has had no valid location data for some period of time.
4. Test app in all hemispheres: North/South and West/East.	Ensure that your calculations on negative degree values are correct.
5. Test 0-degree and 180-degree location for longitude and latitude.	None.

Design considerations when using location:

Test scenario	Details
1. Use a lower level of accuracy to save on battery power if applicable.	None.
2. Check the Position.Location.IsUnknown and GeoPositionStatus properties to ensure that the location is valid.	None.

Resource usage and performance

Windows Phone apps need to be designed to efficiently use and preserve the limited resources of the phone platform. You want to design your apps to use the least possible CPU cycles, to access networks efficiently and purposefully, and to make the best use of visual components—graphics, bright colors, and themes use more power than a simpler UI.

Test areas to consider:

Test scenario	Details
1. Check for a nonresponsive or jerky UI.	This could be caused by long-running activity on the UI thread.
1. Check for Memory leaks – repeat scenarios multiple times to detect memory leaks during specific sequences.	Repeat page navigation could increase app memory.
2. Check for rapid battery drain.	Can be caused by using the app for long periods of time.

Tips and tools:

The Visual Studio app profiler, on the debug menu, is a key tool for looking into app memory and CPU usage.
Using the EnabledFrameRateCounter/EnableRedrawRegionscan be useful when app testing.
Use APIs in the DeviceStatus class track memory usage in the app, especially ApplicationCurrentMemoryUsage and ApplicationPeakMemoryUsage.
See App performance considerations for Windows Phone for an overview of app performance for Windows Phone.

In part 3 of this series, we’ll discuss additional areas and testing approaches to consider, including to network resources, device-specific tests for hardware variations, display resolution, app upgrade, common Store test cases, and real-world testing.

Use your HTML5 skills, port your PhoneGap app to Windows Phone, and win prizes

2013-05-20T19:09:00Z

Many of you have heard about PhoneGap (aka Apache Cordova), the popular open source framework you can use to create mobile apps using HTML, CSS, and JavaScript. PhoneGap has supported the Windows Phone platform since Windows Phone 7.5, and had a major update to support new capabilities in Windows Phone 8, including Internet Explorer 10.
Today, we’re launching a Porting Challenge and inviting developers who have used PhoneGap to publish apps in other stores – for example, Apple iTunes, Google Play, Blackberry World, Bada, Symbian, or Palm OS – to take any of their existing PhoneGap apps, published in any store, and port it to Windows Phone 8, like the Untappd app recently ported to Windows Phone 8.

Members of a panel selected from Microsoft, the Adobe PhoneGap team, and industry experts will choose 20 winners, based on apps that are:

Original
Innovative
Easy to use
Engaging and visually appealing to the user

The panel will pick 3 grand prize winners who each will receive a Windows Phone 8 device and a Surface Pro, and 17 first prize winners who each will receive a Windows Phone 8 device. All winning apps will be evaluated for featured slots in the Windows Phone Store.

The challenge starts today, May 20, 2013. You have through June 30, 2013, to submit your app for this porting challenge. Winners will be announced July 19, 2013, at the PhoneGap Day event in Portland, Oregon. The challenge is open to developers in all countries/regions where Windows Phone Dev Center registration is available. Read the complete rules for all the details before you sign up at http://www.phonegapwpchallenge.com/.

Whether you’re a seasoned PhoneGap developer new to Windows Phone, or if you’re new to PhoneGap, I encourage you check the pointers on how to get started on the challenge site: http://www.phonegapwpchallenge.com/Home/Resources
We have a 5-minute video tutorial that shows you how to set up PhoneGap with Visual Studio, and a few other detailed tutorials. We’ve also collected tips & tricks to adapt WebKit-optimized HTML5 code to Internet Explorer 10, and how to give your app UI a Windows Phone look and feel.

If you’re curious to see examples of published Windows Phone apps that were built using the PhoneGap framework, head over to the PhoneGap website to browse their Windows Phone app gallery.

Ready, set, go!

JC Cimetiere
@jccim

XAudio2 Performance and Battery Considerations for Windows Phone 8

2013-05-17T18:50:31Z

This blog post was authored by Joao Lucas Guberman Raza, a program manager on the Windows Phone team.

- Adam

In this post we cover important information for Windows Phone 8 developers who use the XAudio2 APIs, including best practices for battery performance. XAudio2 is a high-performance audio API available in Windows 8, Xbox 360, and Windows Phone 8. An app developer can use XAudio2 to create audio graphs in which they can treat each audio source in the graph as a distinct “voice.” The developer can apply different effects to each of the “voices.”

In Windows Phone 8, the XAudio2 engine must be aligned with the life cycle of the app. This means that if an app is suspended, the app that’s using XAudio2 must force the XAudio2 engine to stop. When the app resumes/rehydrates, if it is designed to resume sounds using XAudio2, it must restart the XAudio2 engine. Significant battery drain can occur if an app doesn’t stop the XAudio2 engine when the app is suspended, and the engine continues to run.

To avoid this scenario, an app must call IXAudio2::StopEngine when the app is suspended as described in the Native audio APIs for Windows Phone 8. When the app resumes, it should call IXAudio2::StartEngine. For Silverlight and Direct3D with XAML apps, the suspend/resume APIs are the Suspended and Activated events. For Direct3D native-only apps, the suspend/resume APIs are the Suspending and CoreView Resuming events.

The following code examples show you how you can do this in a pure native Direct3D app.

First create the XAudio2 object, which handles the XAudio2 sound APIs.
C++
1. IXAudio2* pXAudio = NULL ;
3. if( FAILED(XAudio2Create(&pXAudio, 0, XAUDIO2_DEFAULT_PROCESSOR) ) )
4. return false ;
6. if ( FAILED(pXAudio->CreateMasteringVoice( &pMasterVoice ) ) )
7. return false;
Then, on the suspending/resume events, set up the XAudio2 object to call StopEngine and then StartEngine. In the following example, we use the default events in the Windows Phone 8 SDK template for Direct3D native-only apps.
C++
1. void WindowsApp::Initialize(CoreApplicationView^ applicationView)
2. {
3. applicationView->Activated +=
4. ref new TypedEventHandler<CoreApplicationView^, IActivatedEventArgs^>(this, &WindowsApp::OnActivated);
6. CoreApplication::Suspending +=
7. ref new EventHandler<SuspendingEventArgs^>(this, &WindowsApp::OnSuspending);
9. CoreApplication::Resuming +=
10. ref new EventHandler<Platform::Object^>(this, &WindowsApp::OnResuming);
11. }
13. void WindowsApp::OnSuspending(Platform::Object^ sender, SuspendingEventArgs^ args)
14. {
15. pXAudio->StopEngine() ;
16. }
18. void WindowsApp::OnResuming(Platform::Object^ sender, Platform::Object^ args)
19. {
20. pXAudio->StartEngine() ;
21. }

With these steps, you can design your app to follow best practices for battery consumption when you use the XAudio2 APIs. It’s important to note that this is one of many best practices you can use in your app. To learn more, see also local folder best practices for Windows Phone, localization best practices for Windows Phone, and background agent best practices for Windows Phone.

Tips to grow your app revenue through in-app purchase

2013-05-16T17:28:18Z

Your Windows Phone 8 app presents three potential sources of revenue: app sales, in-app advertisement, and in-app purchases.

In a previous blog post I wrote about what you can sell in your Windows Phone 8 app by adding in-app purchase. You can:

Sell digital items.
Offer consumables (items that are used a set number of times per purchase) and durables (items purchased and then owned by the buyer).
Extend app features: add game levels, app features, and game currency, for example.

Today, I want to share recommendations and guidance to optimize the experience and effectiveness of in-app purchase in your Windows Phone app.

In-app purchase trends in the Windows Phone store

In-app purchase was added with the launch of Windows Phone 8 as a way to expand the value of apps and offer the possibility of additional revenue. It represents a growing revenue source in the Windows Phone Store: already 40% of the top 15 highest-grossing developers have apps that use in-app purchase.

Consumer adoption of in-app purchase varies by market, depending on regional trends, consumer preferences, and other regional differences. Central Europe, China, France, Middle East and United States are the markets where consumers purchased most in-app items, as a percentage of app downloads, compared to other markets.

In-app items are used in all categories of Windows Phone 8 apps in the Store. The categories with highest use of in-app purchase are Games, Tools and Productivity and Books & Reference. So in-app purchase can be used in all types of apps.

Use of in-app purchase by app category

Insight from the apps with highest in-app revenue

We analyzed the 30 apps and games with the highest in-app purchase revenue in the Windows Phone Store, and found some interesting trends, common characteristics, and best practices. Here’s what we discovered.

In-app purchase can add value to both games and non-game apps: the top grossing list includes 20 games (shooters, puzzles, racing, family, and other types of games) as well as 10 non-game apps (audio book, health/fitness, tools/productivity, navigation, and sports).

Start with a great app: All these top 30 apps are high quality, engaging apps with beautiful graphics and compelling sounds and music. All apps have 4-star ratings or higher, and user comments posted in the Store show that users love these apps, and therefore are willing to purchase the in-app items to enhance their experience. All these apps are easy to use and intuitive.

Use the ‘freemium’ business model: Most of these apps are free and offer in-app purchase extends the value of the app (90% of the apps are free and 10% are available in a paid version only). There are a few apps that are not free, and these apps are from developers with a brand name strong enough that users will know the quality or utility of the app. Very few of the apps, less than 5, use advertisement in the apps: most of these top developers focus only on in-app purchase to generate revenue.

Offer value even without purchase, and extend the app through in-app purchase: 28 of the 30 apps are useful even without in-app purchase. The apps provide great value even if no in-app purchase is used. In-app purchase is used to improve the app experience:

The games use in-app consumables to offer game currency, which in turn is used to purchase items in the game. Users can earn this currency through gameplay, or accelerate gameplay through purchase.
Non-games offer content through consumables and durables (audio books, book chapters, navigation maps, more sounds) or offer additional features through durable in-app purchase (for example additional features like online backup).
Three of the five apps that have ads use in-app purchase as an option for the user to remove the ads.
Two apps use in-app purchase to unlock the full version or new levels. These apps require in-app purchase to provide value beyond the introductory level or content.

Integrate in-app purchase seamlessly: The app developers use in-app purchase as a natural extension of the app, not as an afterthought. When using these apps, users feel that they are getting a significant additional value of value through the in-app purchase, and don’t feel forced to buy the app items to be able to use the app. In-app purchase is shown on simple, clear screens that show the value of what is being purchased, and frequently offer many options so the user can choose the best one for their budget and needs.

Make the app available also on Windows Phone 7: In-app purchase is only available on Windows Phone 8, so many of these top apps have created a XAP for Windows Phone 7 and a XAP for Windows Phone 8, to offer the app on Windows Phone 7:

10 of these apps are available for free on Windows Phone 7, providing the same functionality as the Windows Phone 8 versions, without in-app purchase. A few of these apps added mobile ads to provide ad revenue in place of the in-app revenue.
5 of these apps have a paid Windows Phone 7 version that offers the capabilities of the Windows Phone 8 version with all the in-app purchases.

Rebellion: Dredd vs Zombies and Guns 4 Hire

I interviewed Chris Kingsley, CTO of Rebellion, to understand more about their Windows Phone games and how they use in-app purchase. Rebellion has two shooter games on Windows Phone: Dredd vs Zombies and Guns 4 Hire. Both games use in-app purchase, and are among the highest grossing free Windows Phone games.

Rebellion makes games for many platforms, including PC games and Windows Store games. Chris shared with me the principles that he thinks have made in-app purchase successful in their Windows Phone games:

The game has to be great.
The game has to be designed with in-app purchase from the ground up.
The game has to balance free versus paid content.
Test, test, test, with as many people as possible.

Dredd vs Zombies was designed for in-app purchase from the ground up: the game is playable from beginning to end without in-app purchase. In-app purchase is used to sell credits that are used to purchase items that make the game more fun and which accelerate leveling up.

The items are designed so they genuinely feel like they are part of the game, and they provide a better play experience.

Dredd also offers items to try out, so players can get a feel for the game items that can be purchased. This also helps increase player engagement.

Guns 4 Hire offers a variety of in-app purchase items. The player has different options to choose from, and isn’t required to purchase to play the game.

The game shows the items for purchase in a very effective way: a large display for each item, a price, and a short and clear description of what you get with the purchase.

Chris from Rebellion mentioned they have another game coming up this month for Windows Phone – Zombie HQ – which builds on the shooter template by allowing players to customize their own HQ between missions.

Adding in-app purchase to your app

In-app purchase can enhance the app experience and increase your revenue, so if you think that you have a great app or game that is a good candidate for in-app purchase, add it today! Here’s how to get started:

Understand what can be sold through in-app purchase and how to add it.
Define how you would add in-app purchase to your Visual Studio project:
- Add it to an existing Windows Phone 7 project (through reflection) or create a new Windows Phone 8 project that uses in-app purchase natively.
- Offer a trial/paid version for Windows Phone 7 users.
Add the in-app purchase to your code.
Add the in-app purchase items through Dev Center.
Test using the different available testing techniques, and share the game with as many users as possible to polish the in-app purchase experience.
Publish your app in the Store!

Please post your feedback or questions about in-app purchase.

Latest Windows Phone app submission improvements

2013-05-10T18:12:43Z

As Todd mentioned in his post last week, I’d like to share some details about the latest improvements we’ve made to Dev Center to address your feedback.

Multiple XAP management during app submission

As more developers update their apps to take advantage of new Windows Phone 8 functionality, managing multiple XAP files for a single app becomes an increasingly common scenario. Many apps have different XAPs for Windows Phone 7.x and Windows Phone 8.0. Dev Center allows each to be serviced independently. Many of you asked for a simplified way to manage XAPs, so we set out to streamline the experience, make it easier to keep track of which XAPs exist for your app, and to clearly identify which XAP you’re acting on when you make a change. Here’s the new UI for managing XAPs in an app submission:

When you update an existing app, you’ll see that all of the XAPs for your app are already present in the submission. You can replace or delete one or more of the existing XAPs, add new ones, or leave them unchanged. Typically you’ll only want to add a new XAP when you’re either submitting a new app or adding support for a new platform version to an existing app. (For more details, see Guidance for app management for Windows Phone). Be careful when you delete a XAP in a submission because it will be removed from your app and no longer available in Store after the submission is published. You can think of this table as showing all XAPs that will be available for your app when the submission is published.

After you’ve established the XAPs that you want for your app, you can select each XAP individually by clicking the button beside its name, and then add/edit the Store listing info for each language that the XAP supports.

MPNS certificate management

To use authenticated push notifications from the Microsoft Push Notification Service (MPNS), your app needs to be associated with the authentication certificate that’s used by your service. You can manage certificates at an account level in Dev Center and then choose from those certificates when you submit a new app or update an existing app.

We’ve refreshed the certificate management UI to make it easier to see all of the certificates that you’ve uploaded, and to differentiate between them:

We’ve also updated the certificate selection UI on the App info submission page to help you select the correct certificate. Remember that if you’re updating an app to associate it with an updated certificate, MPNS requires that the Subject Name CN value remains the same. Dev Center will enforce this restriction to ensure that push notifications continue to work after your update is published.

Review submission

When you create a submission for a new or existing app in Dev Center, that submission will remain until you submit or delete it. This means that you can make changes to a submission on different days and from different browser windows and we’ll keep track of them. This can be a powerful feature as you don’t have to worry about losing changes by closing your browser or switching computers. However, this also makes it important to check your work before final submission to make sure you’re aware of all of the changes. We’ve created a new review page to help you do just that. Now you’ll have the opportunity to check the review page for a submission to be sure you are satisfied with the changes that you’ve made before you submit your app. Here’s an example:

The review page is organized into three sections:

Submission: Displays the publish option chosen, along with errors and warnings if applicable.
App: Displays the changes made at the app level. By default, this section shows only the changes you made, but you can clear the Only show changes I made box to see the full summary.
XAPs: Displays a list of XAPs that will be published for your app.

Here’s how the page looks if you choose to see the full summary of app-level information:

We made these changes to enhance your experience with Dev Center. As always, please keep adding your feedback to the Windows Phone Dev Center UserVoice forum. We appreciate hearing from you and your feedback helps us shape future development priorities.

Inside Windows Phone – Windows Phone and HTML5

2013-05-09T18:41:20Z

This blog post was authored by Matthias Shapiro, a technical evangelist at Microsoft.

- Larry

One of the exciting things and lesser known features in Windows Phone development is how it’s the perfect place to develop apps using HTML5. Jeff Burtoft, an HTML5 technical evangelist with Microsoft, joins us this week to talk about the flexibility and cross-platform power of HTML5 in Windows Phone. The in-depth example that we cover in the video is a project called YetiBowl, a standards-compliant HTML5 game that runs flawlessly on the web, as a Windows 8 app, and as a Windows Phone 8 app. For more information, see Developing in HTML5 and Javascript for Windows Phone.

Testing your Windows Phone app – Part 1

2013-05-03T20:44:00Z

This blog post was authored by Craig Horsfield, a Senior SDET on the Windows Phone Test and Operations team.

- Adam

Testing your app throughout the development process helps to ensure that your app has a high level of performance and quality. Testing also helps to make sure your app is effectively represented in the Windows Phone Store. A small investment in the key areas described in this post can give your app positive results in your market, and help bypass common errors early in the development process. This document will outline testing approaches for key test areas that you should consider.

Beta testing

After you have thoroughly tested your app using the emulator and on a Windows Phone device, it’s important to also test your app as a beta app. Submit your beta app for beta distribution, where you can continue to test your app based on the beta and code flow experience. Additionally, you can include beta tester to help review your app. For more info, see Beta testing your app and in-app products.

Installation and launch

Testing your app’s install and launch process is a vital area that can often be overlooked. By following these steps, you can minimize installation and launch issues that are not handled by your app. There are a few scenarios to consider when testing the initial launch experience and resume paths scenarios. One of these is the new Windows Phone 8 fast app resumescenario that a Windows Phone 8 app can opt into.

The following tests can help verify your app’s install, launch, and resume functions.

Test scenario	Details
1. Verify the app on the first launch.	Note any End User License Agreement (EULA) and any other one-time notifications that appear in the launch UI.
2. Reinstall the app.	Verify that all one-time notifications appear again on a subsequent install and launch.
3. Start the app, and then return to the Windows Phone Start screen.	Launch the app again from a Live Tile, or from the phone’s App list. · Verify the default scenario, in which the old app is terminated, and a new instance of the app starts. · For Windows Phone 8 apps, if the app uses fast app resume for Windows Phone 8, in which ActivationPolicy="Resume", then the app resumes instead of starting a new instance. Verify that the app returns to the correct page in the app.

Fast Application Switching (FAS) and tombstoning

When a Windows Phone app is moved to the back stack based on the app’s navigation history, the app is suspended. When the app resumes, it returns to the foreground. Apps on the back stack are tombstoned when there is resource pressure on the device. The exception occurs when running location-tracking apps in the background for Windows Phone 8. Windows Phone 8 location-tracking apps continue to run in this scenario. Your app needs to handle both of these cases, and you should test this function in your app. FAS occurs when the user leaves the app to go to Start, Search, or some other path based on the launchers and choosers you’ve used in your app to support navigation. For more info, see Multitasking for Windows Phone and App activation and deactivation for Windows Phone.

The following tests can help verify your app’s FAS and tombstoning functions.

Test scenario	Details
1. Test the phone’s Start button and Back button.	Launch the app, and then press the Start button to verify that the Windows Phone start page appears. Press the Back button to resume the app. Verify that the app resumes in the required time, and in the state it was in before you navigated away from the app.
2. Test the Camera button.	Launch the app, and then press the Camera button to verify that the camera starts. Press the Back button to resume the app. Verify that the app resumes in the required time (10 seconds) and that is in the state it was before you navigated away from the app.
3. Test locking the phone using the Power button.	Launch the app, and then press the Power button to lock the phone. Unlock the phone, and then verify that the app resumes in the required time, and that the app is in the state it was in before you locked the phone.
4. Perform the same test cases for FAS and tombstone state.	To force a tombstone path, in Visual Studio, in the project Properties windows, click the Debug tab, and then select Tombstone upon deactivation while debugging.
5. Test deactivating and closing your app.	Make sure the app doesn’t take too long to process the Application_Deactivated and Application_Closing events, so that the app can save its state correctly. Avoid doing a lot of work in the Application_Closing code path, because processing time and access to the UI thread are limited.
6. Test background execution of your app.	For continued background execution in location tracking apps, you’ll want to test the app’s RunningInBackground event handler. In addition to running the preceding tests, check for the following conditions: · Background execution occurs when the app enters the back stack. · Start the app and move it to the back stack and resume the app. Verify that the app was not suspended and that it continued to run.

App navigation

You should navigate all paths in the app to test its navigation. You especially want to be sure that your app exits and handles navigation interruptions as intended.

Test scenario	Details
1. Test the Back button.	Your app should exit when you press the Back button on the top most page.
2. Test navigation interruptions.	Your app should not try to initiate new navigation while your app is currently navigating. Test rapid navigations in the app, and navigating in the app while pages are loading.

Don’t throw unhandled exceptions to exit the app at a page that isn’t at the top of the page stack. Instead, navigate over the page by removing it from the back stack; you don’t want to display the page on the exit path, or call API available in Application.Terminatein Windows Phone 8 apps. This triggers an app crash, and a Watson error report. You might see the crashes indicated in the app reports available in the Store.

Launchers and choosers

Launchers in your Windows Phone app give users the ability to perform common tasks, such as launching the Bing Maps app, launching Media Player, or launching the Store or Marketplace. Launchers do not return data or status to your app. With a chooser, on the other hand, users can return data to your app. For instance, users can choose return info from the Contacts app. For all launchers and choosers, test your app to be sure the launcher or chooser works correctly, and that it doesn’t trigger related errors.

Test scenario	Details
1. Test navigating to and from the launcher or chooser.	In the app, navigate to the launcher or chooser. Immediately go back to the previous page or screen. The app should return to the page and state the navigation was initiated from.
2. Test the complete scenario when using the launcher or chooser.	In the app, navigate to the launcher or chooser. Complete the scenario, i.e., select a photo or send mail. When the action is completed, the app should return to the preceding app state.
3. Test FAS scenarios when navigating to a launcher or chooser.	Navigating to a launcher or chooser can triggers an FAS scenario. See the related section earlier in this post for additional test scenarios related to FAS.

UI and layout

You need to test to make sure all elements of your UI and their layout work as intended, and meet app submission requirements, such as supporting Light Theme and Dark Theme. Test each control you use in your app, and the overall appearance of your app on the phone.

The following tests will help verify your app’s UI and layout.

Test scenario	Details
1. Test your app in the Light Theme.	Ensure all text is readable and all UI is visible.
2. Test your app in the Dark Theme.	Ensure all text is readable and all UI is visible.
3. Test the UI for text clipping.	You may need to set the text to wrap or make other layout changes.
4. Test your Splash screen display.	If you use a splash screen in your app, verify that it’s visible when the app starts, and that it displays for the expected time.
5. Test each animation.	Ensure all animations are smooth. If they appear slow or stop unexpectedly, see if the app is doing excessive work on a background task or thread.
6. Test each screen orientation.	Verify that the layout looks as you intended in portrait and landscape orientations, and that each page can display and move between orientations.

In part 2 of this series, we’ll discuss additional areas and testing approaches to consider related to push notification; Live Tiles; background agents; media, audio, and video; geolocation, and resource usage and performance.

Expanded developer opportunity – new payout markets and billing connections

2013-05-03T16:02:00Z

We continue to take steps forward on the path to establish a Windows Phone ecosystem characterized by quality, scale, and developer opportunity. We are seeing strong results for the ecosystem since the launch of Windows Phone 8 with more than a 100% increase in app downloads and nearly 140% increase in paid app revenue. Today I have a few enhancements to announce that can help you expand your app distribution reach and revenue opportunities.

Diverse phone offering and distribution

Nokia’s Lumia 720 and 520/521 phones have just begun to ship across the globe, giving potential Windows Phone customers additional choices in form factor, phone capabilities, and price points. This review from CNET (Nokia Lumia 520 review: One of the best budget phones around) pretty much sums up the sentiment on the new device, stating the Lumia 520 packs an “impressive punch” both in terms of hardware quality and value for the money.

These phones will be available in new markets and distribution channels, given their budget-friendly pricing. In fact, this week the Nokia Lumia 521 paired with an offer from US mobile operator T-Mobile to make its debut on the popular US Home Shopping Network, a first for Windows Phone.

The industry continues to recognize Windows Phone steady growth. According to Kantar Worldpanel ComTech, Windows Phone has already increased its share of all smartphone sales by nearly 2% compared to last year and is attracting first-time smartphone buyers. With over half of the US market (and much of the world) still owning a feature phone, it’s likely many will upgrade over the coming year, which ultimately will contribute to growth for Windows Phone.

Six new developer payout markets

This week we will enable developer payout in 6 new markets via Dev Center bringing the total markets supporting developer payout to 122. The new markets include: Afghanistan, Iraq, Montenegro, Serbia, Timor-Leste, and Ukraine. Developers in these 6 markets will now be able to submit both free and paid apps to the Windows Phone Store to reach customers in 191 markets.

New Mobile Operator Billing Connections

We have added 15 new mobile operator billing partners since August 2012, bringing the total number of supported partners to 25 in 19 markets, surpassing Google Play. Mobile operator billing gives consumers a payment option with significantly higher conversion rates than credit cards. On average, an app developer earns 3x more per active user on a paid app published in a mobile operator billing-enabled market than a market that only supports credit card. We will continue to expand this footprint and you’ll be seeing many more connections in the near future.

Simplified app submissions

Finally, I want to point out that we continue to incorporate your feedback and streamline the app submission process. Recently the Dev Center team enabled cancelling submissions, rotating screenshots and automatic screenshot resizing – all items you indicated needed improvement. You can read more about these enhancements on the Windows Phone Developer blog. Next, we’ll add the ability to review your app submission, giving you a chance to make sure everything looks right, before you actually submit. I encourage you to watch for a post from Rushmi Malaviarachchi in the coming week that will provide details on all the latest improvements.

If you haven’t yet developed an app for Windows Phone or if you haven’t updated your app recently, I’d like to encourage you to visit the Dev Center to download the SDK and get started. There’s never been a better time to develop for Windows Phone.

Inside Windows Phone – Data binding

2013-05-02T20:48:33Z

Data binding is one of the fundamental concepts used for good Windows Phone application design, but can be difficult to grasp for newcomers. The core concept is this: No one wants to manually update the user interface elements. It’s best to have the UI automatically reflect the state of the application. Data binding helps us do this. We can work exclusively on our Windows Phone UI, bind the values in the UI and then work on the inner logic of the application knowing that all the updates are being reflected to the user. Because of the power in the model, as you see in this video, there are some really great "fringe" benefits in terms of interaction and design that we get, along with the core benefits. For more information, see Data binding for Windows Phone.

Using the Windows Phone 8.0 SDK to localize Windows Phone OS 7.1 projects

2013-04-24T19:00:17Z

This blog post was authored by Dan Zucker, a program manager on the Windows Phone team.

- Adam

Here are the quick steps you need to take to set up a Windows Phone OS 7.1 Visual Studio project to use the techniques and features described in the blog posts Tips for Localizing Windows Phone 8 XAML Apps - Part1 and Tips for localizing Windows Phone apps – Part 2 to localize apps. Note that throughout these steps, you must replace <PROJECT_NAME_SPACE> with your project name.

Follow the steps in the Standard Localizing Steps section described in Tips for Localizing Windows Phone 8 XAML Apps - Part1 to make your single-language app ready for localization.
Update the <Application.Resources> node in the App.xaml file with the following code, where <PROJECT_NAME_SPACE> is replaced with your project name:
XAML
1. 
2. <Application.Resources>
3. <local:LocalizedStrings xmlns:local="clr-namespace:<PROJECT_NAME_SPACE>" x:Key="LocalizedStrings"/>
4. </Application.Resources>
The LocalizedStrings Application Resource, along with the LocalizedStrings class added in the next step provides a globally accessible means for your app to access its project’s localized resources. Although there are simpler ways to achieve that goal, the method described here provides the benefits of strong typing, including resource visibility in IntelliSense and compilation validation during coding.
Add a new class file named LocalizedStrings.cs to the project. Replace the existing code with the following, where <PROJECT_NAME_SPACE> is replaced with your project name:
C#
1. using <PROJECT_NAME_SPACE>.Resources;
3. namespace <PROJECT_NAME_SPACE>
4. {
5. /// <summary>
6. /// Provides access to string resources.
7. /// </summary>
8. public class LocalizedStrings
9. {
10. private static AppResources _localizedResources = new AppResources();
12. public AppResources LocalizedResources { get { return _localizedResources; } }
13. }
14. }
Search the entire project for localized string resources. Update the project namespace as needed by including the following code, where <PROJECT_NAME_SPACE> is replaced with your project name:
C#
1. using <PROJECT_NAME_SPACE>.Resources;
Add a folder named Resources to the project.
Add a new resources file named AppResources.resx file to the new Resources folder.

Add the language initialization resource strings ResourceFlowDirection and ResourceLanguage to AppResources.resx, as described in Tips for Localizing Windows Phone 8 XAML Apps - Part1. Typically, the value of the resource strings should be set to meet the traditional flow direction and locale of the neutral language (the one that a viewer of your app will see if they have selected a phone language that is not supported by your app).

Name	Value	Comment
ResourceFlowDirection	LeftToRight	Controls the FlowDirection for all elements in the RootFrame. Set to the traditional direction of this resource file's language.
ResourceLanguage	en-US	Controls the Language and ensures that the font for all elements in the RootFrame aligns with the app's language. Set to the language code of this resource file's language.

Change the access modifier of AppResources.resx to "Public" by using the Access Modifier drop-down list at the top of the resource editor.
Save and rebuild the solution.
Add the following references to App.xaml.cs, where <PROJECT_NAME_SPACE> is replaced with your project name:
C#
1. using <PROJECT_NAME_SPACE>.Resources;
2. using System.Threading;
3. using System.Globalization;
4. using System.Diagnostics;
5. using System.Windows.Markup;
Add the InitializeLanguage function and call to the constructor of the App.xaml.cs file. Include the following using statements to reference System.Threading and System.Globalization at the beginning of the file. Also, add the declaration for the appForceCulture global variable to enable the international testing feature described in Tips for localizing Windows Phone apps – Part 2.
C#
1. // . . .
2. public partial class App : Application
3. {
4. // Global variable to set app locale at launch for International testing
5. // An empty value causes the app to following users phone language culture
6. public static String appForceCulture = "qps-ploc";
8. /// <summary>
9. /// Provides easy access to the root frame of the phone app.
10. /// </summary>
11. /// <returns>The root frame of the phone app.</returns>
12. public static PhoneApplicationFrame RootFrame { get; private set; }
14. /// <summary>
15. /// Constructor for the Application object.
16. /// </summary>
17. public App()
18. {
19. // Global handler for uncaught exceptions.
20. UnhandledException += Application_UnhandledException;
22. // Standard XAML initialization
23. InitializeComponent();
25. // Phone-specific initialization
26. InitializePhoneApplication();
28. // Language display initialization
29. InitializeLanguage();
30. // . . .
Add the InitializeLanguage method to App.xaml.cs:

C#

// Initialize the app's font and flow direction as defined in its localized resource strings.

//

// To ensure that your apps font is aligned with its supported languages and that the

// FlowDirection for each of those languages follows its traditional direction, ResourceLanguage

// and ResourceFlowDirection should be initialized in each .resx file to match these values with that

// file's culture. For example:

//

// AppResources.es-ES.resx

//    ResourceLanguage's value should be "es-ES"

//    ResourceFlowDirection's value should be "LeftToRight"

//

// AppResources.ar-SA.resx

//     ResourceLanguage's value should be "ar-SA"

//     ResourceFlowDirection's value should be "RightToLeft"

//

// For more info on localizing Windows Phone apps see http://go.microsoft.com/fwlink/?LinkId=262072.

//

private void InitializeLanguage()

{

    try

    {

        // Change locale to appForceCulture if it is not empty

        if (String.IsNullOrWhiteSpace(appForceCulture) == false)

        {

        // Force app globalization to follow appForceCulture

            Thread.CurrentThread.CurrentCulture = new CultureInfo(appForceCulture);



// Force app UI culture to follow appForceCulture

            Thread.CurrentThread.CurrentUICulture = new CultureInfo(appForceCulture);

        }

        // Set the font to match the display language defined by the

        // ResourceLanguage resource string for each supported language.

        //

        // Fall back to the font of the neutral language if the display

        // language of the phone is not supported.

        //

        // If a compiler error occurs, ResourceLanguage is missing from

        // the resource file.

        RootFrame.Language = XmlLanguage.GetLanguage(AppResources.ResourceLanguage);

        // Set the FlowDirection of all elements under the root frame based

        // on the ResourceFlowDirection resource string for each

        // supported language.

        //

        // If a compiler error occurs, ResourceFlowDirection is missing from

        // the resource file.

        FlowDirection flow = (FlowDirection)Enum.Parse(typeof(FlowDirection), AppResources.ResourceFlowDirection,false);

        RootFrame.FlowDirection = flow;

    }

    catch

    {

        // If an exception is caught here it is most likely due to either

        // ResourceLangauge not being correctly set to a supported language

        // code or ResourceFlowDirection is set to a value other than LeftToRight

        // or RightToLeft.

        if (Debugger.IsAttached)

        {

            Debugger.Break();

        }

        throw;

    }

}

As the comments in the code explain, the InitializeLanguage method initializes the app's font and flow direction as defined in the localized resource strings.

As described in the blog posts Tips for Localizing Windows Phone 8 XAML Apps - Part1 and Tips for localizing Windows Phone apps – Part 2, when you add a language to your app using the Windows Phone 8.0 SDK, a resource file for that locale is created. In that .resx file, the ResourceLanguage and ResourceFlowDirection values are initialized for the locale of the language you added. When the app is launched, InitializeLanguage() uses the values of ResourceLanguage and ResourceFlowDirection to initialize the xml:lang and FlowDirection of the app’s Rootframe.

Typically the culture used by InitializeLanguage() is the culture the system chooses to most closely match to the user’s phone language setting. The appForceCulture clause allows you to override this with the culture of your choice, so that you can deploy and review your app in the language of your choice without the time-consuming process of changing settings or restarting the device or emulator. If you use this convenient method, don’t forget to also test the app to be sure that everything works as expected when you modify the Phone Language setting and reboot.

Inside Windows Phone – code samples

2013-04-19T18:05:05Z

What Windows Phone code samples are available to you, and how do you get them? We publish a large number of code samples that cover a solid range of Windows Phone developer scenarios. In this video, we touch on some of the code samples we’ve created to help you design and develop great Windows Phone apps, and where to find them.

Here’s where you can find some of the Windows Phone code samples and resources we discuss in the video.

Matthias's blog post that highlights some awesome Windows Phone samples, and where to get them
The Windows Phone Dev Center samples page – the complete list of samples created by the Windows Phone developer content team, by developers for developers
The Lens sample (check out Lenses for Windows Phone 8 for an overview and walkthrough of how to build your Lens app)
The photo extensibility sample (see Photo extensibility for Windows Phone for more info about how to use the sample and how to create your app)
The Twitter search infinite scrolling sample using the LongListSelector control in Windows Phone (check out the topic on how to display data in a grouped list using LLS)
The People Hub LongListSelector sample, with jump lists (be sure to see the topic on how to display data in a grouped list using LLS for info about using LLS for this sample, too)
A speech recognition sample that covers using a custom grammar (see Voice commands for Windows Phone 8 for more info about how to use this feature in your app)

Please send us any questions or feedback – we’d like to hear from you.

Tweet to @LarryALieberman or @matthiasshap

Facebook SDK for .NET - Featured in the Facebook Technology Partner program

2013-04-18T17:01:25Z

This blog post was authored by Sanjeev Dwivedi, a developer evangelist for Microsoft working with Facebook.

- Adam

Today we are pleased to share with you that Facebook has announced the Facebook SDK for .NET as part of the Facebook Technology Partners program. This is a C#/XAML–based SDK that makes integrating your Windows Phone and Windows 8 style apps with Facebook a breeze. The SDK is an open-source project owned and released by the Outercurve Foundation. The Outercurve website for the SDK is http://facebooksdk.net, which hosts tutorials for both Windows 8 and Windows Phone, and has links to the GitHub repository where the source is hosted.

You can easily integrate the SDK into your project using NuGet, which automatically downloads and installs the SDK in your project. To do this, launch the Package Manager Console from the toolbar:
Tools > Library Package Manager > Package Manager Console

Install the Facebook NuGet package as part of your app by running the following command:

Install-Package Facebook

The Facebook SDK for .NET makes your life easier by providing two key functionalities:

It takes away all of the complexity of logging on with Facebook. Based on the provided samples, all you need to do is use a bit of boilerplate code, add your Facebook app ID to the mix, and voila! You can have people logging on to your app with Facebook.
It allows you to focus on your Facebook-related scenarios by abstracting away the low-level details such as HTTP connections and query parameters. This way you can plan and develop around Open Graph APIs and objects, which is where you want to spend your development resources.

An added benefit of using this SDK is that it provides very similar APIs on both the Windows Phone and the Windows 8 platforms, so code-sharing between the two platforms becomes very easy. Here is a snippet that showcases retrieval of a Friends list from Facebook on Windows Phone. As you can see in the code example, setting up the client and making the call to retrieve your Friends list requires just a few lines of code. The rest of the code is your logic around picking the data that is of interest to you.

Code Snippet
 // Instantiate the Facebook client
FacebookClient fb = new FacebookClient("<Supply Access Token here>");
 
// Make the friends list Open Graph API request
var friendsTaskResult = await fb.GetTaskAsync("/me/friends");
 
var result = (IDictionary<string, object>)friendsTaskResult;
var data = (IEnumerable<object>)result["data"];
foreach (var item in data)
{
    var friend = (IDictionary<string, object>)item;
    // Pick out the properties from the dictionary without the need for writing deserializing classes
 
    string name = (string)friend["name"];
    string id = (string)friend["id"];
}
 

You can find more details about the SDK on the Outercurve Foundation website: http://facebooksdk.net/docs/. You can also follow the development of the SDK at its Facebook page, report any issues on Github issue tracker, and ask any follow-up questions on the StackOverFlow forum. For details about how to obtain an Access Token, see the Authenticate section in the Windows Phone tutorial.

The offerings and resources presented may be relevant to developers. However, this post is for informational purposes only and Microsoft is providing this information "as is" with no warranties. Each contribution is licensed to you under an agreement by its provider, not Microsoft. It is your responsibility to evaluate if these resources are suitable for your usage.

Defining your app’s requirements for a great customer experience

2013-04-17T18:30:48Z

One of the things I really enjoy about developing for Windows Phone is being able to reach a diverse audience across the globe. Windows Phone users access my apps on phones from different manufacturers, all with varying capabilities and price points to meet local needs. While I benefit from the diverse audience, it does take a little planning on my part to create a great user experience and to ensure that my apps comply with the Windows Phone technical certification requirements.

In this post I’ll help you identify the phone features and hardware your app requires, and then provide guidance on how define these needs in Visual Studio.

Capabilities and requirements

Windows Phone uses the app manifest file to identify the software capabilities, hardware required, and memory each app requires to run correctly:

Software capabilities: indicate that an app accesses the phone identity, camera, maps, media libraries, networking, Near-Field Communication (NFC), push notifications, sensors, wallet, web browser, and other software capabilities. Windows Phone grants access to these capabilities, and customers are informed before purchasing the app which capabilities are used.
Hardware requirements: indicate phone features that the app must have to function correctly. The operating system uses the list to prevent apps from being installed on phones that don’t meet these requirements.
Functional capabilities: indicate that your app is requesting more memory at run time, if it is available.

Your app must enable the relevant capabilities and hardware requirements

Make sure your app is not marking capabilities and requirements that it doesn’t need. Users see your app’s capabilities and requirements when they install the app, and may decide not to move forward with installation if they see that your app uses capabilities that they don’t want to enable, or that are not related to the purpose of the app.

In a scenario in which your app can provide value even when some hardware is absent, use API checks to first detect the presence of the hardware, and then to inform users if some features are disabled because of missing hardware.

The following steps explain how you can modify support for different Windows Phone capabilities in your app.

Open your project in Visual Studio, go to the Solution Explorer, and then in the Properties folder, open WMAppManifest.xml. Then, add or remove the capabilities as illustrated here:

Windows Phone 7 project

Windows Phone 8 project

Add hardware and functional capabilities to the manifest file

If the hardware or functional capabilities you need are not listed in Visual Studio, you must manually edit the manifest file. To do this, first understand all the capabilities available, and then edit the manifest file in a text editor, such as Notepad, or directly in the code. Right-click the file in Solution Explorer, click Open With, and then edit through Notepad or ‘view code’. You turn these on by adding the correct flag:

Requirement	Short description
ID_REQ_MEMORY_90	App requires at least 90 MB of RAM
ID_REQ_MEMORY_300	App requires at least 180 MB of RAM
ID_REQ_FRONTCAMERA	App requires the front-facing camera
ID_REQ_REARCAMERA	App requires the rear camera
ID_REQ_NFC	App requires a phone with NFC chip
ID_REQ_MAGNETOMETER	App requires a compass
ID_REQ_GYROSCOPE	App requires gyroscope to measure rotational velocity

Here’s an example of the manifest flag that shows the software, hardware, and functional capabilities:

Capabilities required when using the Microsoft Ad Control

If your app uses the Microsoft Ad Control, be sure to enable the following capabilities:

Windows Phone 7 Silverlight	Windows Phone 7 XNA	Windows Phone 8 project
ID_CAP_IDENTITY_USER	ID_CAP_IDENTITY_USER	ID_CAP_IDENTITY_USER
ID_CAP_MEDIALIB	ID_CAP_NETWORKING	ID_CAP_MEDIALIB_PHOTO
ID_CAP_NETWORKING	ID_CAP_PHONEDIALER	ID_CAP_NETWORKING
ID_CAP_PHONEDIALER		ID_CAP_PHONEDIALER
ID_CAP_WEBBROWSERCOMPONENT		ID_CAP_WEBBROWSERCOMPONENT

Additional considerations

In some scenarios, capabilities are added automatically. Here are some examples:

During debugging, when running the app in the Windows Phone Emulator, the Network Capability is set to ‘on’ by default. You should always test your app on a phone instead of on the emulator if your app uses any of the Windows Phone Software or Hardware capabilities, to ensure you are getting correct test results.
For Windows Phone 8 projects, it is your responsibility to ensure all the correct Software capabilities are identified and added to the manifest file.
For Windows Phone 7 projects, the submission process looks for software API calls and, if found, will add the Software capabilities to ensure that the app has the correct permissions to run.
Third-party libraries could make calls to some APIs, for example, to network or sensor APIs.

Having a variety of phones with different price points creates opportunities to reach out to more users. Take the time to set the correct information and get your app ready to be successful on a variety of Windows Phone devices.

How capabilities are displayed to Windows Phone users

The following table shows examples of how capabilities appear to consumers in the web Store and on the phone:

How capabilities are shown in app details page of an app on the Windows Phone web Store

How capabilities are shown in the app details page of an app on Windows Phone

Using the Store Test Kit (for Windows Phone 7 projects)

If your app targets Windows Phone 7.1, you can use the Store Test Kit to verify the capabilities that are being detected, to confirm they align with what you are expecting. The Windows Phone 8.0 SDK includes the Store Test Kit, and the Windows Phone 7 SDK requires you to install a stand-alone tool to run these tests.

Take the following steps to run the Store Test Kit for Windows Phone 7 project:

INSTALL AND START THE TEST KIT. Install and run the Store Test Kit. In the latest version of the SDK you can open the Store Test Kit directly from within your project: on the Project menu, click Open Store Test Kit.
RUN THE AUTOMATED TESTS. The Store Test Kit can detect and add software capabilities based on API calls for Windows Phone OS 7.x managed projects (not on native projects or Windows Phone OS 8.0 managed projects). Note You probably will need to update the test cases the first time you run the Test Kit, because we update them frequently. You can do this easily from the blue alert bar you might see across the bottom of the Test Kit window.

Use the Automated Tests tool to identify the capabilities that your app is using. Verify that these are the capabilities your app actually requires.

Windows Phone users appreciate having visibility into my app requirements, so that they can make an informed choice about downloading and purchasing your app. In the end, the user gets an app that performs well on their phone, and you get a better review for your apps. Everyone wins.

I’d like to hear from you. Please let me know your questions about defining capabilities, as well as suggestions for topics you’d like me to cover in future blog posts.

Controlling a hardware prototype with your Windows Phone

2013-04-16T22:54:54Z

This blog post was authored by Erik Reitan, a programming writer on the Windows Phone developer content team.

- Adam

You’re already familiar with creating great apps for Windows Phone, and porting your apps from iOS or Android, but did you know that you can build .NET hardware prototype devices to integrate with your Windows Phone?

Using a prototyping platform for small electronic devices, such as .NET Gadgeteer or Netduino, you can create interesting hardware projects. Using C#, the .NET Micro Framework‎, and Visual Studio, you can develop your own hardware prototype and use the capabilities of your Windows Phone to interact with the hardware.

The following video shows how Matt @RogueCode used his Windows Phone to control a maze using Bluetooth and Netduino.

For more details about Matt’s project, read Greg Duncan’s Coding4Fun blog post on Channel 9.

Here’s another video that shows how Marco Minerva @MarcoMinerva used his Windows Phone to control a rover with Bluetooth and.NET Gadgeteer. Very cool!

For complete details about Marco’s project, see the related Coding4Fun blog post on Channel 9.

Here’s another video by Matt that shows how you can combined Windows Phone, Netduino, a sonar sensor, and Bluetooth for some interesting results.

For more details about Matt’s project, see the following Coding4Fun blog post on Channel 9.

Each of these Windows Phone projects provide the steps, code, and details necessary to build the project yourself, through the above links. Possibly, these examples could lead to your own hardware prototype. Let us know what you create.