Welcome to Map Suite™ from ThinkGeo, a full-featured mapping control that makes it easy for any Microsoft .NET developer to add mapping functionality to a Microsoft .NET application quickly and efficiently. Using the intuitive object model, even developers inexperienced with Geographic Information Systems (GIS) can have fully functional maps working in minutes.

This guide will help you quickly get started building your own spatially aware applications. Like any new software, there will be some learning along the way.

How do we begin taking advantage of the power of Map Suite? The best way to learn is to make a sample application with it.

Before we get started, make sure you've installed the ThinkGeo Product Center and that you've either started an evaluation or activated a full license of Map Suite iOS or Android Edition. By default, this will install the Map Suite 9.0 Xamarin.Forms assemblies to C:\Program Files (x86)\ThinkGeo\Map Suite 9.0\Map Suite Xamarin Forms.

Download Sample Code From This Exercise (1.5 MB)

Please following our Xamarin.Forms Installation Guide for Xamarin.Forms development environment.

Let's start by creating a new Forms blank app in Microsoft Visual Studio (2012 or newer) named HelloWorld (see Figure 1). We can create the project with .NET Framework 4.5 or higher.

The project HelloWorld is created in a new solution called HelloWorld. The wizard creates a single blank Application(Xamarin.Forms.Portable).

After you created a HelloWorld project, we will see three projects in the solution, please see Figure 2.

Figure 2. A new project for Mobile App.

We need to add MapSuiteProtableCore.dll and MapSuiteFormsEdition.dll to the “HelloWorld” project which we will work mainly. Right-click the Reference in Solution Explorer and select “Add Reference”, we can find “MapSuitePortableCore.dll” in two products(iOS or Android) at C:\Program Files (x86)\ThinkGeo\Map Suite 9.0\Map Suite Android[Map Suite iOS]\Current Version\Managed Assemblies. then navigate to the C:\Program Files (x86)\ThinkGeo\Map Suite 9.0\Map Suite Xamarin Forms\Current Version\Managed Assemblies folder and select “MapSuiteFormsEdition.dll”.

Figure 3. Add Reference to HelloWorld.

For android platform, we need to add AndroidEdition.dll, MapSuiteFormsEdition.dll and MapSuiteFormsEdition.Android.dll to “HelloWorld.Droid” project. Right-click the Reference in Solution Explorer and select “Add Reference”, navigate to the C:\Program Files (x86)\ThinkGeo\Map Suite 9.0\Map Suite Xamarin Forms\Current Version\Managed Assemblies folder and select “MapSuiteFormsEdition.Android.dll” and “MapSuiteFormsEdition.dll”, navigate to the C:\Program Files (x86)\ThinkGeo\Map Suite 9.0\Map Suite Android\Current Version\Managed Assemblies folder and select “AndroidEdition.dll”.

Figure 4. Add Reference to HelloWorld.Droid.

The next step is to Initialize MapSuiteForms, MainActivity.cs:

public class MainActivity : global::Xamarin.Forms.Platform.Android.FormsApplicationActivity
{
    protected override void OnCreate(Bundle bundle)
    {
        base.OnCreate(bundle);
 
        Forms.Init(this, bundle);
        MapSuiteForms.Init();
 
        LoadApplication(new App());
    }
}

For iOS platform, we need to add iOSEdition.dll, MapSuiteFormsEdition.dll and MapSuiteFormsEdition.iOS.dll to “HelloWorld.iOS” project. Right-click the Reference in Solution Explorer and select “Add Reference”, navigate to the C:\Program Files (x86)\ThinkGeo\Map Suite 9.0\Map Suite Xamarin Forms\Current Version\Managed Assemblies folder and select “MapSuiteFormsEdition.dll” and “MapSuiteFormsEdition.iOS.dll”, navigate to the C:\Program Files (x86)\ThinkGeo\Map Suite 9.0\Map Suite iOS\Current Version\Managed Assemblies folder and select “iOSEdition.dll”.

Figure 5. Add Reference to HelloWorld.iOS.

The next step is to Initialize MapSuiteForms, AppDeleagte.cs:

