Printing of the ArcGIS Map Control contents is accomplished via the ESRI.ArcGIS.Client.Printing.PrintTask Class. It is not printing directly to a device such as a printer or plotter, rather the PrintTask Class is used to generate an image for Printing. PrintTask operations are new as part of ArcGIS Server 10.1 and the ArcGIS API 3.0 for Silverlight.

Synchronous -vs- Asynchronous Geoprocessing Tasks

When it comes to using the PrintTask in web development using the ArcGIS API for Silverlight to generate an image on ArcGIS Server, as a developer you have two options: synchronous geoprocessing tasks and asynchronous geoprocessing tasks. In a traditional sense the terms "synchronous" means that your computer will wait while a process executes on the server and "asynchronous" means that your computer does not have to wait for the process to finish execution and you can move on to other operations. However in web development using Silverlight, all web requests are asynchronous in nature, meaning that once a web request has initiated you are free to perform other operations/functionality in your application as it remains highly responsive. When it comes to the PrintTask there are some important differences between the synchronous geoprocessing tasks and asynchronous geoprocessing tasks that are outlined as follows:

• A synchronous geoprocessing task means that once ArcGIS Server starts the task to generate the image, ArcGIS Server is dedicated to that operation until it completes. It should be noted that from the web based Silverlight application’s perspective, that once the synchronous geoprocessing task has been initiated you are still free to perform other operations as the application remains highly responsive. See the code example in the PrintTask.ExecuteAsync(PrintParameters,Object) Method for how a synchronous geoprocessing task works.
• An asynchronous geoprocessing task means that ArcGIS Server will control when it can handle generating an image based upon its computing load and will multi-task multiple operations simultaneously until the operation is complete. Again it should be noted that from the web based Silverlight application’s perspective, that once the asynchronous geoprocessing task has been initiated you are still free to perform other operations as the application remains highly responsive. See the code example in the PrintTask.SubmitJobAsync Method Method for how an asynchronous geoprocessing task works.

When constructing a PrintTask the following Types are used by both the synchronous geoprocessing tasks or asynchronous geoprocessing tasks:

• PrintTask Constructor
• DisableClientCaching Property
• ProxyURL Property
• Token Property
• Url Property

The following table illustrates which PrintTask Types are dedicated exclusively to a synchronous geoprocessing task or an asynchronous geoprocessing task:

As a developer of a web based Silverlight application, when choosing whether to perform a PrintTask based upon the methodology of synchronous geoprocessing task or an asynchronous geoprocessing task, the following information may be helpful in the decision making process:

