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:

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.

How to use:

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.

XAML

Copy 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://serverapps.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://serverapps.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.NET

Copy 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://serverapps.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

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

Target Platforms: Windows Vista, Windows 7

Reference