[Register("AppDelegate")]
public partial class AppDelegate : global::Xamarin.Forms.Platform.iOS.FormsApplicationDelegate
{
    public override bool FinishedLaunching(UIApplication app, NSDictionary options)
    {
        Forms.Init();
        MapSuiteForms.Init();
 
        LoadApplication(new App());
        return base.FinishedLaunching(app, options);
    }
}

The next step is to create Map view in the constructor of App, and define it as “mapView”.

public App()
{
    MapView mapView = new MapView();
 
    MainPage = new ContentPage
    {
        Content = new StackLayout
        {
            Children = { mapView }
        }
    };
}

After completing this section, we'll be able to draw a map with the MapView using our own data. First, let's have a look at the data and the important objects we'll use.

The first step in creating our “Hello World” sample application is to set references to the ThinkGeo.MapSuite.Core and ThinkGeo.MapSuite.FormsEdition workspaces at the very top of our code, since we'll use many classes within them. Set the reference like this:

using ThinkGeo.MapSuite.Core;
using ThinkGeo.MapSuite.FormsEdition;

Now, let's add a base overlay to display the world map witch called “WorldMapKitOverlay”.

public App()
{
    MapView mapView = new MapView();
 
    // Set the Map Unit to DecimalDegrees, the Shapefile’s unit of measure. 
    mapView.MapUnit = GeographyUnit.DecimalDegree;
 
    // Create a WorldMapKitOverlay.
    WorldMapKitOverlay worldMapKitOverlay = new WorldMapKitOverlay();
 
    // Add a WorldMapKitOverlay.
    mapView.Overlays.Add("WorldMapKit", worldMapKitOverlay);
 
    // Set a proper extent for the map. The extent is the geographical area you want it to display.
    mapView.CurrentExtent = new RectangleShape(5, 78, 30, 26);
 
    MainPage = new ContentPage
    {
        Content = new StackLayout()
        {
            Children = { mapView }
        }
    };
}

If we compile and run what we have now, our map should look like the one below (see Figure 6).

Figure 6. A simple map of Europe (Android left, iOS right).

Map Suite iOS Edition 9.0 supports multiple kinds of data sources. Here we will provide an introduction to Shapefiles, which we will use in this Quick Start Guide.

Maps are generally made up of shapes like lines (representing roads), dots (for points of interest, such as cities and towns at small scales), and polygons (delineating parks, etc.). Shapefiles store the coordinates that are used to draw or render these shapes. Shapefiles have a .shp extension. Shapefiles also come with two supplementary files that help Map Suite work with the data.

The first supplementary file is the .shx file. This file provides a simple index of the main Shapefile; it tells the Map Suite component when to start reading binary data and when to stop. It is much like a directory for reading the binary data, or a lookup mechanism.

The second supplementary file is the .dbf file. This file holds tabular data associated with the features in the main Shapefile. For example, a Shapefile might have the coordinates for drawing a road, while the .dbf file may tell you the name, length, and type of the road (county road, state road, interstate highway, etc.).

All three files need to reside in the same directory, but the Map Suite component only expects you to designate the name and file path of the main Shapefile. Next, when we discuss layers, you’ll start understanding a bit more about how maps are constructed in Map Suite using the shape data.

A ShapeFileFeatureLayer in a map correlates to a single Shapefile, such as a network of roads. Your feature layer will be superimposed on top of the base map. In fact, you can incorporate multiple feature layers in your web mapping application. Overlapping layers of different types features on a map, such as agricultural areas, rivers, and roads, is a powerful way to visualize and work with data.

You can think of layers much like actual terrain in the real world. The landscape could be considered a “base map”, with “layers” of roads and rivers superimposed on it. Keep in mind that overlapping layers may obscure the layers below. Be sure to add them in a logical order so they can be visualized correctly. For example, make sure your roads are displayed on top of rivers, creeks and streams, so bridges will be visible on the map. While the order of overlapping layers won't be editable at the client end, the display of individual layers may be turned on or off by the end user.

How do we create and add layers? The general rule is to start big. Add polygon layers representing large areas, such as country or regional boundaries, as a first, “bottom” layer. Next, you may want to add layers with lines representing rivers and roads. Add the smallest and most specific features last, as the top layer. These may include points for cities or places of interest. Again, keep in mind that logic will dictate what works best.

