Frequently asked questions

Sections:

• Installation
• Getting started
• Adding layers
• Working with layers
• Deploying
• Extending

Installation

Question: Do I have to install the ArcGIS Viewer for Silverlight on the same machine as ArcGIS Server?

No. The ArcGIS Viewer for Silverlight does not have to be installed on the same machine as ArcGIS Server. The minimum requirements are as follows:

• .NET Framework 3.5 SP1 or 4.0 runtime
• Static Content
• ASP.NET
• IIS Management Console

For additional information on installing the ArcGIS Viewer for Silverlight on specific operating systems, see System requirements.

Getting started

Question: How do I start the Application Builder?

Start (open) the Application Builder via the Start menu: Start>All Programs>ArcGIS>ArcGIS Viewer for Silverlight 3.3>ArcGIS Viewer for Silverlight 3.3. Alternatively, you can open a Web browser and type http://<machine_name>/builder.

Question: Do I need to install the ArcGIS API for Silverlight to use the ArcGIS Viewer for Silverlight?

No, the ArcGIS API for Silverlight is not required to use the Application Builder to configure the ArcGIS Viewer for Silverlight. The ArcGIS API for Silverlight is only required if you want to extend the Viewer by creating custom add-ins, in which case you need to install the ArcGIS Extensibility SDK for Silverlight. The software development kit (SDK) installer includes an option to install the ArcGIS Viewer for Silverlight.

Question: Can I work in a disconnected or firewalled environment?

While the ArcGIS Viewer for Silverlight is designed to work with online services, there may be times you find it necessary to temporarily work in a disconnected environment. In this case, you need to remove the ArcGIS Online Streets layer from the Map.xml file and replace with a base map on your local intranet. The Map.xml file is located in your install folder, for example: C:\inetpub\wwwroot\Builder\Templates\Default\Config. If you do not remove the ArcGIS Online Streets layer and replace it with your basemap, you will receive an "Error initializing layer: Streets" message and will not be able to continue configuring with the Application Builder. If you work in a firewalled environment, you should also (1) Update the default set of basemaps in Builder\App_Data\Basemaps.xml and Builder\Templates\Default\Config\Tools.xml, (2) Update the ArcGIS Online Sharing and Secure URLs through either the Builder settings user interface (UI) or Builder\App_Data\Settings.xml, and (3) Update the geometry task URL through either the Builder settings UI or Builder\App_Data\Settings.xml.

Question: How do I connect to Portal for ArcGIS?

Portal for ArcGIS provides you with the same collaboration and sharing tools as ArcGIS Online, but differs in where it is hosted and what content is available to users. Portal for ArcGIS can be deployed behind your organization's firewall or a private instance can be hosted and managed by Esri for your organization. Settings for Portal for ArcGIS are contained on the Application Settings tab of the Application Builder settings page.

Problem: Cannot edit, copy, or delete site on Home page.

You may receive the preceding error (“Error occurred: System.Exception: Unable to find site with siteID …”) when attempting to edit, copy, or delete a site on the Home page. It is likely that a write to the sites.xml configuration file on disk has failed. In this case, the URL is visible in the Home page during the same session in which it was created because it is in the sites “catalog” in-memory, but on a refresh of the Builder disappears.

Workaround: On Windows XP 32-bit (x86) systems, the ASPNET account can be incorrectly set up causing a problem with permissions (that is, writing to directories). The solution is to explicitly grant permissions to ASPNET on the configuration files in the App_Data folder (permissions on the parent App_Data folder may not be inherited correctly). The App_Data folder is in the Application Builder's directory on disk (for example, C:\inetpub\wwwroot\Builder).

Problem: Error accessing application files.

When attempting to edit a previously-created site from your Home page, you may receive the following error. This indicates that you do not have a clientaccesspolicy.xml or crossdomain.xml file at your web root (for example, C:\Inetpub\wwwroot). For more information on the structure and function of a clientaccesspolicy.xml file, read the topic Network Security Access Restrictions in Silverlight. As an example, you can view the policy file used by ArcGIS Online: http://services.arcgisonline.com/clientaccesspolicy.xml.

Adding layers

Problem: I created a custom basemap, but when I click it in the gallery, nothing happens.

Verify that you have entered the URL to your ArcGIS Server basemap correctly. Note, dynamic map services are not supported for use as basemaps. For more information, see Configuring basemaps.

Question: How do I enable Bing Maps basemaps?

Bing Maps basemaps require a Bing Maps Key from Microsoft. See Getting a Bing Maps Key for more information. Once you have obtained a key, enter the key in the Application Settings tab of the Settings menu.

Problem: Cannot load data from my server.

1. If accessing ArcGIS Server services, make sure that the ArcGIS Services Directory is set up and functioning. Navigate to http://<host>/arcgis/rest/services in a browser. See the Services Directory main page for more information.
2. Make sure the Representational State Transfer (REST) endpoint for the service is available. Copy and paste the URL defined in your Silverlight/WPF application into a browser. For example: http://<host>/arcgis/rest/services/USA/MapServer.
3. If your Silverlight application is not hosted on the same server or domain as the data (services) you are accessing, you need a clientaccesspolicy.xml file on the remote server. See the next FAQ for more information.
4. Use the InitializationFailure event on the layer to determine if an error is occurring, and interrogate the error message.
5. View the HTTP request and response using a standard tool for interrogating HTTP communication such as Fiddler, Silverlight Spy, FireBug (FireFox add-on), and so on.

Problem: Cannot load data from an external data source outside your Silverlight application's domain.

To access data from a remote server, the remote server needs to have a clientaccesspolicy.xml file in the web server's root directory (for example, c:\inetpub\wwwroot). The ArcGIS Viewer for Silverlight is built on the Microsoft Silverlight platform. For security reasons, a Web browser is not allowed to access data that resides outside the exact Web domain where Silverlight application originated. However, a Silverlight application can load data across domains if permission is granted from the server. This is accomplished by having a small clientaccesspolicy.xml file on the remote server that permits Silverlight to connect to services on that server. For additional information, read the topic Making a Service Available Across Domain Boundaries. For more information on the structure and function of a clientaccesspolicy.xml file, read the topic Network Security Access Restrictions in Silverlight. As an example, you can also view the policy file used by ArcGIS Online:http://services.arcgisonline.com/clientaccesspolicy.xml.

ArcGIS Online clientaccesspolicy.xml content

<?xml version="1.0" encoding="utf-8" ?>
<access-policy>
  <cross-domain-access>
    <policy>
      <allow-from http-request-headers="*">
        <domain uri="*"/>
        <domain uri="http://*"/>
      </allow-from>
      <grant-to>
        <resource path="/" include-subpaths="true"/>
      </grant-to>
    </policy>
  </cross-domain-access>
</access-policy>

Question: How do I use a proxy page to access secured services?

The ArcGIS Viewer for Silverlight supports adding secured services via a proxy as detailed in the topics Adding secured services and Configuring a proxy.

Working with layers

Question: How do I specify my own address locator for the Search tool?

The Search tool is now configurable in the Application Builder and the Places search functionality can be used with any ArcGIS Server Locator service. See Configuring the Search tool for information.

Question: How can I change the fields displayed in the pop-up window and the attribute table?

By default, the pop-up window and the attribute table display all of the fields of a particular layer. To change the fields that are shown, select the layer in the Configure Layers panel, and click Configure. Select either the Pop-ups or Table option and set the Visibility as desired. See Configuring a layer's fields for more information.

Problem: I cannot select features. The Select tool is disabled (dimmed).

Features within ArcGIS Server Map Service layers cannot be selected. To allow selection of features belonging to a layer within an ArcGIS Server map service, you need to add that layer directly to the map from the Browse panel. For more information on the types of map services and layers that can be added and the behavior associated with each, see Layer types.

Question: Why are my point features grouped together? (clustered).

Clustering is enabled by default when there are more than 1000 features. You can set the clustering options on a per-layer basis. For more information, see Clustering and Feature retrieval.

Problem: Only the first 500 or 1000 features of my service display.

By default, ArcGIS Server 10.0 and later map services limit the number of records returned in response to a query to 1000 records. Earlier versions of ArcGIS Server set this limit at 500 records. Beginning with ArcGIS Server 10.0, you can raise this limit in the Service Properties dialog box in either ArcCatalog or ArcGIS Server Manager. For ArcGIS Server 9.3.1 and earlier, you must manually set the MaxRecordCount property in the configuration file at <ArcGIS install location>\Server\user\cfg\<configuration file name>.cfg.

In the Application Builder, you can configure feature retrieval settings on a per-layer basis. This allows you to either retrieve all features at once (up to the maximum record count) or to retrieve features as you pan around the map. By default, the Application Builder loads features as you pan around the map (that is, on-demand). See Feature retrieval for more information.

Note:

Responses that include a large number of features take more resources to serve than those with fewer features. This is the reason for the existence of the MaxRecordCount limit. If you are considering increasing the MaxRecordCount, you should test anticipated usage scenarios with the new limit to ensure that service performance is acceptable.

Question: Are there out-of-the-box tools to search my local data?

No. The Search tool included with the Application Builder is designed to allow you to search for places, search ArcGIS.com, and search the Web. It is not designed to search your data. For functionality not covered by the Search tool, you can create a custom add-in.

Problem: Feature layers in my app break when layers in the underlying map service are added, removed, or reordered.

Feature layers in your Silverlight Viewer app point to specific layers in a map service using the layer index as part of the URL. The layer index is zero-based, so the third layer in the Boulder map service, for example, would have a URL like this: http://myServer/arcgis/rest/services/Boulder/MapServer/2. If a new layer is added to the Boulder service as the first layer (position 0), the layer you want in your app is now the fourth layer in the service (index position 3). Your Silverlight Viewer app has no way of tracking such changes in the underlying service, so will continue to point to the layer at the original index position.

To update feature layers in your Silverlight Viewer app:

1. Open a web browser and navigate to the REST page for the map service your feature layers reference (http://myServer/arcgis/rest/services/Boulder/MapServer, for example). The layer positions are listed in parenthesis after each layer in the service directory page.
2. Open the Map.xml file for the viewer in a text editor (<install directory>\Apps\<Viewer Name>\Config\Map.xml).
3. Locate feature layer definitions in the file (search for esri:FeatureLayer, for example) and update the Url attribute as needed using the layer position information in the service directory page.
4. Save and close the Map.xml configuration file.

Deploying

Question: How do I deploy to another machine?

Once you are ready to deploy your Viewer application to a web server, copy the published web application folder(s) from your development machine to the Web resources directory of your production machine. For example, if you created a new application called "Site1," you would copy the Site1 folder from the Apps directory of your development machine to the Web resources directory of your publication machine. Depending on where you deploy it and how your production web server is configured, you may then need to configure a virtual directory to point to the copied directory.

Note:

ArcGIS Viewer for Silverlight is not required to be installed in the production environment.

Question: How can I implement security for the Viewer?

If you would like to add a login page to your published Viewer application, one method would be to configure ASP.NET forms-based authentication. See the blog post on ArcGIS Viewer for Silverlight security for detailed steps on configuring forms-based authentication for your application.

Extending

Question: How do I extend the ArcGIS Viewer for Silverlight?

The ArcGIS Viewer for Silverlight allows you to develop custom functionality by creating add-ins. To help you write add-ins, the Viewer provides a lightweight and flexible extensibility application programming interface (API). The API provides access to the map and selected layer, methods to show UI in dialog boxes, and the ability to store and load configuration data.

While the extensibility API provides a few simple points of interaction with the Viewer, what you can include in an add-in is very open-ended. Within an add-in, you may leverage any Silverlight library, including the ArcGIS API for Silverlight and the native Silverlight API. You are free to manipulate the map and layers, display any Silverlight UI, make your components configurable, interact with other Silverlight or JavaScript components on the page, make calls to web services such as those provided by SharePoint or ArcGIS Server, and much more. See Extending the ArcGIS Viewer for Silverlight for more information.

Question: How do I create a custom layout?

The easiest way to create a custom layout is to begin with the AArcGIS Viewer for Silverlight Visual Studio template that is included in the SDK. In the Layouts project, you will find a copy of each of the existing Viewer layouts (Accordion, Basic, Black Box, Black Box - Reverse, Floating Panels, Glass [default], Under Glow, and Wings). Use these as a starting point for modifying a layout in either Visual Studio or Microsoft Expression Blend. See Creating a custom layoutfor instructions. Also, see the Samples in the ArcGIS Viewer for Silverlight resource center.

Problem: The assembly 'xyz' is already included in the application runtime.

The error message when uploading an add-in that "The assembly 'xyz' is already included in the application runtime" is simply a warning and the add-in will still load successfully. To remove this warning, return to your Visual Studio solution and make sure that Copy Local=False for the references specified in the dialog box.