Getting Started with the .NET MAUI Map Control

See how the Telerik UI for .NET MAUI Map control lets you display maps, labels and regions to add things like world maps or seating charts to your apps.

In the world of web development, there are applications for displaying geographic information. Although there are ways to embed Google Maps or similar options, customizing them isn’t so easy when you need to highlight geographic areas or respond to user selection. Fortunately, the Progress Telerik UI library has a .NET MAUI Map control, which we will examine throughout this article. Let’s get started!

What Is the Telerik UI for .NET MAUI Map Control?

The Telerik .NET MAUI Map control is a powerful control for displaying maps in your .NET MAUI applications, with a lot of flexible styling options. It also supports multiple layers, pan and zoom, and many other features.

The control works with ESRI shapefiles, which are a standard vector format in geographic information systems or GIS. According to the MAUI Map documentation, these files consist of geometric objects such as lines, polylines and polygons. This makes it possible to display different types of objects like floor plans and seat distribution, up to parts of country maps, roads, rivers, etc.

It’s important to note that an ESRI shapefile is composed of two files:

• A .shp file, which contains the polygons that draw something on the map, such as a country, a region or a custom shape
• A .dbf file, which contains the attributes associated with each geometry, such as the country’s name or its population

The control uses SkiaSharp to render the shapefile geometries, allowing fast and consistent rendering across platforms.

Finally, you should know that the .NET MAUI Map control is based on the use of layers, where each layer represents a data source that overlays the map. Let’s see how to integrate this control into a .NET MAUI app.

Integrating the Telerik .NET MAUI Map Control into .NET MAUI Apps

To see the control’s features in action, we’ll create a new project selecting the .NET MAUI App template, making sure not to include the sample code. Once the project is created, you can follow the installation guide for Telerik controls in .NET MAUI projects, which will allow you to use Telerik controls in your project.

Next, we will install the following NuGet package in the project:

This package will help reduce repetitive code in view models. With this, we are ready to integrate a map into our application.

Downloading the Map Data

As I mentioned earlier, the map control needs a shapefile to be able to draw the map. To simplify this guide, we will download the files world.shp and world.dbf that Progress Telerik has made available to us in the examples repository.

To be able to use the downloaded files, let’s create a new folder in Resources/Maps, where we will add the files .shp and .dbf. In addition, we must mark the files as embedded resources, which we will achieve by modifying your project file .csproj as follows:

With the above, we will be able to use future additional map files without configuring each file as embedded. Also, we mark them as EmbeddedResource so that they are packaged inside the app assembly, which will allow us to read them later.

Creating a Demo View Model

With the map files added, the next step will be to create a view model that allows storing information about a country selected by the user. For this, we will define a file MainViewModel.cs with the following code:

The above code defines properties to determine if there is a selection, a selected country and a selected population. The property HasNoSelection will allow showing a message when no country has been selected yet.

Displaying the Map in a ContentPage

The time has come to display the map in the application. To do this, we will open the ContentPage file where we want to show the map, and replace its content with the following:

In the above code, you can see that we use properties of the map control, such as MinZoomLevel and MaxZoomLevel to limit the zoom range, in addition to InteractionMode to enable panning and zoom with gestures.

Additionally, we use the RadMap.Layers tag to add a MapShapefileLayer type, which will read the shapefile. We also use a MapShapeReader type named reader, which will be responsible for loading the files .shp and .dbf.

Now, we must load the files from the code behind of the page where we defined the map, as follows:

In the above code, there are a few elements worth analyzing:

• We access the map information through a special class called MapSource, with which we load the map resources. Make sure to modify the namespace according to your project’s name.
• We subscribe to the ReadCompleted event before any map reading, so that the handler runs when the reading of the files finishes.
• We use the properties DataSource and Source to load both the map and the geometries.
• In the OnReadCompleted handler, we unsubscribe from the read event so that it only executes once, and also use the methods SetView and GetBestView to calculate the region with the best fit for all the geometries.

Before running the application, we must go back to the MauiProgram.cs file and add to the dependency container the references for the content page and its view model

Now, when running the application, we will be able to see the map control rendered correctly:

Adding Labels to the Map

We have successfully added the map to our app. However, it doesn’t display any information, which is not very useful.

The file .dbf contains information we can use to add additional data to the map, such as country names. To do this, we’ll use an attribute called CNTRY_NAME, modifying the layer MapShapefileLayer to include the layer LabelAttributeName:

In the code above, the property LabelAttributeName allows adding a label for each shape in a MapShapefileLayer. When running the app, we can see the names on the map as shown below:

In the demo above, you can see how when zooming the country labels gradually appear, allowing for a pleasant user experience.

Customizing the Map

So far, we have used the map’s default style; however, in real apps you’ll likely want to add colors for sections of your map. This is possible thanks to the use of MapShapeStyleSelector, which is a style selector that we can use to decide what colors to use for each region on the map.

In our example, we’ll compare the population of each country to determine its color. To do this, we’ll create a new class calledPopulationShapeStyleSelector, which will be defined as follows:

The operation is similar to a common .NET MAUI Style Selector, that is, we define style references as part of the class, in this case HighPopulationStyle, MediumPopulationStyle and LowPopulationStyle.

Next, the attribute POP_CNTRY is obtained from each mapShape, which is evaluated to determine the style that will be applied.

With the selector defined, we still need to create the styles to be applied. We can do this from the ContentPage where we’ve implemented the map control, as follows:

You can see that we create an instance of PopulationShapeStyleSelector, within which we assign to each property of the selector a MapShapeStyle, which will allow customizing each defined selector.

The last step is to indicate that we want to use the selector we just created in MapShapefileLayer:

The result of running it is as follows:

In the image above, you can see how the countries appear colored according to their population. Now, let’s see how to select regions on a map.

Enabling Country Selection

To make the map fully functional, we will allow users to select a country to view its information in detail. We’ll do this by adding the use of the property SelectionMode in the MapShapefileLayer:

In the code above we have indicated that only one country can be selected at a time, although you could also use the value Multiple if you need the user to select more than one country. Likewise, we have defined a MapShapeStyle section, which is used to specify the characteristics of the selected region.

We will also complete the ContentPage of our app, adding a Telerik container RadBorder in the second row of the main grid, which will serve to display the selected country’s information using standard controls and Telerik buttons:

You also need to complete the code behind of the ContentPage to react to selection changes, as well as handle button actions:

In the code above we subscribed to the CollectionChanged event, which will be fired when a user selects or deselects a country. In the event handler OnSelectedShapesChanged we validate whether there are selected shapes; if not, the graphical elements that display information about each country are cleared.

If a country has been selected, the attributes CNTRY_NAME and POP_CNTRY are read and the values in the view model are updated.

Finally, we also create the event handlers OnResetViewClicked for a button that allows recentering the entire map using the method GetBestView() again. We have also defined the method OnClearSelectionClicked, which will be used to clear the SelectedShapes collection, to deselect any selected country and reset the data in the UI:

In the image above we can see how, when selecting a country on the map, its information is correctly displayed at the bottom.

Conclusion

In this article you got to know the Telerik UI Map control for .NET MAUI, which is an excellent option for displaying maps, labels and regions reliably and quickly. We saw step by step how to read ESRI shapefiles as well as render them.

We also learned how to color different regions using a style selector and how to allow users to select specific regions on the map.

Now it’s your turn to create unique experiences using this powerful control. The whole Telerik UI for .NET MAUI suite comes with a free 30-day trial so you can explore it yourself.

Try Now