When you work with map caches in client applications, consider how each application works with the tiles, whether it stores tiles locally, and what conditions it requires for cache overlays.
How applications access and use the cache
Once you define a tiling scheme for your map service, the service immediately begins trying to use the cache. Any ArcGIS application that can display a map service uses the cache, although how the tiles are retrieved and used varies between applications.
Web applications
When developing with the ArcGIS API for JavaScript, you use a specific class to specify that you're connecting to a tiled (cached) map service. For example, you use ArcGISTiledMapServiceLayer to connect to a cached service. When you use the cached service, tiles are retrieved from the cache directory by REST calls to the map service. The tile request takes the form https://<map service URL>/tile/<level>/<row>/<column>.
If you are viewing a single cached service in any web application and pan to an area where tiles do not exist, the application does not display a dynamic image; instead, you don't see anything. One way to ensure that you see a map when you pan to an uncached area is to enable on-demand caching.
Tip:
If the map appears more slowly than expected, examine the URLs of the map images to verify that the application is retrieving tiles. One way to do this is to open the application in Mozilla Firefox and click Firefox > Web Developer > Web Console. When the console appears, click the Net button and zoom or pan your map.
If you see URLs like this, your application is successfully getting tiles from REST requests:
https://gisserver.domain.com:6443/arcgis/rest/services/myService/MapServer/tile/10/1723/3495.jpg
If you see some other URL format for your map images, your application is retrieving the tile in a less efficient way or the cache is not being used.
ArcMap and ArcGIS Pro
You add cached map services to ArcMap and ArcGIS Pro using the Add Data button, the same way you add any other map service. There are two ways you can view a cache:
- Access the cache through a map service—To view a cache this way, browse to the GIS server and the map service used to create the cache. In this scenario, an initial connection to the GIS server is made to determine if the service has a cache. Then the tiles are retrieved from the cache directory on the server's file system.
- Access the cache as a raster dataset—To view a cache this way, browse to the directory containing the cache tiles and add the dataset. The cache is represented with the same icon used to add all other rasters using the Add Data button. A cache accessed as a raster is for viewing only and cannot be queried. The advantage with this type of cache is that it is not tied to a map service and can be viewed when disconnected from the server, as long as you can still access the cache directory.
When a request is made for a tile at a scale that exactly matches a scale level in the cache, the map service returns the tile directly. Most often, requests do not exactly match the scale levels in the cache. In this situation, the tile from the next closest scale level is requested and resamples it to match the requested scale. This resampling is still much quicker than generating a tile dynamically; however, it does result in an image that looks different than the original tile. Map labels that have been cached may be difficult to read at certain scales due to this resampling. For best results, view the map at or near the scales from which the cache was created.
Printing maps with cached content
The standards for map caches and web map printing align in the need for consistent performance at many scales. However, you may find that the resolution of a cached map service is unsatisfactory for printing quality. Printed maps often require a resolution of 200 dots per inch (dpi) or greater, while map caches in ArcGIS generally display at 96 dpi.
The PrintingTools service that's built in to ArcGIS Server allows you to balance the objectives of map caching and map printing. To do so, it uses dynamic layers, which are enabled by default on map services.
The service takes into account whether dynamic layers are enabled. When a map service (including a WMS service) with cached content has dynamic layers enabled, the service queries the source data for the map service to export the map extent at a higher resolution. This is a dynamic operation that bypasses the map cache.
If dynamic layers are not enabled on a map service or WMS service with cached content, the PrintingTools service instead exports the map extent from the cache on the server site. The map result of this operation will be at the 96 dpi resolution of the map cache, which may not satisfy expectations for a printed map.
To print high-quality output (in other words, print-quality resolution) from a cached map service using the PrintingTools service, it is recommended that you have the dynamic layers option enabled.
Improve the display performance of cached map services
When clients send requests to ArcGIS Server to display a map service, the response from the server is typically cached by the browser and reused for a certain period of time. This behavior helps ArcGIS Server achieve the best possible display performance for your map service. However, depending on how your map service and its associated data are used in applications, you may consider adjusting the length of time the browser will use a response in its cache. This can be achieved by adding a property named cacheControlMaxAge to the JavaScript Object Notation (JSON) of the service.
How the cacheControlMaxAge property is used
ArcGIS Server map service responses include an entity tag (ETag) and Cache-Control header. The ETag header value is a unique identifier of the response. The Cache-Control header has a max-age value that provides information to the browser regarding the maximum time period for which it can reuse a response from the browser's cache. This value is controlled by the cacheControlMaxAge property.
When a request is repeated and the maximum age of the cache has not expired, the browser will use the cached response without sending the request to the server. If the maximum age has expired, the browser must send the request to the server and set an IF-NONE-MATCH header with an associated ETag value corresponding to the response in its cache. ArcGIS Server evaluates the request and uses the ETag value to determine if the response has changed. If the response from the server is different from the copy on the browser, the server will send a completely new response to the browser. If the response is identical to the copy on the browser, the server alerts the browser to continue to use the response in its cache.
Define the value of the cacheControlMaxAge property
To specify how long a browser is allowed to use a cached response, define the cacheControlMaxAge property. This property can be set for individual service caches. By mitigating the need for ArcGIS Server to send a full response, you allow your browser caches to be more efficient, help optimize your applications, and save network bandwidth.
For cached map services that do not allow clients to cache tiles locally, the default is 0. This means the browser will always resend a request and ArcGIS Server will process the request and send a full response to the browser if the content has changed. This value works well for most applications.
For cached map services that allow clients to cache tiles locally, the default value is 86,400 seconds (1 day). This means that if a request is repeated within 1 day, the browser will use the response from its cache.
Learn more about local cache storage
For cached map services in which the map or data does not change frequently, it is recommended that you increase the default to 30 days (259,2000 seconds) or longer to minimize network traffic.
To add the cacheControlMaxAge property to your service and specify its default value, do the following:
- In a web browser, open the ArcGIS Server Administrator Directory and log in with a user that has administrator privileges. The URL is formatted https://gisserver.domain.com:6443/arcgis/admin.
- Click services and select the map service you want to modify from the Services list. If you don't see your service listed, it may be in a directory under Root folder.
- On the Service - <service name> (<service type>) page, scroll to the bottom and click edit.
- On the Service Properties dialog box, locate the properties section of the service JSON.
- Add the cacheControlMaxAge property to the section and specify the value (in seconds) for the property, for example:
"properties": { "cacheControlMaxAge": "2592000", - Click Save Edits.
- On the Service - <service name> (<service type>) page, verify that the cacheControlMaxAge property and the value you specified for it appears in the Properties section.
Overlaying caches
When designing map caches that will be overlaid with other map caches, applications require that you match coordinate system and tile size. It's also a good practice to match as many scales as possible.
The easiest way to do this is to match tiling schemes for both caches, then only create tiles at the scales that make sense for each cache. This way, you can be sure that you've matched coordinate system and tile size and that the software recognizes that the two caches have scales in common.