How to: Test and Debug your Trial Application for Windows Phone

This is pre-release documentation for the Windows Phone OS 7.1 development platform. To provide feedback on this documentation, click here. For the Windows Phone OS 7.0 developer documentation, click here.

May 19, 2011

This topic describes how you can test and debug your trial application.

When debugging in the Windows Phone Emulator or testing on an unlocked device, your application must simulate trial mode. In these cases, which are generally called debug mode, the IsTrial() method always returns false and the Show() method always launches a page that reports that the application cannot connect to the service. There are various approaches to implementing trial simulation, depending on the nature of your application.

A suggestion for the simulated trial experience while debugging is illustrated in the following figure.

Simulation of Trial and Purchase while Debugging

Options for Trial Simulation

The XNA Framework supplies the Guide class of the GamerServices namespace to support the simulation of both trial mode and conversion to full mode. You can take advantage of these capabilities from either Silverlight or XNA Framework applications. Using the Guide.SimulateTrialMode property in combination with the IsTrialMode and ShowMarketplace methods, allows you to code your simulation with minimal difference between debug and released code paths. For more information, see Simulating Trial Mode for Marketplace Content.

While Silverlight does not have any native means of simulating trial mode, you can write custom trial simulation code or call the XNA Guide class from within your Silverlight project.

Custom Trial Simulation

In this example, the IsTrial() method is called indirectly through a CheckIsTrial function in the following example which wraps the IsTrial() method in conditional compilation code. When compiled for release, the application checks the result of the IsTrial() method. When compiled for debug, the IsTrial() call is replaced by a message box that allows you to decide which path to use.

For the preceding trial simulation, your code might look something like this:

private void Level_One_Over_with_Simulation ()
{
  if (!CheckIsTrial())
  {
    Enter_level_2();
  }
  else
  {
    Show_Buy_Now_Page();
  }
}

private bool CheckIsTrial()
{
#if DEBUG
  MessageBoxResult result = MessageBox.Show("CLICK OK TO SIMULATE FULL LICENSE","BUY NOW!",MessageBoxButton.OKCancel);


  if (result == MessageBoxResult.OK)
  {
    Return FALSE;
  }
  else
  {
    Return TRUE;
  }
#else
  Return licenseInfo.IsTrial();
#endif
}

Testing your Call to MarketPlaceDetailTask.Show

It is a good practice to test your Show() call.

Selecting the Cancel button in the trial simulation example will navigate to the “Buy Now” page. The Buy button on that page calls the buy_now_Click function that was described in the The MarketplaceDetailTask.Show Method section. This will cause the display of the Windows Phone Marketplace application error page that is in the following illustration. Error code 80070057 specifies that the Show() call successfully opened the Windows Phone Marketplace application.

TestingCalltoMarketPlaceDetailTaskShow

Trial Simulation using the GamerServices.Guide Class

Here’s how the XNA Framework Guide class enables trial simulation:

When an application is tested in the Windows Phone Emulator or deployed to your unlocked phone in debug mode, the following tasks are performed:

When a released application is executed on a normal phone, the following tasks are performed:

  • A call to the Guide.IsTrialMode method is functionally equivalent to a call to the IsTrial() method. It returns the state of the current license for the calling application.

  • A call to the ShowMarketplace method is functionally equivalent to a call to the Show() method. It causes the Windows Phone Marketplace application to open and navigate to the Detail page of the calling application. When this occurs, your application is tombstoned.

  • It is important to set the SimulateTrialMode property to false in released code, or excluded from it. A good practice is to place the statement that initializes the SimulateTrialMode property within a #if DEBUG clause to avoid issues when you submit your app.

In the following example, the value of the SimulateTrialMode property is set to true when the application loads during the debug mode and is not instantiated in the release mode.

using Microsoft.Xna.Framework.GamerServices;
public App
{
#if DEBUG
  Guide.SimulateTrialMode = true;
#endif

}

private void Level_One_Over ()
{
  if (Guide.IsTrialMode == false)
  {
    Enter_level_2();
  }
  else
  {
  /*The PlayerIndex parameter of the ShowMarketplace call (set arbitrarily to One in
      *this example) must contain an integer value. The actual value used is not   
      *consequential when the Guide class is used in a SilverLight application.
  */

    Guide.ShowMarketplace(PlayerIndex.One); 
  }
}

Show: