How to Support Loading Extensions in DotSpatial

Introduction

DotSpatial is an open-source project that contains controls which can be used to manipulate and display geographic information. As DotSpatial is intended to be extensible, many developers find they want to deploy DotSpatial with extensions such as Tools or the GDAL data providers. This article provides a quick overview and functional code that demonstrates the technique for loading extensions.

Downloading DotSpatial and Creating a Project

This article is based on the DotSpatial 1.0 Release located on the downloads tab at http://dotspatial.codeplex.com

If you are not familiar with creating a simple DotSpatial-based application, please consider the introductory article. For practical purposes, we assume you are coming to this article after having completed the previous one.

Adding an AppManager

The AppManager is responsible for discovering and loading extensions. We will add one to our project.

While we could instantiate an AppManager in code, in this example, we will consider a Windows Forms Application based project which has a form named Form1. View the form designer. Drag an AppManager onto the form and drop it onto a blank spot. An instance named appManager1 will appear in the component tray.

As the AppManager is a component, it doesn’t have a visual representation at run-time, but will appear in the component tray at design-time. We can select it and use the Properties Window to select the controls or components that will be available to extensions during program execution.

Using the AppManager component requires us to add a reference (Project, Add Reference…) to the System.ComponentModel.Composition assembly. Select this assembly the .NET tab or Assemblies, Framework tab (depending on your version of Visual Studio) of the Add Reference Dialog.

Set the Map name property to uxMap.

Loading Extensions

The AppManager does not actually load extensions until it is instructed to do so. This allows us to display a splash screen or defer loading extensions until we would like them to become available. Keep in mind that extensions may remain in memory once they are loaded until the application closes.

Switch to code view for Form1. Add the following code in the form constructor just before the closing brace:

appManager1.LoadExtensions();

With your additions, the form constructor might now look something like this:

public Form1()
{
    InitializeComponent();
    appManager1.LoadExtensions();
}

At this point we can load some extensions by simply placing them in the “Plugins” folder. The AppManager has a Directories property, and we could alternately use it to point the AppManger to another set of folders. These directories will be traversed recursively in search of DotSpatial Extensions.

Note: It is very important to “unblock” dlls as described in the introductory article as the .NET framework may not load blocked dlls.

Loading GdalExtension32

GDAL is widely used for loading raster files. DotSpatial only supports a limited number of file formats by default (as illustrated), so we will load the GdalExtension32 extension.

Because GDAL is written in native code we would need to deploy an x86 version with our application for x86 (32-bit) machines and an x64 version for x64 (64-bit) machines. To simplify deployment we will setup our application to run in WoW64 on 64-bit machines and we will use the 32-bit version of the GDAL extension.

Go to Project Properties and select the Build Tab. Set the Platform target to x86.

Locate the output directory where your project is compiled. You could do this by clicking the Browse button by the Output path. In my case, this directory is C:\dev\DotSpatial\DotSpatial.Examples.LoadingExtensions\bin\Debug

Copy the Data Extensions/GDAL folder from the location where you downloaded DotSpatial to a new folder named “Plugins” inside of the output directory. In my case, C:\dev\DotSpatial\DotSpatial.Examples.LoadingExtensions\bin\Debug\Plugins

Run the application. Notice the support for additional file types when using the Open File Dialog or dragging and dropping files.

Points of Interest

In order to support extensions that interact with the user interface directly, you will need to provide a dock manager, status control and header control.

It is important to remove any extensions that would require those, unless you have them.

Getting Started with DotSpatial Desktop Mapping RC2

Introduction

DotSpatial is an open-source project that contains controls which can be used to manipulate and display geographic information. This article provides a quick overview and functional code that will help you get started with DotSpatial. Some of the basic operations that can be performed include: loading a shape file, panning and zooming.

Downloading DotSpatial

This article is based on the DotSpatial Release Candidate 2 (1.0.845) located on the downloads tab at http://dotspatial.codeplex.com

Note: Be aware that your browser may add an identifier to downloaded files which results in “blocked” dll files. You can click the following link to learn how to “Unblock” files. Right click on the zip file before unzipping, choose properties, go to the general tab and click the unblock button.

Once you have extracted the downloaded archive, you may run DemoMap.exe to get a sense of the capabilities in DotSpatial.

Creating a project

Start Visual Studio 2010 and create a new project. By using the Windows Forms Application template, a form is added to our project. Later, we will place visual elements on this form.

Changing Target Framework

DotSpatial requires that our project target the .NET Framework 4 instead of the default .NET Framework 4 Client Profile. Right-click your project (or click Project, Properties …) and select the Application Tab where you can switch to the .NET Framework 4 target framework.

If using VB.Net, you will need to go to the Compile tab and click Advanced Compile Options… where you can switch the target framework.

Adding Toolbox items

The toolbox provides a way to drag and drop controls onto the design surface of a form. Generally, when a control is dropped onto a form, Visual Studio will generate code necessary to instantiate the control, and add any required references to the project. You could instantiate the control without using the designer, by writing the appropriate code and making any necessary references.

Make sure the Solution Explorer is visible (View, Solution Explorer). Double-click Form1 to view it in Design view. Make the Toolbox visible (View, Toolbox). Optionally, create a new tab to contain the DotSpatial controls by right-clicking in the toolbox and clicking Add Tab in the context menu.

Right click in the tab you just created or in the General tab and click Choose Items…

Click Browse… and navigate to the location where you downloaded the DotSpatial files. Select DotSpatial.Controls and click Open, then OK.

You should see a number of DotSpatial control fill the Toolbox.

Laying out the user interface

Drop four Button controls onto the design surface of Form1. You can find the button in the Common Controls tab of the Toolbox. Also, drop a Map control onto the form. You will probably want to resize the form so that there is more space for placing the controls.

Adding DotSpatial references

You will notice that Visual Studio adds a reference to DotSpatial.Controls when you drop the Map control onto Form1. If we try to build the project at this point, however, we are notified that we need to add additional references to the project.

Add references to key DotSpatial libraries by clicking Project, Add Reference.…Browse to the location where you downloaded the files. Select DotSpatial.Data and DotSpatial.Symbology. You can select multiple files by holding the CTRL key while individually clicking on them.

Setting control properties

We return to the form designer to set properties of the various controls we have added. Again, this could be done in code, but properties may be easier to discover in the Properties Window. Select button1 and look at the Properties Window (View, Properties Window). Notice the Text property is “button1.” Change it to “Open File.” It is wise to change the name of the button as well to represent its function. Find (Name) and change it to “uxOpenFile.” Prefixing the button name with ux is simply a convention. You won’t be able to include spaces in a control name.

Similarly, update buttons 2-4 to represent Zoom In, Zoom Wide, and Pan. Remember to rename them. Rename the map from “map1” to “uxMap.”

If you were to run the project at this point, you would find you could drop a file onto the map control, but we haven’t yet wired up the buttons and they won’t do anything if you depress them. The designer in Visual Studio has a shortcut that will create a button event handler and take us to it so we can add our own code. Double click the Open File button. You are taken to the appropriate event handler. Type the following:

uxMap.AddLayer();

The AddLayer method will show the user a dialog so that they can select a relevant file to display on the map control.

Return to the form designer by double clicking on Form1 and create an event handler for Zoom In. Type the following code into the event handler.

uxMap.ZoomIn();

Now, when a user clicks the Zoom In button, the map view will lurch forward. You’ll similarly add the following code to deal with the situation when the user clicks the Zoom Wide button.

uxMap.ZoomToMaxExtent();

For the final button, instead of going back to the designer, just paste this code below the event handler for Zoom Wide. You need to make sure you paste it just after the event handler and above the two trailing braces }.

private void uxPan_Click(object sender, EventArgs e)
{      uxMap.FunctionMode = DotSpatial.Controls.FunctionMode.Pan;
}

Now we need to attach this method to the uxPan Button. Double Click Form1 to return to the form designer and select the uxPan Button. In the Properties Window, click the lightning bolt icon to view Events. Type uxPan_Click into the Click Action.

When a user clicks the pan button, the cursor will change to a Pan (hand) symbol. In this mode, the map can be dragged from right to left, etc. While our previous event handlers execute methods, this event handler changes the FunctionMode of the map. The map will remain in pan mode until the user closes the application. Alternately, you could add buttons that would toggle the map into other modes.

Build and run your project and open a data file (see resource section for samples).

Points of Interest

You should be able to easily expand this project to include buttons which toggle between the Info, Measure, and Select tools.

History

11-11-2011 Initial Posting.

Resources

dotspatial.codeplex.comAdditional information and documentation about DotSpatial

mapwindow6.codeplex.comMapWindow 6 – an extensible DotSpatial-based application

naturalearthdata.com Sample data files

www.diva-gis.org/gdata Sample data files

License

This article, along with any associated source code and files, is licensed under The Microsoft Public License (Ms-PL)