A Map object is the highest level object that encompasses layers and some other objects. For now, you can think of a Map as an interface providing access to a set of layers. It can render each layer and present you with a map based on actions performed, such as zooming in and out, or panning to another area.

While Shapefiles provide the coordinates for shapes, styles define their appearance. You can specify the color of a country, the width of a road, the shape (triangle, circle, cross etc.) of a point, and so on.

Map Suite has many preset styles built in, including styles for roads, rivers, cities, countries, and other features. This makes it easy to create great looking maps without a lot of hassle.

Styles define the way we visually represent the data, while ZoomLevels define the situation in which we want to display them. ZoomLevels allow for different levels of detail at different scales. For example, we can display small towns when zoomed in close, and omit them when zoomed out to the country level, to avoid cluttering the map.

Map Suite offers the 20 most common scales, from ZoomLevel01 to ZoomLevel20, at which you may want to change your display. What is scale? Scale is a ratio between the distance represented on the map and the corresponding distance on the ground, when measured in the same units. If a road is 10,000 inches long in the real world and a map depicts this length as 1 inch on the screen, then we say the scale of this map is 1:10,000. Now let's say ZoomLevel02 uses a scale of 1:500 and ZoomLevel03 uses a scale of 1:1200. In this situation a map with a scale of 1:1000 will match ZoomLevel03 - the ZoomLevel with the closest scale.

PresetZoomLevels has a very useful property called ZoomLevel.ApplyUntilZoomLevel, which you can easily use to extend your ZoomLevels. Let's say you want a particular style to be visible at ZoomLevel03 through ZoomLevel10. To make that work, simply code as follows:

capitalLayer.ZoomLevelSet.ZoomLevel01.DefaultPointStyle = PointStyles.CreateSimpleCircleStyle(GeoColor.StandardColors.White, 7, GeoColor.StandardColors.Brown);
capitalLayer.ZoomLevelSet.ZoomLevel01.ApplyUntilZoomLevel = ApplyUntilZoomLevel.Level05;

Now let's look at a code sample to bring this concept to fruition. We'll look at Shapefiles relating to the entire world. In our example, we have one such Shapefile:

• worldwide country borders (Countries02.shp)

Android The data used here can be found in the attached sample above in the “\AppData” folder. And we has copy data to sdcard. Please check data, and make sure we can find it in sdcard (“/mnt/sdcard/Android.Sample/”).

iOS The data used here can be found in the attached sample above in the “\AppData” folder. The data files' build action should be “Content”.

Our next step is to define and add our Layers. Here is the code to use for our example. All of the following code can be placed in the the constructor of App.

public App()
{
    MapView mapView = new MapView();
 
    // Set the Map Unit to DecimalDegrees, the Shapefile’s unit of measure. 
    mapView.MapUnit = GeographyUnit.DecimalDegree;
 
    // Get the base data location on different platform.
    string baseDataPath = Device.OnPlatform<string>("", "/mnt/sdcard/Android.Sample/", "");
 
    // Set the Map Unit to DecimalDegrees, the Shapefile’s unit of measure.
    mapView.MapUnit = GeographyUnit.DecimalDegree;
 
    WorldMapKitOverlay worldMapKitOverlay = new WorldMapKitOverlay();
    mapView.Overlays.Add("WorldMapKit", worldMapKitOverlay);
 
    // Create a new Layer and pass the path to a Shapefile into its constructor. 
    ShapeFileFeatureLayer worldLayer = new ShapeFileFeatureLayer(baseDataPath + @"AppData/Countries02.shp");
 
    <nowiki>//</nowiki> Set the worldLayer with a preset Style, as AreaStyles.Country1 has YellowGreen background and black border, our worldLayer will have the same render style.  
    worldLayer.ZoomLevelSet.ZoomLevel01.DefaultAreaStyle = AreaStyles.Country1;
 
    // This setting will apply from ZoomLevel01 to ZoomLevel20, which means the map will be rendered in the same style, no matter how far we zoom in or out. 
    worldLayer.ZoomLevelSet.ZoomLevel01.ApplyUntilZoomLevel = ApplyUntilZoomLevel.Level20;
 
    // Create a new Layer Overlay to hold the layer we just created
    LayerOverlay layerOverlay = new LayerOverlay();
 
    // Add the shapefile layer to the layer overlay
    layerOverlay.Layers.Add(worldLayer);
 
    // Add the layerOverlay to map.
    mapView.Overlays.Add(layerOverlay);
 
    // Set a proper extent for the map. The extent is the geographical area you want it to display.
    mapView.CurrentExtent = new RectangleShape(5, 78, 30, 26);
 
    MainPage = new ContentPage
    {
        Content = new StackLayout()
        {
            Children = { mapView }
        }
    };
}

If you compile and run, your map should look like the one below. (see Figure 7).

Figure 7. A Simple map of Europe (Android left, iOS right).

So what has occurred here? We've created a layer and added it to the Map, and the Map has rendered it according to its default style parameters. We've also used ZoomLevel to display the map the way we want.

NOTE: It is important that the MapUnit property of a Map object be set using the GeographyUnit Enumeration. This is because the coordinates stored in a Shapefile can be in decimal degrees (a format of latitude and longitude), feet, meters, or another unit system, and our map has no way to know what the Shapefile's unit of measurement is until we tell it. This information is normally found somewhere in the Shapefile's documentation (also referred to as its metadata), or within its supplemental data file, as discussed in the section on Shapefiles. It may also come as a separate .txt, .xml, or .html file that begins with the same file name as the main Shapefile.

Now you can display and navigate your map. Pan by dragging the map, zoom in by double-clicking, zoom in and out with the gesture. Very powerful for just couple lines of code, isn't it?

That was an easy start! Now let's add a second Shapefile to the sample, so we'll have a total of two layers:

1. World country borders (“Countries02.shp”)
2. World capitals (“WorldCapitals.shp”)

public App()
{
    MapView mapView = new MapView();
    mapView.MapUnit = GeographyUnit.DecimalDegree;
 
    string baseDataPath = Device.OnPlatform<string>("", "/mnt/sdcard/Android.Sample/", "");
 
    WorldMapKitOverlay worldMapKitOverlay = new WorldMapKitOverlay();
    mapView.Overlays.Add("WorldMapKit", worldMapKitOverlay);
 
    ShapeFileFeatureLayer worldLayer = new ShapeFileFeatureLayer(baseDataPath + @"AppData/Countries02.shp");
    worldLayer.ZoomLevelSet.ZoomLevel01.DefaultAreaStyle = AreaStyles.Country1;
    worldLayer.ZoomLevelSet.ZoomLevel01.ApplyUntilZoomLevel = ApplyUntilZoomLevel.Level20;
 
    ShapeFileFeatureLayer capitalLayer = new ShapeFileFeatureLayer(baseDataPath + @"AppData/WorldCapitals.shp");
    // Similarly, we use the presetPointStyle for cities.     
    capitalLayer.ZoomLevelSet.ZoomLevel01.DefaultPointStyle = PointStyles.Capital3;
    // This setting also applies from ZoomLevel01 to ZoomLevel20, so city symbols will be rendered in the same style, no matter how far we zoom in or out. 
    capitalLayer.ZoomLevelSet.ZoomLevel01.ApplyUntilZoomLevel = ApplyUntilZoomLevel.Level20;
 
    LayerOverlay layerOverlay = new LayerOverlay();
    layerOverlay.Layers.Add(worldLayer);
    // We need to add both of the new layers to the Layer OverLay. 
    layerOverlay.Layers.Add(capitalLayer);
 
    mapView.Overlays.Add(layerOverlay);
    mapView.CurrentExtent = new RectangleShape(5, 78, 30, 26);
 
    MainPage = new ContentPage
    {
        Content = new StackLayout()
        {
            Children = { mapView }
        }
    };
}

If you compile and run, your map should look like the one below. (see Figure 8).

Figure 8. A map of Europe with the additional borders and capitals layers displayed (Android left, iOS right).

