ArcGIS Runtime SDK for WPF - Library Reference
KmlLayer Class
Members  Example  See Also 
ESRI.ArcGIS.Client.Toolkit.DataSources Namespace : KmlLayer Class

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

Object Model

KmlLayer Class

Syntax

Visual Basic (Declaration) 
Public Class KmlLayer 
   Inherits ESRI.ArcGIS.Client.GroupLayer
   Implements ESRI.ArcGIS.Client.ILegendSupport 

Remarks

Enhanced functionality to support more KML elements was added in the ArcGIS Runtime SDK for WPF. 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. 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.

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 the geographic information on the client. 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 is however the recommended server to host KML/KMZ files via geographic web services as it generates KML/KMZ files natively as part of the web service publishing process from an ArcMap .mxd.

Developers who wish to test the KmlLayer functionality using KML/KMZ files locally on their development machine have the following options:

Option #1: 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 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

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).

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 Element Supportability 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>

Example

How to use:

When the Map initially loads a KmlLayer (Earth Quakes in the last 7 days) will be added that was defined in XAML. Click the button to add another KmlLayer (Volcanoes of the World) using code-behind logic.

The XAML code in this example is used in conjunction with the code-behind (C# or VB.NET) to demonstrate the functionality.

The following screen shot corresponds to the code example in this page.

Adding KmlLayers to the Map using XAML and code-behind.

XAMLCopy Code
<Grid x:Name="LayoutRoot">
            
  <!-- Add a Map Control. Zoom to the Central Europe/Mediterranean area. -->
  <esri:Map Background="White" HorizontalAlignment="Left" Margin="0,171,0,0" Name="Map1" VerticalAlignment="Top" 
            WrapAround="True" Height="419" Width="405" Extent="-692043,2479159,4226170,7567385">
    <esri:Map.Layers>
      <esri:LayerCollection>
                  
        <!-- Add a background ArcGISTiledMapServiceLayer for visual reference. -->
        <esri:ArcGISTiledMapServiceLayer 
          Url="http://services.arcgisonline.com/ArcGIS/rest/services/World_Street_Map/MapServer" />
          
        <!-- Add a KmlLayer that shows Earthquake occurrences over the last 7 days. Need to use a ProxyUrl. -->
        <esri:KmlLayer ID="Earth Quakes" 
                       Url="http://earthquake.usgs.gov/earthquakes/catalogs/eqs7day-age_src.kmz"
                       ProxyUrl="http://servicesbeta3.esri.com/SilverlightDemos/ProxyPage/proxy.ashx">
        </esri:KmlLayer>
        
      </esri:LayerCollection>
    </esri:Map.Layers>
  </esri:Map>
      
  <!-- Add a Legend Control to show the symbology of the Layers in the Map. -->
  <esri:Legend HorizontalAlignment="Left" Margin="403,171,0,0" Name="Legend1" VerticalAlignment="Top" 
               Height="419" Width="237" Map="{Binding ElementName=Map1}" 
               ShowOnlyVisibleLayers="True" LayerItemsMode="Tree" />
        
  <!-- Add a button that has the Click event wired up. The button will add another KmlLayer via the code-behind. -->
  <Button Content="Add KmlLayer 'Volcanoes of the World' to the Map." Height="23" HorizontalAlignment="Left" 
          Margin="0,144,0,0" Name="Button1" VerticalAlignment="Top" Width="640" Click="Button1_Click"/>
  
  <!-- Provide the instructions on how to use the sample code. -->
  <TextBlock Height="138" HorizontalAlignment="Left" Name="TextBlock1" VerticalAlignment="Top" Width="640" 
     TextWrapping="Wrap" Text="When the Map initially loads a KmlLayer (Earth Quakes in the last 7 days) will 
             be added that was defined in XAML. Click the button to add another KmlLayer (Volcanoes of the World)
             using code-behind logic." />
  
</Grid>
C#Copy Code
private void Button1_Click(object sender, System.Windows.RoutedEventArgs e)
{
  // Add another KmlLayer to the Map.
  
  // Create a new KmlLayer object. 
  ESRI.ArcGIS.Client.Toolkit.DataSources.KmlLayer theKmlLayer = new ESRI.ArcGIS.Client.Toolkit.DataSources.KmlLayer();
  
  // Set the KmlLayer's ID.
  theKmlLayer.ID = "Volcanoes of the world";
  
  // Set the Url of the KmlLayer. Note the Url takes a Uri object!
  theKmlLayer.Url = new Uri("http://sites.google.com/site/geined13/tours/Volcanoes_of_the_World.kmz?attredirects=0&d=1");
  
  // Need to use a ProxyUrl on the KmlLayer since the service is not hosted locally or on a local network.
  theKmlLayer.ProxyUrl = "http://servicesbeta3.esri.com/SilverlightDemos/ProxyPage/proxy.ashx";
  
  // Add the KmlLayer to the Map. An automaic refresh of the Map and Legend Controls will occur.
  Map1.Layers.Add(theKmlLayer);
}
VB.NETCopy Code
Private Sub Button1_Click(sender As System.Object, e As System.Windows.RoutedEventArgs)
  
  ' Add another KmlLayer to the Map.
  
  ' Create a new KmlLayer object. 
  Dim theKmlLayer As New ESRI.ArcGIS.Client.Toolkit.DataSources.KmlLayer
  
  ' Set the KmlLayer's ID.
  theKmlLayer.ID = "Volcanoes of the world"
  
  ' Set the Url of the KmlLayer. Note the Url takes a Uri object!
  theKmlLayer.Url = New Uri("http://sites.google.com/site/geined13/tours/Volcanoes_of_the_World.kmz?attredirects=0&d=1")
  
  ' Need to use a ProxyUrl on the KmlLayer since the service is not hosted locally or on a local network.
  theKmlLayer.ProxyUrl = "http://servicesbeta3.esri.com/SilverlightDemos/ProxyPage/proxy.ashx"
  
  ' Add the KmlLayer to the Map. An automaic refresh of the Map and Legend Controls will occur.
  Map1.Layers.Add(theKmlLayer)
  
End Sub

Inheritance Hierarchy

System.Object
   System.Windows.Threading.DispatcherObject
      System.Windows.DependencyObject
         ESRI.ArcGIS.Client.Layer
            ESRI.ArcGIS.Client.GroupLayerBase
               ESRI.ArcGIS.Client.GroupLayer
                  ESRI.ArcGIS.Client.Toolkit.DataSources.KmlLayer

Requirements

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

See Also

© ESRI, Inc. All Rights Reserved.