C# Class ESRI.ArcGIS.Client.Toolkit.DataSources.KmlLayer

A GroupLayer based upon the Keyhole Markup Language (KML) specification that targets the Google Maps level of support.

Enhanced functionality to support more KML elements was added in the ArcGIS Silverlight/WPF/Windows Phone API's at version 2.3. This brings the KML level of functionality very close to that of the KML specification used in Google Maps.

KML is an XML tag based syntax that holds geographic information (geometric shapes, symbology, and attributes) in a file with the .kml extension. The KmlLayer also support the KMZ specification which is essentially a set of zipped KML files, folders, and other documents (e.g. images, icons, html documents, etc. ) into a single file with the .kmz extension. To view the contents of a KMZ file, rename the file with the extension .zip and use a ZIP program to explode the contents onto a hard drive location.

KmlLayer is a GroupLayer

The KmlLayer is of Type GroupLayer meaning that certain KML elements are parsed out into individual Layers in a LayerCollection. As of version 2.3 of the API's, the following KML elements are parsed into the ArcGIS Layer types of:

KML Element(s)ArcGIS Layer Type <Placemark><Point>GraphicsLayer based upon MapPoint Geometries <Placemark><LineString>GraphicsLayer based upon Polyline Geometries <Placemark><Polygon>GraphicsLayer based upon Polygon Geometries <GroundOverlay>ElementLayer

Note: The KML elements of <Folder>, <Document>, and <NetworkLink> become child KmlLayers (which can be recursive in nature depending on the KML/KMZ file) and are parsed into the ArcGIS Layer types noted in the prior table. Additionally, a KmlLayer can contain other KmlLayers (which again can be recursive).

Drilling into individual Layers and their subsequent atomic level Types of a KmlLayer GroupLayer is accomplished via the KmlLayer.ChildLayers Property. See the code example in the KmlLayer.Name Property documentation for one example of drilling into the KmlLayer GroupLayer to obtain detailed information (like: Graphic Attributes, Graphic Symbology, Graphic Geometry, ElementLayer ElementType, ElementLayer Opacity, ElementLayer Envelope, etc.) that may be useful in creating an application.

Windows Phone specific issues

The KmlLayer.MapTip Property is only works in the Silverlight and WPF API’s; it is not supported in the Windows Phone API. TIP: For Windows Phone applications, when using a Legend Control buddied with a Map Control that contains a KmlLayer, use the Legend.LayerItemsMode = "Flat" in order to see the graphical symbols in the Legend. This is not a KmlLayer specific issue, rather a function of the default Legend template not taking advantage of the TreeView Control hierarchy for GroupLayers.

WPF specific issues

There is a known issue of KmlLayer symbols briefly flickering in the upper left corner of the Windows Desktop when a WPF application starts and stops.

Accessing KML/KMZ on the local hard drive

Accessing a KmlLayer is unique in that ArcGIS Server is not required to view geographic information. Since the KmlLayer is based upon a KML or KMZ file, all that is required is a web server to host the KML/KMZ file. NOTE: ArcGIS Server has the ability to host geographic web services created in ArcMap as native KML/KMZ files.

Developers who wish to test the KmlLayer functionality using KML/KMZ files locally on their development machine have several options depending on the API platform that they are developing on.

In Silverlight:

Option #1: Developers can place the KML/KMZ file in the ClientBin directory of the test web site that is generated when creating a Silverlight application using Visual Studios built in web server (i.e. the directory that has the path: ..\[APPLICATION_NAME].Web\ClientBin). This option is the easiest method for testing KML/KMZ files when there is no web browser security issues because all of the KML/KMZ functionality is self contained. See the code example in the KmlLayer.Url Property for one common workflow example of Option #1.