TextStyle is used to label items on map. While the features themselves are drawn from information in the Shapefile, they're labeled with feature names or other attributes contained in the .dbf file. For example, the Shapefile containing capitals of the world has a corresponding .dbf file with the field “CITY_NAME”. We can use this field to label the cities on our map.

Map Suite includes several built-in TextStyles to help us quickly apply attractive city labels. We can simply pick the TextStyle we like and use it.

public App()
{
    MapView mapView = new MapView();
    mapView.MapUnit = GeographyUnit.DecimalDegree;
 
    string baseDataPath = Device.OnPlatform<string>("", "/mnt/sdcard/Android.Sample/", "");
 
    WorldMapKitOverlay worldMapKitOverlay = new WorldMapKitOverlay();
    mapView.Overlays.Add("WorldMapKit", worldMapKitOverlay);
 
    ShapeFileFeatureLayer worldLayer = new ShapeFileFeatureLayer(baseDataPath + @"AppData/Countries02.shp");
    worldLayer.ZoomLevelSet.ZoomLevel01.DefaultAreaStyle = AreaStyles.Country1;
    worldLayer.ZoomLevelSet.ZoomLevel01.ApplyUntilZoomLevel = ApplyUntilZoomLevel.Level20;
 
    ShapeFileFeatureLayer capitalLayer = new ShapeFileFeatureLayer(baseDataPath + @"AppData/WorldCapitals.shp");
    // Similarly, we use the presetPointStyle for cities. 
    capitalLayer.ZoomLevelSet.ZoomLevel01.DefaultPointStyle = PointStyles.Capital3;
    // This setting also applies from ZoomLevel01 to ZoomLevel20, which means city symbols will be rendered in the same style no matter how far we    
    //zoom in or out.
    capitalLayer.ZoomLevelSet.ZoomLevel01.ApplyUntilZoomLevel = ApplyUntilZoomLevel.Level20;
 
    // We create a new Layer for labeling the capitals.
    ShapeFileFeatureLayer capitalLabelLayer = new ShapeFileFeatureLayer(baseDataPath + @"AppData/WorldCapitals.shp");
    // We use the preset TextStyle. Here we pass in "CITY_NAME", the name of the field containing the values we want to label the map with.
    capitalLabelLayer.ZoomLevelSet.ZoomLevel01.DefaultTextStyle = TextStyles.Capital3("CITY_NAME");
    capitalLabelLayer.ZoomLevelSet.ZoomLevel01.ApplyUntilZoomLevel = ApplyUntilZoomLevel.Level20;
    // Since the map is drawn with tiles, the label needs to draw on the margin to make sure the text is complete after joining the tiles together.
    // Change the number below (to 0, for example) to better understand how this works.
    capitalLabelLayer.DrawingMarginPercentage = 50;
 
    LayerOverlay layerOverlay = new LayerOverlay();
    layerOverlay.Layers.Add(worldLayer);
    layerOverlay.Layers.Add(capitalLayer);
    layerOverlay.Layers.Add(capitalLabelLayer);
 
    mapView.Overlays.Add(layerOverlay);
    mapView.CurrentExtent = new RectangleShape(5, 78, 30, 26);
 
    MainPage = new ContentPage
    {
        Content = new StackLayout()
        {
            Children = { mapView }
        }
    };
}

If you compile and run, your map should look like the one below. (see Figure 9).

Figure 9. Europe map with TextStyle applied (Android left, iOS right).

Now that we know how to render text and symbols, let's create custom Styles and TextStyles. We'll also specify different ranges of ZoomLevels, and apply varying custom Styles and TextStyles to the same layer at different ZoomLevel ranges.