• By default, a synchronous geoprocessing task is created when ArcGIS Server is installed and initially configured. This means that no other work is required on ArcGIS Server to enable using the PrintTask (other than starting the PrintingTools, Geoprocessing Service) by an ArcGIS Silverlight application developer. Typically in ArcGIS Server, this synchronous geoprocessing task is located under in the ArcGIS REST Services Directory in the Utilities folder as an Utilties/ExportWebMap (GPServer) Service. The Task is usually called Export Web Map Task and has an Execution Type of esriExecutionTypeSynchronous. For example, assume for the sample ESRI ArcGIS Server (http://servicesbeta2.esri.com/arcgis/rest/) the PrintTask.Url for the synchronous geoprocessing task would be as follows (see the following screen shot):

  

• For small PrintTask operations using a synchronous geoprocessing task will probably yield faster results in generating a return image/pdf.

• A web based Silverlight application can only issue one PrintTask via a synchronous geoprocessing task at a time. This means that it is not possible to have multiple PrintTask operations (i.e. generating multiple image/.pdf files at a time) using a synchronous geoprocessing task. Use the PrintTask.IsBusy Property to determine if an existing synchronous geoprocessing task is running before issuing the PrintTask.ExecuteAsync Method to avoid the Visual Studio runtime error: NotSupportedException was unhandled by user code ("Task does not support concurrent I/O operations. Cancel the pending request or wait for it to complete").

• If multiple simultaneous PrintTask operations are necessary from a single web based Silverlight application (i.e. an application that produces numerous images/.pdf for cartographic production), then use the asynchronous geoprocessing task options for better performance.

• If the PrintTask operations will be used for very large image/.pdf generation or numerous ArcGIS Silverlight applications will be utilizing a single ArcGIS Server and thereby causing internet browser time-out error messages, then an asynchronous geoprocessing task may be the better choice. It may be possible to increase the amount of time an internet browser waits before a time-out error message occurs when using a synchronous geoprocessing task but this will require testing to determine which option is best for your organization.

• Using an asynchronous geoprocessing task requires configuring an ArcGIS Server Geoprocessing Task. This is not done automatically as part of the ArcGIS Server installation/configuration. One option is to use ArcMap to run the ArcToolbox: Server Tools | Printing | Export Web Map tool and when the Results are completed right click on the ExportWebMap session and Share As a Geoprocessing Service that can be used by ArcGIS Server. Another option is to use the default ArcGIS Server: Printing Tools, Geoprocessing Service (located in the Utilities folder) that is created when ArcGIS Server is initially installed/configured and change its Execution Mode from Synchronous to Asynchronous (see the following screen shot for an example test ArcGIS Server running on the local developement computer) and re-starting the service:

  

  This will result in an ArcGIS REST Services Directory page that looks similar to the following screen shot:

  

• Using the PrintTask via asynchronous geoprocessing task Types provide much better options to track the status of image/.pdf creation. The PrintTask.StatusUpdated Event uses the ESRI.ArcGIS.Client.Tasks.JobInfoEventArgs Class to give instant status information of the operation.

Layout Templates

One common request by ArcGIS developers is the ability to produce a printed map with various marginalia. Marginalia are elements on a map that enhance its viewing and include items such as legends, titles, grids and graticules, scale bars, scale text, north arrows, spatial reference information, additional graphics and text items. For both asynchronous (via the PrintTask.SubmitJobAsync Method) and synchronous (via the PrintTask.ExecuteAsync Method) geoprocessing tasks on ArcGIS Server, it is the Printing.PrintParameters.LayoutOptions Property that controls the visual representation of the marginalia in the map that is returned from ArcGIS Server.

The Printing.LayoutOptions Class provides a mechanism to set various marginalia to augment what is seen in the Map Control on a printed map. Depending on the ArcMap graphic Elements in the Layout Template used to generate a printed map via the PrintTask Class, developers can set several LayoutOptions Class Properties to control the marginalia.

Note: An example of producing map with various marginalia using a Layout Template can be found in the example code section of the Printing.LayoutOptions Class document.

A Layout Template is a map document (.mxd) that is used to define the placement of a map and marginalia for use by ArcGIS Server to generate an output image. The default location where the Layout Templates are stored on ArcGIS Server is <install_directory>\Templates\ExportWebMapTemplates (see the following screen shot):

The filename without the .mxd extension should exactly match the names of the Layout Templates that are listed in Layout_Template parameter of the ArcGIS REST Services Directory under the Choice List option (see the following screen shot):

The default Layout Templayes may not make use of every option available in the various LayoutOptions Class Properties. It is the developer’s responsibility to work with the ArcGIS Server manager/administrator to understand what graphic Elements of a specific Layout Template is available for customization via the LayoutOptions Class Properties. The following table provides a list of the ArcMap supported graphic Elements in the Layout Template and how they correspond to the LayoutOptions Class Properties:

Note: the ArcMap DataFrame graphic Element in the Layout Template corresponds to the Map Control and is automatically set using the Printing.PrintParameters.LayoutTemplate Property.

It should be mentioned that there are numerous other ArcMap graphic Elements in a Layout Template that can be used to create an output map via the PrintTask Class. Not all of these graphic Elements can be controlled from the client application; they are static in nature in that they are preset when the Layout Template is originally created and published as a PrintTask ExportWebMap service via ArcGIS Server. The following ArcMap screen shot shows all of the graphic Elements that can be used in a Layout Template with those that can be controlled/adjusted by the client application highlighted in red:

The default installed Layout Templates may be insufficient to generate maps for custom client applications. Esri provides the ability to create custom Layout Templates with ArcMap and publish them as a print service via the ExportWebMap Geoprocessing task. The ArcGIS Server manager/administrator should work closely with the client application developer to achieve desired results in generating the custom Layout Template. During this process it may be necessary to go through several iterations to get the desired result. It should be noted that once a particular ExportWebMap Geoprocessing task is published on ArcGIS Server, that a snapshot of the ArcMap Layout Template .mxd document is used to generate the service. It is not possible to make a modification to the ArcMap Layout Template .mxd document and have that change reflected in an existing ExportWebMap Geoprocessing task service. If a change to the ArcMap Layout Template .mxd document is made, the ArcGIS Server ExportWebMap Geoprocessing task service should be deleted and re-published to reflect the new changes in the Layout Template. The LayoutOptions.CustomTextElements Property document provides a code example with workflow of how to create a custom Layout Template and publish an ArcGIS Server print task via the ExportWebMap Geoprocessing task service.

WYSIWYG Printing of Maps

The acronym WYSIWYG stands for "What You See Is What You Get" and is typically used to describe what you view on a digital screen (i.e. desktop computer, laptop, tablet, phone, hand held device, etc.) matches a hard copy print output. For a typical application using a 'screen capture' type of WYSIWYG printing, the Microsoft API Printing document serves as a starting point.

For ArcGIS developers who want to produce applications for cartographic map printing, the API's provided by Microsoft may be insufficient. ESRI provides additional resources via the ESRI.ArcGIS.Client.Printing Assembly that suit many of the needs for cartographic map printing via ArcGIS Server.

One common request by ArcGIS developers is the ability to replicate what is seen in the Map Control of an application on a printed map. In a nutshell, the key to producing a WYSIWYG printed output specifically for the Map Control involves:

• Knowing the Data Frame - Knowing the key pieces of information on the ArcGIS Server machine (specifically the Data Frame Height and Data Frame Width of the ArcMap Layout Template).
• Using a Ratio - Ensuring that the ratio between the Height and Width of the Data Frame in the ArcMap Layout Template exactly matches the ratio between the Height and Width of the Map Control in the application.
• Ensuring No Scale Dependency Layers - Ensuring that any map Layers in the ArcGIS Service does not use scale dependency visibility rendering (aka. no specific Scale Range was set in ArcMap when authoring the service. Make sure that the Layer is visible for all scale levels).

Note: An example of producing a WYSIWYG printed output specifically for the Map Control using various Layout Template options can be found in the example code section of the ESRI.ArcGIS.Client.Printing.MapOptions document.

ArcGIS Server uses the information provided from the client application to generate the image that is used for printing. There are several options available in the PrintTask.PrintParameters Class which can be used in almost unlimited combinations. The key to making a successful WYSIWYG printed output the Map Control, first involves understanding the constraints that ArcGIS Server has to generate the map image for printing. When a specific Scale and Extent are passed to ArcGIS Server from the client, the image generation process attempts to center the map based upon the Extent and maintain the Scale subject to the Data Frame that is used for a specific Layout Template. In most cases, the size and/or aspect ratio of the of the Map Control on the client does not exactly match the Data Frame on the ArcGIS Server and the result is often seeing more or less geographic coverage in the output image that what is in the Map Control (basically the Scale of the Map Control is different than that of the Data Frame of the Layout Template). Additionally when the Scale that is shown in the Map Control on the client does not match that of the Data Frame in the Layout Template, Layers may or may not draw based upon their scale dependency visibility setting. This may result in an output image that looks very different than what is on the client. How to obtain and use each of the three key pieces of information (listed previously) in order to produce a WYSIWYG printed output specifically for the Map Control will be discussed in more depth as follows:

Knowing the DataFrame

The Data Frame is the placeholder for the map (and it's Layers) within the Layout Template. In order to produce a WYSIWYG printed output specifically for the Map Control requires knowing the Data Frame Width and Height in the Layout Template. Using ArcMap, open a particular Layout Template map document (.mxd) and with the Layout View being active, right-click on the Data Frame element and choose Properties... from the context menu (see the following screen shot for opening the ‘Tabloid ANSI B Portrait.mxd’ file):

Then click on the Size and Position tab of the Data Frame Properties dialog to obtain the Width and Height arguments (see the following screen shot):

Using a Ratio

Because the exact aspect ratio of the Map Control on the client and the Data Frame of the Layout Template on ArcGIS Server will typically not match, this will result in scale differences that will give non-WYSIWYG output. To correct for this, it is necessary to create either Height-to-Width ratio or a Width-to-Height ratio using the results of the Height and Width arguments of the Data Frame. This ratio will then be used to adjust either the Height or Width of the Map Control in the client application and thereby ensure that what geographic coverage is in the Map Control exactly matches the Data Frame in the Layout Template. The following provides the generic algorithm for applying the ratio (only one is needed in your application):

            DataFrame.Height = X (<-- some static value)
            DataFrame.Width = Y (<-- some static value)
            MapControl.Height = Z (<-- some static value)
            MapControl.Width = MapControl.Height * (DataFrame.Width / DataFrame.Height)
            

            DataFrame.Height = X (<-- some static value)
            DataFrame.Width = Y (<-- some static value)
            MapControl.Width = Z (<-- some static value)
            MapControl.Height = MapControl.Width * (DataFrame.Height / DataFrame.Width) 
            

Ensuring No Scale Dependency Layers

Because the physical size of the Map Control in the client application and the Data Frame in the Layout Template will most likely not be exactly the same, the Scale will be different. While the Extent of the geographic coverage of the Layers in between the Map Control and the Data Frame may be the same (especially since you made sure the ratio between the two is the same), because the physical size of the two elements is different the Scale will also be inherently different. When Layers (or any sub-Layers) that have scale dependent visibility applied as you zoom in/out, the geographic features that are displayed could change. As a safety precaution to ensure WYSIWYG compliance, it is best that no scale dependency is set on any Layers that are desired to be visible in the Map Control. Examining the ArcGIS REST Services Directory for the Url of the web service for each Layer you can ensure that the Min. Scale and Max. Scale attributes are both zero (0) (see the following screen shot):

If it turns out that non-zero value are present in the web service, it may be necessary to re-author the ArcMap map document (.mxd) and re-publish the web service on ArcGIS Server. Setting the scale dependency visibility in ArcMap is done in the General tab of the Layer Properties dialog; look for the Scale Range section (see the following screen shot):

Discovering PrintTask Capabilities

It is possible to programmatically discover what capabilities are available for a particular PrintTask on an ArcGIS Server service using the PrintTask.GetServiceInfoAsync Method. When the PrintTask.GetServiceInfoAsync Method is called, ArcGIS Server returns an e.ServiceInfoEventArgs argument in the PrintTask.GetServiceInfoCompleted Event to provide the following information:

Note: An example of programmatically discovering what capabilities are available for a particular PrintTask can be found in the example section of the PrintTask.GetServiceInfoAsync Method documentation.

The same information in the e.ServiceInfo argument in the previous table can also found by examining the ArcGIS REST Services Directory for the PrintTask.Url (see the following screen shot):

Tips and Known Limitations*:

Symbols:

For triangles generated client-side in a (1) FeatureLayer or (2) DynamicLayer of an ArcGISDynamicMapServiceLayer, the PrintTask will produce solid-fill circles as the point marker symbol. This is planned to be corrected in a future version of ArcGIS Server and the ArcGIS API for Silverlight.

Custom symbols (point/line/polygon) generated client-side are 'downgraded' to simple symbols (point/line/polygon) when the PrintTask is used to generate media for hardcopy printing. Additionally, simple symbols that have a custom ControlTemplate applied on the client-side will also be 'downgraded' when the PrintTask is used to generate media for hardcopy printing. The term 'downgraded' means that the custom symbol will be black in color and be a solid-fill circle for a point, be a solid line for a line, or a solid fill for a polygon. The reason for this is that ArcGIS Server uses a different graphics engine that that of the ArcGIS API for Silverlight and is incapable of generating an exact match.

If Symbol.Color alpha values (meaning opacity) are used on the client-side as part of a ClassBreaksRenderer, the PrintTask will produce a solid color for the output symbol. This is planned to be corrected in a future version of ArcGIS Server and the ArcGIS API for Silverlight.

To generate correct PictureFillSymbols for use with the PrintTask, ensure that the height and width are proportional to the original image.

Only PictureFillSymbols that are selected on the client-side will display correctly from the PrintTask operation. If the PictureFillSymbols are not selected, only the outline is displayed. This is planned to be corrected in a future version of ArcGIS Server and the ArcGIS API for Silverlight.

GraphicsLayer:

Client-side generated GraphicsLayers should not contain mixed geometries if using the PrintTask to generate media for hard copy printing. If you need to print different geometries put each geometry type in its own GraphicsLayer. For example do not use a single GraphicsLayer that has both points and polygons; separate them into a point GraphicsLayer and a polygon GraphicsLayer.

FeatureLayer:

For client-side FeatureLayer.Geometry objects, if the FeatureLayer.Mode = SelectionOnly, the make sure and include the 'ObjectID' in the FeatureLayer.Outfields, otherwise all features in the FeatureLayer will be returned in the PrintTask.

Client-side FeatureLayers will only display Legend items that are viewable in the current Map Extent when the PrintTask is used. Legend items are dynamically generated by the PrintTask based upon the features that are currently viewable.

KmlLayer:

For the PrintTask, the KML specification of 2.0 and 2.1 is currently supported but the KML 2.2 specification is not. This means specifically that time animation, photo overlays, and schema tags will not generate appropriate output for the PrintTask. Enhanced KML support is planned to be supported in a future version of ArcGIS Server and the ArcGIS API for Silverlight.

For KML based layers, all elements are displayed via the PrintTask regardless of what is viewable in the client-application. This becomes particularly apparent when the KML graphics are contained in folders. This impacts the following: (1) KML folders that have graphics that are set to invisible are displayed, (2) the order of layers may not be respected in generating which graphics are drawn first, (3) layers that have opacity specified is not respected, and (4) labels cannot be turned off. Enhanced KML support is planned to be supported in a future version of ArcGIS Server and the ArcGIS API for Silverlight.

General:

Client-side generated HeatMap Layers are not generated by the PrintTask. Support for this functionality is planned for a future version of ArcGIS Server and the ArcGIS API for Silverlight.

To show a Legend in PrintTask, layers must have the Layer.ID Property specified. The generation of a Legend is supported on all Layout Template types except: MAP_ONLY. The Layout Template of MAP_ONLY only generates media for hard copy printing of what is in the Map Control.

Client-side generated ClassBreaksAger on temporal layers does not respect any opacity settings in the PrintTask. The whole layer will have the opacity applied rather than individual graphic elements. Additionally, track lines will appear on top of marker symbols in the PrintTask generated output. This is planned to be corrected in a future version of ArcGIS Server and the ArcGIS API for Silverlight.

* The Known Limitations apply to ArcGIS Server 10.1 and ArcGIS API 3.0 for Silverlight.

System.Object
   ESRI.ArcGIS.Client.Printing.PrintTask

Target Platforms: Windows XP Professional, Windows Server 2003 family, Windows Vista, Windows Server 2008 family, Windows 7

Reference