NOTE: If the KML/KMZ file has hyperlinks (i.e. they begin with http://) to resources (such as other KML/KMZ files) to locations outside of your local network, IT WILL BE REQUIRED to use Option #2 for local testing of KML/KMZ files. Some common KML tags (or nested sub-tags) that can use external hyperlinks outside of your local network include the following: <href>, <Style>, <Icon>, <IconStyle>, <StyleMap>, <NetworkLink>, and <styleUrl>. Additionally, if you get a Security Exception or unhandled exception 4004 errors in Visual Studio during your Silverlight application debugging, you will most likely need to use Option #2 instead.

Option #2: If the developer has installed a web server on the same computer as Visual Studio (for example: Internet Information Server (IIS)), then they can place the KML/KMZ file in an application directory of their local web server (i.e. http://localhost). Using this option has the additional requirements of:

Setting up the correct MIME type on the web server to handle KML/KMZ files Adding a crossdomain.xml file to the root of the web server Making use of a proxy to avoid Security Exception error messages

See the code example in the KmlLayer.ProxyUrl Property for one common workflow example of Option #2.

In WPF:

Option #1: Because WPF does not have the same security restrictions as Silverlight, developers can place a KML/KMZ file anywhere on the local hard drive and provide the file path as the KmlLayer.Url (example: Url="C:\TEST_KML_FILES\Test.kml").

Option #2: If developers want to use a local web server (like IIS) to place their KML/KMZ files for testing, they are free to do so just like in Silverlight (example: Url="http://localhost/TEST_KML_FILES/Test.kml"). NOTE: WPF does not use proxies so the use of KmlLayer.ProxyUrl is not necessary (even though the local KML file may have resource links (i.e. http://) to locations outside of the local network).

In Windows Phone:

Option #1: If developers want to use a local web server (like IIS) to place their KML/KMZ files for testing, they are free to do so just like in Silverlight (example: Url="http://localhost/TEST_KML_FILES/Test.kml"). NOTE: Windows Phone does not use proxies so the use of KmlLayer.ProxyUrl is not necessary (even though the local KML file may have resource links (i.e. http://) to locations outside of the local network).

Supported KML Tags

The following table lists the KML elements supported by the KmlLayer class, and provides additional notes for elements that are conditionally supported.

Supported KML ElementSupportability Notes <altitudeMode> Only 2D supported. <atom:author> The <atom:author> 'name' attribute is stored in the ESRI.ArcGIS.Client.Graphic as an Attribute (where the key = 'name' in the key/value pairs of the IDictionary(Of String, Object)). When this value is defined on a container (<Folder> or <Document>), all <Placemark>'s in the hierarchy inherits from this value. <atom:link> The <atom:link> 'href' attribute is stored in the ESRI.ArcGIS.Client.Graphic as an Attribute (where the key = 'atomHRef' in the key/value pairs of the IDictionary(Of String, Object)). When this value is defined on a container (<Folder> or <Document>), all <Placemark>'s in the hierarchy inherits from this value. <atom:name> The <atom:name> 'href' attribute is stored in the ESRI.ArcGIS.Client.Graphic as an Attribute (where the key = 'atomHRef' in the key/value pairs of the IDictionary(Of String, Object)). When this value is defined on a container (<Folder> or <Document>), all <Placemark>'s in the hierarchy inherits from this value. <BalloonStyle> For the <BalloonStyle>, the nested <text> tag information is stored in the ESRI.ArcGIS.Client.Graphic as an Attribute (where the key = 'balloonText' in the key/value pairs of the IDictionary(Of String, Object)). NOTE: Whatever is specified as information in the <text > tag is used, there is no entity replacement. <color> Includes #AABBGGRR and #BBGGRR. <colorMode> Random mode not supported. <coordinates> <Data> Multiple <Data> tags can be nested within the <ExtendedData> tag. The <ExtendedData> tag corresponds to a System.Collections.Generic.List(Of ESRI.ArcGIS.Client.Toolkit.DataSources.Kml.KmlExtendedData). An <ExtendedData> tag is stored as a single key/value pair in the IDictionary(Of String, Object)) of the Graphic.Attributes Property (where the key = 'extendedData' in the key/value pairs of the IDictionary(Of String, Object)). Each <Data> tag holds three attributes: 'name', 'displayname', and 'value' and is stored as a KmlExtendedData object of the System.Collections.Generic.List(Of ESRI.ArcGIS.Client.Toolkit.DataSources.Kml.KmlExtendedData). Thus, the <Data> 'name' attribute maps to a KmlExtendedData.Name Property; the <Data> 'displayname' attribute maps to the KmlExtendedData.DisplayName Property; and the <Data> 'value' attribute maps to the KmlExtendedData.Value Property. <description> For the <description> tag the information is stored in the ESRI.ArcGIS.Client.Graphic as an Attribute (where the key = 'description' in the key/value pairs of the IDictionary(Of String, Object)). NOTE: Whatever is specified as information in the <description> tag is used, there is no entity replacement. The HTML content is allowed but is sanitized to protect from cross-browser attacks; entity replacements of the form $[dataName] are unsupported. <Document> From v2.3, the <Document> tag becomes ESRI.ArcGIS.Client.GroupLayers. <east> Part of <LatLonBox>. <ExtendedData> Multiple <Data> tags can be nested within the <ExtendedData> tag. The <ExtendedData> tag corresponds to a System.Collections.Generic.List(Of ESRI.ArcGIS.Client.Toolkit.DataSources.Kml.KmlExtendedData). An <ExtendedData> tag is stored as a single key/value pair in the IDictionary(Of String, Object)) of the Graphic.Attributes Property (where the key = 'extendedData' in the key/value pairs of the IDictionary(Of String, Object)). Each <Data> tag holds three attributes: 'name', 'displayname', and 'value' and is stored as a KmlExtendedData object of the System.Collections.Generic.List(Of ESRI.ArcGIS.Client.Toolkit.DataSources.Kml.KmlExtendedData). Thus, the <Data> 'name' attribute maps to a KmlExtendedData.Name Property; the <Data> 'displayname' attribute maps to the KmlExtendedData.DisplayName Property; and the <Data> 'value' attribute maps to the KmlExtendedData.Value Property. No support for SchemaData. <fill> <Folder> From v2.3, the <Folder> tag becomes ESRI.ArcGIS.Client.GroupLayers. <GroundOverlay> From v2.3, an ESRI.ArcGIS.Client.ElementLayer is created by <Folder> and <Document> tags to contain all the <GroundOverlay> tags of the container. Nested tags of <LatLongBox>, <rotation>, <color>, and <icon> are used. <heading> Supported when part of an <IconStyle> element for proper rotation of a point's image. <hotSpot> Supported for Symbol creation. <href> <Icon> Only the 'href' element of this complex element is supported. Rotation and scaling are supported. <IconStyle> <innerBoundaryIs> Only single interior ring supported. <kml> It's the root element of any KML document. <LatLonBox> Support for <Placemark> tags. Supported from v2.3 for <GroundOverlay> tags. <LinearRing> Supported, but only makes use of the <coordinates> sub element. <LineString> Supported, but only makes use of the <coordinates> sub element. <LineStyle> <Link> Supported, but only makes use of the <href> sub element. <MultiGeometry> Rendered but displayed as separate features in left side panel. <name> For the <name> tag the information is stored in the ESRI.ArcGIS.Client.Graphic as an Attribute (where the key = 'name' in the key/value pairs of the IDictionary(Of String, Object)). NOTE: Whatever is specified as information in the <description> tag is used, there is no entity replacement. <NetworkLink> From v2.3 support for <refreshInterval> tag and 'OnInterval' RefreshMode. Becomes a sub-layer in the ESRI.ArcGIS.Client.GroupLayer. <NetworkLinkControl> 'MinRefreshPeriod' supported from v2.3. <north> Supported as part of <LatLonBox>. <outerBoundaryIs> Implicitly from <LinearRing> order. <outline> <Placemark> Becomes an ESRI.ArcGIS.Client.Graphic in an ESRI.ArcGIS.Client.GraphicsLayer. <Point> Supported, but only makes use of the <coordinates> sub element. <Polygon> Supported, but only makes use of the <OuterBoundaryIs> and <InnerBoundaryIs> sub elements. <PolyStyle> Makes use of the tags <color>, <fill>, and <outline>. <refreshInterval> Supported from v2.3. <refreshMode> 'OnInterval' mode supported from v2.3. <south> Supported as part of <LatLonBox>. <Style> Supported, but only <IconStyle>, <LineStyle>, and <PolyStyle> sub-elements are supported. <StyleMap> Only 'Normal' style supported. 'highlight' style not supported. <text> <value> Replacement of $[geDirections] is not supported. <visibility> Visibility of containers (<Folder>/<Document>/<NetworkLink>) supported from v2.3. Visibility of features not supported. <west> Supported as part of <LatLonBox>. <width>
Inheritance: GroupLayer
Show file Open project: Esri/arcgis-toolkit-sl-wpf Class Usage Examples

Public Properties

Property Type Description
ClientCertificateProperty System.Windows.DependencyProperty
CredentialsProperty System.Windows.DependencyProperty
ProjectionServiceProperty System.Windows.DependencyProperty

Private Properties

Property Type Description
AssignFolderIDs void
ConditionalRefresh void
ConvertToSeekable Stream
DownloadContent void
GetBaseUri System.Uri
GetKmzContents System.Xml.Linq.XDocument
GetParentsAndSelf IEnumerable
GetProjectionService IProjectionService
GetUri System.Uri
InternalGenerateVisibilityIDs IEnumerable
IsContainerVisible bool
IsInRegion bool
IsStreamCompressed bool
KmlLayer ESRI.ArcGIS.Client.Toolkit.DataSources.Kml.Zip
LayerGraphics IEnumerable
LoadDocument System.Xml.Linq.XDocument
NeedNumericId bool
OnClientCertificatePropertyChanged void
OnCredentialsPropertyChanged void
OnProjectionServicePropertyChanged void
ParseKmlDocument void
ProjectGroundOverlays void
ProjectGroundOverlays void
ResetRefreshTimer void
SetProjectionService void
SetResolutionRange void
SetResolutionRange void
SetSourceInternal void
StartRefreshTimer void
StopRefreshTimer void
UnhookLayerEvents void
backgroundWorker_DoWork void
backgroundWorker_RunWorkerCompleted void
webclient_OpenReadCompleted void

Public Methods

Method Description
GenerateVisibilityIDs ( ) : IEnumerable

Generate the IDs of the folder that are currently visible.

This method is mainly useful for the webmap serializer

Initialize ( ) : void

Initializes the resource.
KmlLayer ( ) : ESRI.ArcGIS.Client.Toolkit.DataSources.Kml.Zip

Initializes a new instance of the KmlLayer class.
KmlLayer_InitializationFailed ( object sender, EventArgs e ) : void
KmlLayer_PropertyChanged ( object sender, PropertyChangedEventArgs e ) : void

Handles the PropertyChanged event of the KmlLayer. Loads and parses the KML source as soon as the layer is visible.
Map_PropertyChanged ( object sender, PropertyChangedEventArgs e ) : void
QueryLegendInfos ( Action callback, Action errorCallback ) : void

Queries for the legend infos of the layer.

The returned result is encapsulated in a LayerLegendInfo object. A group layer returns only one item describing the group layer (the legends of the sublayers are not returned by this method)

Refresh ( ) : void

Refreshes the KML layer by downloading and parsing the KML document.
RefreshOnRegion ( Envelope region ) : void
RefreshOnRegionAsync ( object sender, ExtentEventArgs e ) : void
RefreshTimer_Tick ( object sender, EventArgs e ) : void
SetSource ( Stream stream ) : void

Sets the KML stream source.

Use this method if you need to load KML from a local file or file stream.

SetVisibilityByIDs ( IEnumerable IDs ) : void

Set the folders visibility from an enumeration of Ids. These Ids are those used by the webmaps.

This method is mainly useful for the webmap serializer

Protected Methods

Method Description
OnLoaded ( ) : void

Occurs when this layer is rendered.
OnMapChanged ( Map oldValue, Map newValue ) : void

Override to know when a layer's Map property changes.
OnUnloaded ( ) : void

Occurs when this layer is no longer connected to the main object tree.

Private Methods

Method Description
AssignFolderIDs ( System.Xml.Linq.XContainer xContainer ) : void
ConditionalRefresh ( Envelope region ) : void

If the region matches the map extent, download the URL immediately else set the flag NeedRefreshOnRegion for further refresh
ConvertToSeekable ( Stream inputStream ) : Stream
DownloadContent ( Uri url ) : void

Download content using URL. This method may be called recursively if the KML file contains a network link.
GetBaseUri ( ) : Uri
GetKmzContents ( ZipFile zipFile ) : System.Xml.Linq.XDocument

Processes each file in the ZIP stream, storing images in a dictionary and load the KML contents into an XDocument.
GetParentsAndSelf ( KmlLayer kmlLayer ) : IEnumerable
GetProjectionService ( ) : IProjectionService
GetUri ( string url, Uri baseUri ) : Uri
InternalGenerateVisibilityIDs ( KmlLayer layer ) : IEnumerable
IsContainerVisible ( string path, bool defaultVisibility ) : bool
IsInRegion ( Map map, Envelope region ) : bool
IsStreamCompressed ( Stream inputStream ) : bool
KmlLayer ( KmlLayer parentLayer ) : ESRI.ArcGIS.Client.Toolkit.DataSources.Kml.Zip

Initializes a new instance of the KmlLayer class which will be a child of another KmlLayer.
LayerGraphics ( Layer layer ) : IEnumerable
LoadDocument ( Stream stream ) : System.Xml.Linq.XDocument
NeedNumericId ( System.Xml.Linq.XElement element ) : bool
OnClientCertificatePropertyChanged ( DependencyObject d, System.Windows.DependencyPropertyChangedEventArgs e ) : void
OnCredentialsPropertyChanged ( DependencyObject d, System.Windows.DependencyPropertyChangedEventArgs e ) : void
OnProjectionServicePropertyChanged ( DependencyObject d, System.Windows.DependencyPropertyChangedEventArgs e ) : void
ParseKmlDocument ( ) : void
ProjectGroundOverlays ( ) : void
ProjectGroundOverlays ( ElementLayer layer, SpatialReference sref ) : void
ResetRefreshTimer ( ) : void
SetProjectionService ( IEnumerable layerCollection ) : void
SetResolutionRange ( ) : void

Sets the min and max resolution from the Region. If the layer is a networklink, the resolution is set on the layer itself If the layer is not a networklink, the resolution is set on the children that are not networklink.
SetResolutionRange ( Envelope envelope ) : void
SetSourceInternal ( Stream stream ) : void
StartRefreshTimer ( ) : void
StopRefreshTimer ( ) : void
UnhookLayerEvents ( ) : void
backgroundWorker_DoWork ( object sender, DoWorkEventArgs e ) : void
backgroundWorker_RunWorkerCompleted ( object sender, RunWorkerCompletedEventArgs e ) : void
webclient_OpenReadCompleted ( object sender, OpenReadCompletedEventArgs e ) : void

Event handler for when the KML file is completely downloaded. If the KML content contains a network link, then the linked content will be downloaded recursively. If no network link is detected, then the KML content is converted into a feature definition using the engine and eventually rendered as graphic g.

Method Details

GenerateVisibilityIDs() public method

Generate the IDs of the folder that are currently visible.
This method is mainly useful for the webmap serializer
public GenerateVisibilityIDs ( ) : IEnumerable
return IEnumerable

Initialize() public method

Initializes the resource.
public Initialize ( ) : void
return void

KmlLayer() public method

Initializes a new instance of the KmlLayer class.
public KmlLayer ( ) : ESRI.ArcGIS.Client.Toolkit.DataSources.Kml.Zip
return ESRI.ArcGIS.Client.Toolkit.DataSources.Kml.Zip

KmlLayer_InitializationFailed() public method

public KmlLayer_InitializationFailed ( object sender, EventArgs e ) : void
sender object
e System.EventArgs
return void

KmlLayer_PropertyChanged() public method

Handles the PropertyChanged event of the KmlLayer. Loads and parses the KML source as soon as the layer is visible.
public KmlLayer_PropertyChanged ( object sender, PropertyChangedEventArgs e ) : void
sender object The source of the event.
e System.ComponentModel.PropertyChangedEventArgs The instance containing the event data.
return void

Map_PropertyChanged() public method

public Map_PropertyChanged ( object sender, PropertyChangedEventArgs e ) : void
sender object
e System.ComponentModel.PropertyChangedEventArgs
return void

OnLoaded() protected method

Occurs when this layer is rendered.
protected OnLoaded ( ) : void
return void

OnMapChanged() protected method

Override to know when a layer's Map property changes.
protected OnMapChanged ( Map oldValue, Map newValue ) : void
oldValue Map Old map
newValue Map New map
return void

OnUnloaded() protected method

Occurs when this layer is no longer connected to the main object tree.
protected OnUnloaded ( ) : void
return void

QueryLegendInfos() public method

Queries for the legend infos of the layer.
The returned result is encapsulated in a LayerLegendInfo object. A group layer returns only one item describing the group layer (the legends of the sublayers are not returned by this method)
public QueryLegendInfos ( Action callback, Action errorCallback ) : void
callback Action The method to call on completion.
errorCallback Action The method to call in the event of an error (cant' happen with a group layer).
return void

Refresh() public method

Refreshes the KML layer by downloading and parsing the KML document.
public Refresh ( ) : void
return void

RefreshOnRegion() public method

public RefreshOnRegion ( Envelope region ) : void
region Envelope
return void

RefreshOnRegionAsync() public method

public RefreshOnRegionAsync ( object sender, ExtentEventArgs e ) : void
sender object
e ExtentEventArgs
return void

RefreshTimer_Tick() public method

public RefreshTimer_Tick ( object sender, EventArgs e ) : void
sender object
e System.EventArgs
return void

SetSource() public method

Sets the KML stream source.
Use this method if you need to load KML from a local file or file stream.
public SetSource ( Stream stream ) : void
stream Stream A stream to a KML or KMZ file.
return void

SetVisibilityByIDs() public method

Set the folders visibility from an enumeration of Ids. These Ids are those used by the webmaps.
This method is mainly useful for the webmap serializer
public SetVisibilityByIDs ( IEnumerable IDs ) : void
IDs IEnumerable Enumeration of visible folder ID.
return void

Property Details

ClientCertificateProperty public static property

Identifies the ClientCertificateProperty dependency property.
public static DependencyProperty,System.Windows ClientCertificateProperty
return System.Windows.DependencyProperty

CredentialsProperty public static property

Identifies the Credentials dependency property.
public static DependencyProperty,System.Windows CredentialsProperty
return System.Windows.DependencyProperty

ProjectionServiceProperty public static property

Identifies the ProjectionService dependency property.
public static DependencyProperty,System.Windows ProjectionServiceProperty
return System.Windows.DependencyProperty