public App()
{
    MapView mapView = new MapView();
    mapView.MapUnit = GeographyUnit.DecimalDegree;
 
    string baseDataPath = Device.OnPlatform<string>("", "/mnt/sdcard/Android.Sample/", "");
 
    WorldMapKitOverlay worldMapKitOverlay = new WorldMapKitOverlay();
    mapView.Overlays.Add("WorldMapKit", worldMapKitOverlay);
 
    ShapeFileFeatureLayer worldLayer = new ShapeFileFeatureLayer(baseDataPath + @"AppData/Countries02.shp");
    worldLayer.ZoomLevelSet.ZoomLevel01.DefaultAreaStyle = AreaStyles.Country1;
    worldLayer.ZoomLevelSet.ZoomLevel01.ApplyUntilZoomLevel = ApplyUntilZoomLevel.Level20;
 
    ShapeFileFeatureLayer capitalLayer = new ShapeFileFeatureLayer(baseDataPath + @"AppData/WorldCapitals.shp");
    // We can customize our own Style. Here we pass in a color and a size.
    capitalLayer.ZoomLevelSet.ZoomLevel01.DefaultPointStyle = PointStyles.CreateSimpleCircleStyle(GeoColor.StandardColors.White, 7, GeoColor.StandardColors.Brown);
    // The Style we set here is available from ZoomLevel01 to ZoomLevel05. That means if we zoom in a bit more, it will no longer be visible.
    capitalLayer.ZoomLevelSet.ZoomLevel01.ApplyUntilZoomLevel = ApplyUntilZoomLevel.Level05;
 
    capitalLayer.ZoomLevelSet.ZoomLevel06.DefaultPointStyle = PointStyles.Capital3;
    // The Style we set here is available from ZoomLevel06 to ZoomLevel20. That means if we zoom out a bit more, it will no longer be visible.
    capitalLayer.ZoomLevelSet.ZoomLevel06.ApplyUntilZoomLevel = ApplyUntilZoomLevel.Level20;
 
    ShapeFileFeatureLayer capitalLabelLayer = new ShapeFileFeatureLayer(baseDataPath + @"AppData/WorldCapitals.shp");
    // We can customize our own TextStyle. Here we pass in the font, size, style and color.
    capitalLabelLayer.ZoomLevelSet.ZoomLevel01.DefaultTextStyle = TextStyles.CreateSimpleTextStyle("CITY_NAME", "Arial", 8, DrawingFontStyles.Italic, GeoColor.StandardColors.Black, 3, 3);
    // The TextStyle we set here is available from ZoomLevel01 to ZoomLevel05. 
    capitalLabelLayer.ZoomLevelSet.ZoomLevel01.ApplyUntilZoomLevel = ApplyUntilZoomLevel.Level05;
 
    capitalLabelLayer.ZoomLevelSet.ZoomLevel06.DefaultTextStyle = TextStyles.Capital3("CITY_NAME");
    // The TextStyle we set here is available from ZoomLevel06 to ZoomLevel20. 
    capitalLabelLayer.ZoomLevelSet.ZoomLevel06.ApplyUntilZoomLevel = ApplyUntilZoomLevel.Level20;
    capitalLabelLayer.DrawingMarginPercentage = 50;
 
    LayerOverlay layerOverlay = new LayerOverlay();
    layerOverlay.Layers.Add(worldLayer);
    layerOverlay.Layers.Add(capitalLayer);
    layerOverlay.Layers.Add(capitalLabelLayer);
 
    mapView.Overlays.Add(layerOverlay);
    mapView.CurrentExtent = new RectangleShape(5, 78, 30, 26);
 
    MainPage = new ContentPage
    {
        Content = new StackLayout()
        {
            Children = { mapView }
        }
    };
}

Can you imagine what the map will look like now? Below is the result. If you compile and run, at first it looks like Figure 14, then like Figure 15 as you zoom in further.

Figure 10. Map of Europe before zooming in (Android left, iOS right).

Figure 11. Map of Europe after zooming in (Android left, iOS right).

You now know the basics of using the Map Suite Map control and can start adding this functionality to your own applications. Let's recap what we've learned about the object relationships and how the pieces of Map Suite work together:

1. It is of the utmost importance that the units (feet, meters, decimal degrees, etc.) be set properly for the Map control, based on the requirements of your data.
2. Shapefiles provide the data used by a Map control to render a map.
3. A Map is the basic control that contains all the other objects used to indicate how the map should be rendered.
4. A Map has one-to-many Layers. A Layer correlates one-to-one with a Shapefile (.shp).
5. A Layer can have one-to-many ZoomLevels. ZoomLevels help to define ranges (upper and lower scales) of when a Layer should be shown or hidden.

Download Sample Code From This Exercise (1.5 MB)