ArcGIS Resource Center

The Silverlight API is a client application dependent on services that might fail or be unavailable. In general, the Map control will not throw an exception if one service fails. This means that if one service is down, the application will continue to run and access the remaining layers. However, it also means that you don’t automatically get any error reporting, and if all your services fail, you will just end up with a blank map.

When looking at the ESRI Silverlight forums, several users have reported issues with getting their layers to display or encountering blank maps. This blog post tries to outline the common reasons why a service does not display in the map, and how to remedy it.

Most of the problems with a missing layer are related to browser security issues, so to trouble shoot client applications, there is one tool that I will recommend anyone to get familiar with: Fiddler. This is a free HTTP tracing tool that tracks the requests and responses between the browser and the web server, and logs if any requests failed. You can download this tool from http://www.fiddler2.com/.

Once installed and launched, any network traffic initiated by Internet Explorer will be tracked by Fiddler. Note that any traffic to http://localhost/ is not tracked by default, and requires extra configuration. Other browsers might also require explicit configuration to work with Fiddler. I will be using Fiddler several times in this blogpost to track down issues you may experience.

Cross-domain limitations

Let’s for sake of argument say you installed ArcGIS Server on your own server, and you are trying to use one of its services. You first navigate to a service at your REST endpoint and copy/paste the URL to a layer in your Silverlight application, but the layer never shows. Let’s see what happens in Fiddler:

We see two requests. Both are highlighted in red, meaning an error occurred, and from the result code “404″ we can see that none of these files were found. So what are these files it tries to get from the root of my map server?

Silverlight does not allow you to make requests to servers hosted on a different host than your web application. In this case I was running my application on http://localhost/, and trying to access a service on http://myserver/.  Silverlight will first verify that the server allows other applications to perform requests against that server. It does this by trying to download a clientaccesspolicy.xml file from the domain. This is a Silverlight access configuration file telling the client who can call the server and which parts it can request. Flex has a similar pattern in place using a crossdomain.xml file. If it fails to find the clientaccesspolicy.xml file, Silverlight will try and search for Flex’s crossdomain.xml file and use that instead. If both fail, services on the server will be unavailable, the layer will not be able to initialize itself, and it will not render in the map. You can read more about this Silverlight security feature here, and you can look at the policy file that ArcGIS Online uses here.  If your services and application are hosted on the same domain AND port number, this should not be an issue. It’s worth noting the port constraint, since Visual Studio by default will run the autogenerated test-website on a different port on localhost than your ArcGIS REST services (not to mention that you shouldn’t be using localhost in the Url for layer since ‘localhost’ would mean something different to each client hitting your Silverlight application).

The cross domain restriction is by far the number one reason for a service failing to load.

Cross-scheme access

Another security feature in Silverlight is one preventing you from requesting data across different schemes, like http:// https:// and file://.  If you try to run a Silverlight application with a Map control using file:// in your browser URL, you might see this in your Map control:

This is because the Map control will need to be in an application hosted on a http or https website, but you are running the application from the file system (scheme).  To resolve this, make sure your Silverlight application hosted by a Web server and make sure the Web site is set as the startup project in Visual Studio. When you start a new Silverlight application project in Visual Studio, make sure you say yes to create a Web site to host your application in:

Restrictions also apply to http and https schemes. If your application is hosted on https and your service is hosted on http, or visa versa, you can access the service if explicitly permitted by the clientaccesspolicy.xml.  You cannot access images across schemes though, so while a request for service metadata may succeed, the request for a dynamic map image or cache tile will fail.   An upcoming blog post will cover this scenario in more detail. 

Hopefully at this point you’re able to see your map, and Fiddler will show something like:

In sequence you will see one successful request for clientaccesspolicy.xml, then a request for the service metadata, next a request for an image url, and lastly for the actual map image that was generated. Depending on which service type you are using, the last two requests may be different. The above example is using a dynamic map service.

Service output folder configuration

If you still have problems displaying the map service and you see something like below in Fiddler, you might have a configuration issue on your server end:

Notice how it requests images from “myserver”, but in the end tries to request an image from “localhost” (or some other domain/website unknown to the Silverlight client). If this is the case, the output folder of your ArcGIS Server service is not set up correctly.  Use Manager or Catalog to define the appropriate url to the output folder. 

Unsupported file format (GIF)

Silverlight does not support the GIF image format. If you are using a tiled service that has the tiles cached as GIF, it will not work with the ArcGIS Silverlight API.

Tiled layers – Wrong spatial reference

ArcGISTiledMapServiceLayer does not support re-projecting on the fly. This means that if you try and mix cached layers of different spatial reference, one or more services will not display. The first layer in the ESRI Map Control that has a spatial reference set will define the spatial reference for the entire map*, and any cached layer not matching this spatial reference will not load. You will see a request for the service metadata in Fiddler, but no requests for any image tiles. 

*Note that you can override the default map projection by explicitly setting a startup extent with a spatial reference set. See the sample in the Interactive SDK. 

Handling service errors

In the beginning I mentioned that some servers might be unavailable, and the Map control will continue to run with the remaining layers. If this is the case, you may want to let the user know that there was a problem loading a layer.  All layers have an “InitializationFailed” event you can subscribe to, that will fire in the event of a layer failing to initialize. You can also use this yourself to track down any initialization issues as well.
To listen for it, add the highlighted code to your layer definition:

<esri:ArcGISDynamicMapServiceLayer
 ID=”StreetMap”
 InitializationFailed=”layer_InitializationFailed”
 Url=”http://myserver/ArcGIS/rest/services/StreetMapUSA/MapServer” />

In the event handler you can check the InitializationFailure exception to determine what the problem was, and display a message to the user. Example:

private void layer_InitializationFailed(object sender, EventArgs e)
{
  Layer layer = sender as Layer;
  MessageBox.Show(string.Format(“Layer ‘{0}’ is currently unavailable. Error: {1}”,
     layer.ID, layer.InitializationFailure.Message));
}

Morten Nielsen
Senior Software Engineer
ArcGIS Server.NET, Silverlight/WPF, MapIt