Using the Bing Maps token service

Once you have created a Bing Maps developer account, you can access Bing services. See the Bing Maps overview topic in this help system for instructions on obtaining an account. To access Bing services you must generate a token, which stores credential information, and provide it in each request to a Bing service. As a result, Bing components built for the ArcGIS Silverlight API require you to provide a token when constructing the component (whether in XAML or code-behind). To generate the token you must submit your Bing Maps developer account ID and password to the Bing Maps Token Service. Defining user credentials within the Silverlight application is not supported or recommended since they are easily viewed by clients. Instead you can create the token manually and add it to the Bing components or automate token creation by utilizing server-side code to generate and pass a token to the ArcGIS Silverlight application.

To generate a token manually using a Web page, see the information available on a pre-created token page. The following steps outline a programmatic server-side solution for generating and passing a token to a Silverlight application.

Create an ASP.NET Web application and a Web page (aspx) to host your ArcGIS Silverlight application.

In the Web application project, add a Web Reference to the Bing Maps Token Service

In Visual Studio launch the Add Web Reference dialog. Select the Add Web Reference item from either the Project menu or the contextual menu for the project in the Solution Explorer.

If you are using Visual Studio 2008 and Add Web Reference is not present in either the Project menu or the context menu for the project, do the following:
1. Select the Add Service Reference menu item.
2. Click on Advanced.
3. Click on Add Web Reference.

Enter either the staging or production Token Service URL from the list below for the Url and click Go. You must generate a token from the appropriate environment to use it in the respective environment. For example, to use imagery, geocoding, or routing services in the production environment, you must generate a token use the token service in the production environment.

Staging Environment
https://staging.common.virtualearth.net/find-30/common.asmx?wsdl

Production Environment
https://common.virtualearth.net/find-30/common.asmx?wsdl

To access the Production environment, you must be a licensed customer. Contact the Microsoft Bing Maps Licensing Team for more information.

When prompted, enter your Bing Maps Developer account id and password. On the Manage Account page of the Bing Maps Customer Services site you will find your account id.
Once the WSDL has been downloaded, give the web reference a name such as "TokenService". Click Add Reference.

In the code-behind, in the Page_Load method, create a new CommonService instance (a SOAP proxy class in the web reference) and define its Credentials property using the Bing Maps Developer account id and password.
Optional. Create a TokenSpecification instance to define the span of time for which the token will be valid. The maximum value is 8 hours (480 minutes). You should also provide the IP address of the site hosting the Silverlight application.
Generate a client token by calling the CommonService.GetClientToken method and pass the TokenSpecification instance, if available. A token string will be returned.

Create a string which will include the token and the environment (production or staging). Include both as an argument/value pair ("argument=value"). This string will be passed as a parameter to the Silverlight object.

Use the following code as an example of the server-side technique for generating a Bing Maps token.

MyPage.aspx

<script language="C#" runat="server">
	
        bool useStagingServer = true;
        private string BingAccountID = "121212";
        private string BingAccountPassword = "mypassword";
	
        public string bingInfo;
        
        protected void Page_Load(object sender, EventArgs e)
        {
            BingApp.Web.TokenService.CommonService commonService =
                new BingApp.Web.TokenService.CommonService();
	
            string bingToken = null;
	
            //Use staging server instead of production server
            if (useStagingServer)
            {
                commonService.Url = "http://staging.common.virtualearth.net/find-30/common.asmx";
            }
            else
            {
                commonService.Url = "http://common.virtualearth.net/find-30/common.asmx";
            }

            commonService.Credentials = new System.Net.NetworkCredential(BingAccountID, BingAccountPassword);

            BingApp.Web.TokenService.TokenSpecification tokenSpec = new BingApp.Web.TokenService.TokenSpecification();

            // Set the token specification properties
            tokenSpec.TokenValidityDurationMinutes = 480; //8 hours is the maximum allowed
            if (System.Web.HttpContext.Current != null && !System.Web.HttpContext.Current.Request.IsLocal)
            {
                tokenSpec.ClientIPAddress = System.Web.HttpContext.Current.Request.UserHostAddress;
            }
            else
                tokenSpec.ClientIPAddress = "127.0.0.1";

            try
            {
                bingToken = commonService.GetClientToken(tokenSpec);
            }
            catch (Exception ex)
            {
                string error = ex.Message;
            }

            // Define initialization parameters for Silverlight application startup object
            bingInfo = string.Format("token={0},useStaging={1}", bingToken, Convert.ToString(useStagingServer));
        }

</script>

The Silverlight plugin and application is referenced in the aspx page (and html page) using an object tag. The initParams parameter is used to pass information as a comma-delimited string or argument/value pairs. In the example below, the server variable bingInfo is passed as the value of the initParams parameter. The bingInfo variable contains the token and environment settings.

MyPage.aspx

<object data="data:application/x-silverlight-2," type="application/x-silverlight-2"
            width="100%" height="100%">
            <param name="source" value="ClientBin/BingApp.xap" />
            <param name="minRuntimeVersion" value="3.0.40624.0" />
            <param name="initParams" value="<% =bingInfo %>" />
</object>

Bing components in the ArcGIS Silverlight API need the token to function. They also need to know which environment to use (production or staging). One simple technique for providing this information to a Silverlight application involves passing it as an initialization parameter in the host page, as illustrated in the previous step. To capture and use this information open the code-behind for the Silverlight application startup object. In most cases, the default startup object for a Silverlight application is App.xaml.

In the code-behind:
1. Add a property to reference the Bing Maps token string
2. Add a property to reference the Bing Maps environment string
3. Set the property value using the initialization parameters available during the Application Startup event
Use the following code as an example for capturing and storing the Bing Maps token on Silverlight application initialization:

App.xaml.cs
```
        // Store a reference to the Bing Services token string
        public string BingToken { get; set; }
        public bool UseStagingServer { get; set; }

        private void Application_Startup(object sender, StartupEventArgs e)
        {
            //Get token generated on the server (aspx) and provided as an initialization parameter 
            BingToken = e.InitParams["token"];
 
            // Set whether to use staging or production server in the aspx
            UseStagingServer = bool.Parse(e.InitParams["useStaging"]);

            this.RootVisual = new Page();
        }
```

You can now access the Bing Maps token in the code-behind a Silverlight application XAML page. Where necessary you can access the application startup object using the Application.Current property. Merely cast to the explicit startup object type which defines the public property that references the Bing Maps token and environment string. On Bing components in the ArcGIS Silverlight API, define the Token property (e.g. TileLayer) or pass the token string to a constructor (e.g. Geocoder). Set the ServerType property to the appropriate environment value.

Use the following code as an example to set the token for a Bing component:

Page.xaml

<esri:Map x:Name="MyMap" Loaded="MyMap_Loaded">
	<esri:Map.Layers>
		<ve:TileLayer ID="BingLayer" LayerStyle="AerialWithLabels"/>
	</esri:Map.Layers>
</esri:Map>

Page.xaml.cs

private void MyMap_Loaded(object sender, RoutedEventArgs e)
{
    // Associate Bing Services token provided as initialization parameter to application with 
    // the Bing tile layers defined in page xaml.  
    foreach (Layer layer in MyMap.Layers)
        if (layer is TileLayer)
        {
            (layer as TileLayer).Token = (Application.Current as BingApp.App).BingToken;
            if ((Application.Current as BingApp.App).UseStagingServer)
                (layer as TileLayer).ServerType = ServerType.Staging;
            else
                (layer as TileLayer).ServerType = ServerType.Production;
        }

To view a complete solution, download the code for the Bing Maps sample.