MapXtreme
v7.1
DEVELOPER GUIDE
Information in this document is subject to change without notice and does not represent a commitment on the part of the vendor or its representatives. No part
of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, without the written
permission of Pitney Bowes Software Inc., One Global View, Troy, New York 12180-8399.
© 2012 Pitney Bowes Software, Inc. All rights reserved.Pitney Bowes Software Inc. is a wholly-owned subsidiary of Pitney Bowes Inc. Pitney Bowes, the
Corporate logo, MapInfo, Group 1 Software, and MapXtreme are trademarks of Pitney Bowes Inc. or a subsidiary. All other trademarks are the property of
their respective owners.
United States:
Phone: 518.285.6000
Fax: 518.285.6070
Sales: 800.327.8627
Government Sales: 800.619.2333
Technical Support: 518.285.7283
Technical Support Fax: 518.285.6080
www.pb.com/software
Canada:
Phone: 416.594.5200
Fax: 416.594.5201
Sales: 800.268.3282
Technical Support:.518.285.7283
Technical Support Fax: 518.285.6080
pbinsight.ca
Europe/United Kingdom:
Phone: +44.1753.848.200
Fax: +44.1753.621.140
Technical Support: +44.1753.848.229
www.pb.co.uk/software
Asia Pacific/Australia:
Phone: +61.2.9437.6255
Fax: +61.2.9439.1773
Technical Support: 1.800.648.899
www.pbi.com.au/software
Contact information for all Pitney Bowes Software Inc. offices is located at:: www.pb.com/contact-us/
This product contains SpatiaLite v 3.1.0, which is licensed under GNU Lesser General Public License, Version 2.1, February 1999. The license can be
downloaded from: http://www.gnu.org/licenses/lgpl-2.1.html. The source code for this software is available from http://www.gaia-gis.it/gaia-sins/win-bin-
x86-test/spatialite-3.1.0b-test-win-x86.zip and http://www.gaia-gis.it/gaia-sins/win-bin-amd64-test/spatialite-3.1.0b-test-win-amd64.zip.
This product contains Feature Data Objects v 3.6.0, which is licensed under GNU Lesser General Public License, Version 2.1, February 1999. The license can
be downloaded from: http://fdo.osgeo.org/lgpl.html. The source code for this software is available from http://fdo.osgeo.org/content/fdo-360-downloads.
This product contains HelpLibraryManagerLauncher.exe v 1.0.0.1, which is licensed under Microsoft Public License. The license can be downloaded from:
http://shfb.codeplex.com/license. The source code for this software is available from http://shfb.codeplex.com.
July 2012
Table of Contents
Chapter 1: Introduction to MapXtreme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Overview of MapXtreme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Key Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
Migrating to MapXtreme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24
Learning to Use MapXtreme. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Support Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26
Chapter 2: Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Installation Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29
Minimum System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Types of Installations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30
Development (SDK) Installations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Deployment (Runtime) Installations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Side-By-Side Installations and Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31
MapXtreme Licensing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Types of Licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31
Obtaining a License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32
Locations of License Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35
Known Issues with Licensing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Before You Install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37
Administrator Privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37
Install .NET Framework and Visual Studio First. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37
IIS 7.x and IIS 6 Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38
Default Install Directories for MapXtreme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39
Additional Installation Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Installing MapXtreme in Your Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40
Upgrading to MapXtreme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
Migrating Web Sites to 64-bit Web Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
Updating Existing Web Sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Updating Existing Desktop Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44
Creating Applications in Visual Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
MapXtreme 3 Developer Guide
Table of Contents
Map Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46
ASP.NET Web Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48
MapXtreme Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
Building ASP.NET Web Applications Without a Template . . . . . . . . . . . . . . . . . . . . . . 50
Deploying Your Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52
Deploying With the Runtime Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Deploying With Your Own Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53
Deploying a Web Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Deploying Applications that Access Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57
MapXtreme Web Applications Behind Proxy Servers . . . . . . . . . . . . . . . . . . . . . . . . . .57
Permissions to Temp Directory for Deployed Web Applications . . . . . . . . . . . . . . . . . .57
Application Data Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57
Deployment Installation Troubleshooting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58
Chapter 3: Mapping Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Mapping and MapXtreme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61
Labels and Legends. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62
Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
Workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
Coordinate Systems and Projections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
Geocoding with MapXtreme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64
Routing with MapXtreme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65
Chapter 4: Understanding the MapXtreme Architecture . . . . . . . . . . . . . . . . . . . 66
MapXtreme Architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Object Model Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .68
MapInfo.Data Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .68
MapInfo.Data.Find Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69
MapInfo.Engine Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69
MapInfo.Geometry Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69
MapInfo.Mapping Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69
MapInfo.Mapping.Legends Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69
MapInfo.Mapping.Thematics Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69
MapInfo.Persistence Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
MapInfo.Raster Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
MapInfo.Styles Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
MapInfo.WebControls Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
MapXtreme 4 Developer Guide
Table of Contents
MapInfo.Windows Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
MapInfo.Tools Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
MapInfo.Geocoding Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70
MapInfo.Routing Namespace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Application Architectures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Web Application Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Desktop Application Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74
Chapter 5: Web Applications, Controls, and Tools . . . . . . . . . . . . . . . . . . . . . . . 75
Web Application Request/Response Lifecycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76
Components of a MapXtreme Web Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76
MapXtreme Session. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Background Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
MapControl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77
Map Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .79
State Management and Pooling Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .80
MapXtreme Web Controls and Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .80
Description of Web Controls and Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81
Web Control Architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Map Tools Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84
How a Map Tool Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Using the MapXtreme Web Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .86
Managing Your Web Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87
Event Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87
Error Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87
State Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Creating a Custom Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88
Using and Distributing Custom Web Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90
Creating a Web Assembly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91
Adding an InfoTool to a Web Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
ASP.NET AJAX and MapXtreme Web Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . .92
Adding ASP.NET AJAX Controls to a MapXtreme Web Application . . . . . . . . . . . . . . .93
MapXtreme Tile Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94
Using the MapXtreme Tile Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97
HTML/XHTML Validation Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Migrating Post-back Web Controls to JavaScript Web Controls . . . . . . . . . . . . . . . . . 99
Loading Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99
Replacing Controls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100
State and Event Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Specialized Topics for Web Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Using Web Controls in Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
MapXtreme 5 Developer Guide
Table of Contents
Using the MapControl in Table Cells . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101
Web Control Localization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Chapter 6: Understanding State Management . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103
Terminology. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103
What is State Management?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
What State Management Options are Available? . . . . . . . . . . . . . . . . . . . . . . . . . . . .105
Questions to Ask Before Writing Your Application . . . . . . . . . . . . . . . . . . . . . . . . . . . .105
InProc Development Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Pros and Cons of the InProc Development Model . . . . . . . . . . . . . . . . . . . . . . . . . . . .108
InProc Management: A Walk-Through. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108
Configuring an Application to Use the InProc Development Model . . . . . . . . . . . . . . .109
Using the MapXtreme Template with the InProc Development Model. . . . . . . . . . . . .110
State Management For Pooled Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .110
What is Pooling? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .110
Pros and Cons of Pooling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111
Saving State for Pooled Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .112
Manual State Management: A Walk-Through . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113
Configuring a Pooled Application to Use Manual State Management . . . . . . . . . . . . .114
A Detailed Look at Manual State Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115
Overview of the Thematics Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Application Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116
Implementing a StateManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117
Serializing MapXtreme Objects in the Proper Order . . . . . . . . . . . . . . . . . . . . . . . . . .119
Automatically Deserializing MapXtreme Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120
Handling Initial Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120
Handling Subsequent Requests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121
A Closer Look at the MapXtreme Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121
Configuring Microsoft COM+ Object Pooling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122
Chapter 7: Desktop Applications, Controls, Dialogs, and Tools . . . . . . . . . . . 124
Planning a Desktop Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Best Practices for Desktop Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125
MapXtreme and COM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Sample Applications and Project Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .126
MapInfo.Windows.Controls Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Key Controls to Use in Desktop Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .128
MapControl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .128
MapToolStripButtons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129
The MapToolBar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130
Layer Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .133
MapXtreme 6 Developer Guide
Table of Contents
MapInfo.Windows.Dialogs Namespace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
CreateThemeWizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135
Customizing Controls and Dialog Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139
Overview of the MapInfo.Tools Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
MapXtreme Desktop Tools API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .141
View Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .142
Select Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .142
Add Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143
Custom Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Shape Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .144
Using InfoTips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145
Customizing Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146
Tool Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .147
Editing a FeatureGeometry with the Select Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Reshaping a Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .148
Adding Nodes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .150
Reshaping and Adding Nodes Programmatically. . . . . . . . . . . . . . . . . . . . . . . . . . . . .151
Chapter 8: Working with Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Overview of MapInfo.Data Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Catalog and Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161
Catalog. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .165
Supported Table Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Working with Catalog and Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .169
Locating Open Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .169
Closing a Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .170
Packing a Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .170
Listening to Table and Catalog Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Table Metadata (TableInfo) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172
Examining TAB File Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Creating a New Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .173
Adding Expression Columns to a Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .176
Data Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .177
Choosing the Correct Data Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .177
Methods for Accessing Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .178
Data Readers, MemTables and Result Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Using an ADO.NET Data Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Data Binding. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .183
Making Tables Mappable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .186
MapInfo ADO.NET Data Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
MIConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
MapXtreme 7 Developer Guide
Table of Contents
MICommand. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .190
MIDataReader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .192
MapInfo SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .193
Features and Feature Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .193
Feature. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .193
Feature Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .194
Searching for Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Catalog Search Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
SearchInfo and SearchInfoFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .196
Analyzing Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .200
Improving Data Access Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Chapter 9: Working with Core MapXtreme Classes . . . . . . . . . . . . . . . . . . . . . . 203
Session Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .204
Session Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .204
Using Session.Dispose Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .205
ISessionEventHandlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Serialization and Persistence. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Serialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .207
Persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Opening and Saving a Workspace Containing Named Resources . . . . . . . . . . . . . .208
Opening an MWS: ResolveResource() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .209
Saving an MWS: GetResourceName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .209
Registering Your Implementation with MapXtreme . . . . . . . . . . . . . . . . . . . . . . . . . . .209
Setting Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .209
Selection Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .209
Using Selection Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Selection Highlighting and Exporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .210
SelectionChangedEvent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
ISerializable Interface on Selection and Selections Classes . . . . . . . . . . . . . . . . . . . .211
Selection Code Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
Selecting Features Within Another Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .211
Checking a Table for Selections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
Returning All Columns From a Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .212
Changing the Map View Following a Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .212
Event Arguments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .213
Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .213
Chapter 10: Creating Expressions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
Expressions Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
Creating Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .215
Where Clause – Boolean Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
MapXtreme 8 Developer Guide
Table of Contents
Functions In Expressions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
DateTIme and Time Expressions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
Expression Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .217
Chapter 11: Accessing Data from a DBMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Accessing Remote Spatial Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Accessing Remote Tables Through a .TAB File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .222
Accessing Remote Tables Without a .TAB File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .222
Mapping DBMS Data with X/Y Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .223
Accessing Data from Oracle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .223
Geometry Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .223
Oracle Support for Z and M Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .224
SDO_GEOMETRY Arc and Circle Translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
Visualization of Non-translatable Oracle Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . .225
Centroid Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .225
Oracle Spatial Reference Support (SRID) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .225
OCI Connection Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .226
Accessing Data from MS SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .226
SQL Server 2008 Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
DBMS Connection String Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .229
ODBC Connection String Format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
ODBC Layers and Pooling in Web Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . .230
Oracle Spatial Connection String Format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .230
Sample Connection Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
Defining Mappable Tables in Server Table Queries. . . . . . . . . . . . . . . . . . . . . . . . . . .231
The Geometry Column. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
The Key Column(s) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .232
Accessing Attribute Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .233
Performance Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .233
Working with the Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
What Is the Cache? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .234
How the Cache Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .234
The TableInfoServer Object and the CacheSettings Property . . . . . . . . . . . . . . . . . . . 235
The MapInfo_MapCatalog. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Loading Spatial Data to DBMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .237
Manually Creating a MapInfo MapCatalog. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .237
Adding Rows to the MapInfo_MapCatalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .239
Per-Record Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Symbol, Pen, Brush Clause Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .244
Text Objects Limitation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .244
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .245
MapXtreme 9 Developer Guide
Table of Contents
Chapter 12: Adding Mapping Capability to Your Applications . . . . . . . . . . . . . 246
Introduction to the MapInfo.Mapping Namespace. . . . . . . . . . . . . . . . . . . . . . . . . . . .247
Base Mapping Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .247
MapExport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .247
Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .248
MapFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .248
MapLoader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
MapViewList, MapView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .249
MapControl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .249
Layers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .250
FeatureLayer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .250
Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .250
MapLayer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .251
UserDrawLayer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .251
ObjectThemeLayer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
GroupLayer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .251
LabelLayer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .251
GraticuleLayer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .251
Layer Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .251
IVisibilityConstraint. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .252
Code Example: Animation Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .252
Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .253
LabelLayer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .254
LabelSource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .254
LabelModifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .254
ILabelSourceFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .255
LabelProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Generating Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Label Priorities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .256
Label Layer Selectability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .256
Code Example: Creating a LabelLayer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .256
Curved Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
Adornments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .257
Legends . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .258
ScaleBar Adornment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .258
Title Adornment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .259
Feature Style Modifiers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
FeatureStyleModifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .260
FeatureStyleModifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
FeatureOverrideStyleModifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .260
Printing Your Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .261
MapXtreme 10 Developer Guide
Table of Contents
Chapter 13: Finding Locations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Functional Overview of Find . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
The Find Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .263
Matching Address Numbers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
Matching with a Refining Boundary Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .265
Find Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .265
Overview of the Data.Find Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
Find . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .266
.FindAddressRange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .268
FindCloseMatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .269
FindResult . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .270
Fine Tuning the Find Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
Editing the Mapinfow.abb File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
Chapter 14: Using Themes and Legends . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Thematics Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .279
Mapping.Thematics Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Modifier Themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .279
Object Themes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .280
GraduatedSymbolTheme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
When To Use a Graduated Symbol Theme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .281
PieTheme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .282
When To Use a Pie Theme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Printing a Map Containing Pie/Bar Themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .283
BarTheme. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .283
When To Use a Bar Theme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
Controlling Display Size for Pie and Bar Themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
RangedTheme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .284
When To Use a Ranged Theme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Types of Ranged Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
RangedLabelTheme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .286
When To Use a RangedLabelTheme Class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .286
Ranged Themes and Serialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .287
IndividualValueTheme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .287
When To Use an IndividualValueTheme Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .287
Creating an IndividualValueTheme with Custom Bitmap Symbols . . . . . . . . . . . . . .288
IndividualValueLabelTheme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
When To Use an IndividualValueLabelTheme Class. . . . . . . . . . . . . . . . . . . . . . . . . .289
IndividualValue Themes and Serialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .289
DotDensityTheme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .290
When To Use a DotDensityTheme Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .290
MapXtreme 11 Developer Guide
Table of Contents
Bivariate Thematic Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
Legends Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .291
Theme Legends . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .292
Cartographic Legends . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
Formatting a Legend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .293
Chapter 15: Stylizing Your Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
Overview of the MapInfo.Styles Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
StyleFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .296
Style Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .296
AreaStyle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .296
BitmapPointStyle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .296
CompositeStyle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .297
SimpleInterior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Font . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .297
FontPointStyle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .297
GridStyle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .297
RasterStyle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .298
Hillshade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .298
Inflection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .298
SimpleLineStyle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .298
BasePointStyle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .298
BaseLineStyle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .298
BaseInterior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .298
StockStyles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .299
TextStyle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .299
SimpleVectorPointStyle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
Pre-defined Styles and the StyleRepository Class . . . . . . . . . . . . . . . . . . . . . . . . . . .299
StyleRepository Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .299
Using Styles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .300
Styles and Layer Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
Creating a Custom Bitmap Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .300
Overriding Styles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .301
FeatureOverrideStyleModifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
Chapter 16: Spatial Objects and Coordinate Systems. . . . . . . . . . . . . . . . . . . . 302
Introduction to MapInfo.Geometry Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .303
Geometries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .303
Geometry Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .304
FeatureGeometry Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
Geometry Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .309
Including Your FeatureGeometry in a Map. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .310
MapXtreme 12 Developer Guide
Table of Contents
Checking for Points in Polygons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
Coordinate Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .312
Creating a CoordSys Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .313
Changing the Coordinate System of a Geometry Object . . . . . . . . . . . . . . . . . . . . . . .314
Determining the Coordinate System of a Map in MapControl . . . . . . . . . . . . . . . . . . . 314
Adding Coordinate Systems to MapXtreme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .315
Chapter 17: Working with Rasters and Grids . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
Overview of the MapInfo.Raster Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
Raster Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .319
Raster Classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .320
Raster Images and Coordinate Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .321
Raster Reprojection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .321
Raster Image Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .321
Code Sample: Adding a Raster Image to a Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . .321
Raster Handlers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .322
Raster Handler Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .323
Configuring Custom Raster Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .324
Grid Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .325
Grid Classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .326
Code Sample: Adding a Grid Image to a Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Code Sample: Retrieving Data from a Grid Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Grid Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .327
Grid Interpolators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .328
Inverse Distance Weighted (IDW) Interpolator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Triangulated Irregular Network (TIN) Interpolator . . . . . . . . . . . . . . . . . . . . . . . . . . . .329
IInterpolator Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .329
Grid Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
Grid Images and Inflections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .330
Inflection Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .330
Calculating Inflection Values and Colors for a Grid Layer . . . . . . . . . . . . . . . . . . . . . .331
Relief Shading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .331
Grid Style Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .332
GridInfoForm Sample Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .334
Chapter 18: Geocoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
Overview of the MapInfo.Geocoding Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . .336
Main Geocoding Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
GeocodeRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .337
GeocodeResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .337
GeocodeClientFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .337
GeocodingConstraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .338
MapXtreme 13 Developer Guide
Table of Contents
AddressCandidates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .338
BaseGeocodeMatchCode and GeocodeMatchCode. . . . . . . . . . . . . . . . . . . . . . . . . .338
CandidateAddress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .338
Understanding the Geocoding Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
Geocoding Trade-offs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .338
A Few Words About Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
What are Custom User Dictionaries?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .340
What is World Geocoding? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .340
Geocoding a Location. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
Street Address Geocoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .341
Street Intersection Geocoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .342
Postal Code Geocoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .343
Gazetteer Type Geocoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .343
Batch Geocoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .343
Using Constraints for Accurate Geocoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
What are the Match Constraints?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
Impact of Relaxing Match Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .346
Understanding Accuracy for Close Matches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
Single Close Match (S Category). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .347
Best Match from Multiple Candidates (M Category) . . . . . . . . . . . . . . . . . . . . . . . . . .348
Postal Code Centroid Matches (Z Category) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .348
Geographic Centroid Matches (G category) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .348
Non-Match Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .349
Chapter 19: Web Map Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Introduction to MapXtreme’s Web Map Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .351
Understanding WMS Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .351
Using MapXtreme as a WMS Client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .352
Code Example: Requesting a WMS Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .354
WMS and Coordinate Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
Map and Image Bounds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .354
MapXtreme WMS and Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .355
Basic Authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .355
Setting up a MapXtreme WMS Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .356
Step 1: Create a Web.config File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
Step 2: Create a Valid WMS Configuration File for Hosted Data. . . . . . . . . . . . . . . . .357
Step 3a: Configure and Test the WMS Server using IIS7 . . . . . . . . . . . . . . . . . . . . . . 361
Step 3b: Configure and Test the WMS Server with IIS6 . . . . . . . . . . . . . . . . . . . . . . .362
Configuring Layer Information for a WMS Server . . . . . . . . . . . . . . . . . . . . . . . . . . . .365
MapXtreme 14 Developer Guide
Table of Contents
Chapter 20: Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
Overview of MapInfo.Routing Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .370
Main Routing Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .370
Calculating Routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
Point-to-Point Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .371
Multi-Point Routing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .372
Matrix Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .373
Advanced Route Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .374
Routing Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .374
Driving Directions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .375
Route Geometry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .376
Avoiding Points, Features, and Segments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .376
Time-Based Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .377
Iso Routing (Drive-Time and Drive-Distance). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .378
Creating an IsoChrone (Drive-Time) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
Creating an IsoDistance (Drive-Distance) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .382
Updating a Request Using Routing Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .383
Returning Segment Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .383
Transient Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .384
Chapter 21: Linear Referencing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
What is Linear Referencing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .389
Using M values for Linear Referencing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .389
Measure Value Determination Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .391
Linear Referencing Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .391
Dynamic Segmentation Operation (PerpendicularOffset) . . . . . . . . . . . . . . . . . . . . . .392
Curve Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .392
Linear Referencing Sample Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .393
Chapter 22: Web Feature Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
Web Feature Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .395
Understanding WFS Server Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .395
Configuring a WFS Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .400
Step 1: Create a Web.config File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
Step 2: Create a Valid WFS Configuration File for Hosted Features . . . . . . . . . . . . . .401
Step 3: Configuring and Testing the WFS Server . . . . . . . . . . . . . . . . . . . . . . . . . . . .403
Using the MapXtreme WFS Client Programmatically . . . . . . . . . . . . . . . . . . . . . . . . .406
Using Filters in WFS Queries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .406
Creating a Map Layer from a WFS Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
MapXtreme 15 Developer Guide
Table of Contents
Chapter 23: Workspace Manager. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
Features of the Workspace Manager. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
Workspace Format and Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
Workspace Manager Menu Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
File Menu Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .415
View Menu Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .418
Map Menu Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
Tools Menu Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
Extensions Menu Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
Layer Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .425
Layer Control Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .425
Layer Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .425
Layer Control Tabs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .427
Map Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .427
Layer Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .431
Theme Layer Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .432
Label Layer Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .433
Group Layer Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436
Style Override Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .436
Graticule Layer Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436
Using Workspace Manager Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .438
Enhanced Rendering with GDI+ Translucency and Anti-Aliasing . . . . . . . . . . . . . . . .438
Creating Translucent Effects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .440
Curved Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
Graticule Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .446
Chapter 24: Using the GeoDictionary Manager . . . . . . . . . . . . . . . . . . . . . . . . . 449
Using the GeoDictionary Manager. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .450
Changes in the GeoDictionary Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .450
The GeoDictionary Manager’s User Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .450
Run GeoDictionary Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450
The GeoDictionary File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .453
Sample .dct file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .453
Appendix A: How to Create and Deploy a MapXtreme Application . . . . . . . . . 456
Customizing MapXtreme Samples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
Building a Desktop Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .457
Running a Sample Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .457
Modifying Your Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458
Building Under Release Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464
Packaging Your Desktop Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465
Deploying Your Desktop Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .467
MapXtreme 16 Developer Guide
Table of Contents
Building a Web Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467
Running a Sample Web Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467
Modifying Your Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469
State Management Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .471
Configuring for Release Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472
Packaging Your Web Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472
Deploying Your Web Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475
Appendix B: Customizing MapXtreme. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
Customizable Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .478
MapInfo.Data.Provider Namespace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478
ADO.NET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .478
Engine.CustomProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478
Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .479
FeatureStyleModifier or FeatureOverrideStyleModifier . . . . . . . . . . . . . . . . . . . . . . . .479
UserDrawLayer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .480
Windows.Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .481
Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .482
Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .483
GmlFeatureCollection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .484
WorkSpacePersistence and WorkSpaceLoader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484
Workspace Manager Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .485
Creating a Workspace Extension. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .485
Loading Your Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487
Unloading Your Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
Sample Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .488
Location of Application Data Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .489
Find Abbreviation File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .491
Appendix C: Understanding the MapInfo Workspace . . . . . . . . . . . . . . . . . . . . 492
What is the MapInfo Workspace? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
Structure of a Workspace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
Header Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .494
Connection Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .494
DataSource Definition Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495
Map Definition Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495
Creating an .MWS Workspace Programmatically from a .GST . . . . . . . . . . . . . . . . . .497
Appendix D: Extensible Data Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .500
Extensible Data Provider Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500
Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .502
Required Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .504
MapXtreme 17 Developer Guide
Table of Contents
Optional Building Blocks: Base Classes, Helpers and Utilities . . . . . . . . . . . . . . . . .506
Sample: COTW (Center of the World) Data Provider . . . . . . . . . . . . . . . . . . . . . . . . . . 507
Optional Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509
IDataSource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .509
IDataSourceDefinition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .509
ITableModifyProcessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .509
Building and Testing Your Data Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510
SpatiaLite Sample Data Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511
Advanced Topics / Important Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512
Creating Geometries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .513
Coordinate Systems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514
Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .514
Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .515
Persistence Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516
Serialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .518
Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .521
Thread safety . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .524
Appendix E: Printing From MapXtreme Applications . . . . . . . . . . . . . . . . . . . . 526
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .527
Understanding the Print Options in MapXtreme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527
Printing Sizes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .528
Special Transparent Raster Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .528
Special Transparent Vector Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .528
Display Raster in True Color When Possible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .529
GDI+ Translucency and Anti-Aliasing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .529
Dither Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .530
Special Polygon Hole Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .530
Scale Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .530
Print Directly to Device. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .531
Print Using Enhanced Metafile (EMF) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .531
Implementing Printing in Your Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .531
General Printing Tips and Tricks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .533
Printing a Legend in Your Map. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .533
Resolutions to Known Printing Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .536
Platform Independent Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536
Platform-Specific Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .537
Appendix F: Style Lookups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540
Fill Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .541
Understanding the Index Numbering Schemes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .541
Line Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .555
MapXtreme 18 Developer Guide
Table of Contents
Vector Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .556
MapInfo Arrows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556
MapInfo Cartographic. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .556
MapInfo Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .557
MapInfo Oil &Gas. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .557
MapInfo Shields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .557
MapInfo Real Estate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .558
Map Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .558
MapInfo Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .558
MapInfo Transportation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .559
MapInfo Weather . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .559
Custom Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560
MapXtreme Icons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .562
Appendix G: Defining the MapInfo Codespace. . . . . . . . . . . . . . . . . . . . . . . . . . 565
Defining the MapInfo Codespace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 566
Appendix H: Elements of a Coordinate System . . . . . . . . . . . . . . . . . . . . . . . . . 571
Projections and Their Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .572
Projection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .573
Projection Datums. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .576
Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .585
Coordinate System Origin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .586
Datum Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .588
Custom Datums. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .588
Defining Custom Datums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589
National Transformation v. 2 (NTv2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .593
Information on Coordinate Systems and Projections . . . . . . . . . . . . . . . . . . . . . . . . . 596
Appendix I: User-Defined Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 598
Metadata and the MapCatalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599
User-Defined Metadata Support for TableInfoServer Queries . . . . . . . . . . . . . . . . . .599
ColumnHints Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .599
Appendix J: Migrating to MapXtreme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603
Comparing MapXtreme’s Object Model to MapX . . . . . . . . . . . . . . . . . . . . . . . . . . . . .604
Specific Object Model Implementation Differences . . . . . . . . . . . . . . . . . . . . . . . . . . .604
Appendix K: Localization Kit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 614
Localization Kit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .615
System Requirement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .617
How to Use the Localization Kit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617
Building the Satellite Assemblies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .618
MapXtreme 19 Developer Guide
Table of Contents
Building from the Command Line. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .618
Private Key Signing for Satellite Assemblies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .620
Appendix L: Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621
Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .622
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629
MapXtreme 20 Developer Guide
Introduction to
MapXtreme
Welcome Developers to Pitney Bowes Software’s latest offering in the world of
.NET programming. In support of Microsoft’s .NET Framework for Windows,
MapXtreme reflects a single object model for developing or extending mapping
applications for the desktop, traditional client/server environments or the Web.
MapXtreme is an application development tool for organizations who recognize
that data visualization and mapping can help you make better business
decisions and manage assets and operations more effectively. MapXtreme is for
organizations that need to incorporate location analysis or definition into
desktop, client/server and web-based products. MapXtreme can be used as a
powerful analysis toolkit to make critical business decisions such as optimal
locations for sales offices, how to transport products most efficiently, and how to
manage and protect assets. Developers can use MapXtreme to shorten their
development time and improve performance, reliability, and security.
1
In this chapter:
Overview of MapXtreme. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
Migrating to MapXtreme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24
Learning to Use MapXtreme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26
Overview of MapXtreme
MapXtreme is Pitney Bowes Software’s premier Windows software development toolkit that allows
.NET-experienced developers to create powerful location-enhanced desktop and client/server
applications.
From this single SDK, you can develop applications using your favorite .NET programming
language, share and reuse code between desktop and web deployments, access data from a wide
variety of sources using standard protocols, and more.
This is all possible through MapXtreme’s object model, an API of 100 percent managed code that
was developed on Microsoft’s .NET Framework. The Framework’s Common Language Runtime
(CLR) provides the foundation that makes simplified development a reality.
The following components and features are included in MapXtreme:
• Product framework: The MapXtreme Object Model is built using the Microsoft .NET Framework
4.0. See Object Model Overview for more information.
• Development Environment Tools: A variety of templates, controls, sample code and tools help
you develop Windows Forms and ASP.NET applications within Visual Studio. You can extend
some of these components to provide more advanced functionality available through the object
model. Two data management utilities are included for managing tables that you will use in your
application (Geodictionary Manager) and manage workspaces for ease of use and portability
(Workspace Manager). See Chapter 5: Web Applications, Controls, and Tools and
.Chapter 7: Desktop Applications, Controls, Dialogs, and Tools.
• Full Mapping and Analytical capabilities: Map creation and display, data access, thematic
mapping, raster and grid handling, object processing and presentation, and more.
• Scalable Infrastructure: Session object pooling and caching capabilities offer big performance
gains for web applications. Maintain session and user information by saving information to
MapXtreme’s XML-based workspace format. See Chapter 9: Working with Core MapXtreme
Classes.
• Runtime Deployment: MapXtreme uses Windows Installer technology (merge modules) that
developers can use to install or redistribute runtime components used in deployed applications.
See Deploying Your Application.
• Extensive Documentation: Product documentation is at your fingertips as integrated
components in the Visual Studio development environment. The MapXtreme Learning
Resources page keeps you connected to all product resources, including what’s new and
changed in this release. It’s available from the Start menu.
Chapter 1: Introduction to MapXtreme
Overview of MapXtreme
Key Features
MapXtreme is packed with features and conveniences to help you build your Windows Forms or
ASP.NET Web applications efficiently. Regardless if you are making the map the cornerstone of your
application or are adding some basic mapping functionality to support your existing application, the
framework and tools you use are the same. Here is an overview of MapXtreme’s capabilities:
If you are new to Pitney Bowes Software’s mapping products, be sure to also see Chapter 3:
Mapping Concepts for additional help on the basics.
MapXtreme v7.1 22 Developer Guide
Chapter 1: Introduction to MapXtreme
Overview of MapXtreme
For developers upgrading to MapXtreme, see the Release Notes for what’s new and changed in the
product. See also Migrating to MapXtremefor a mapping of features in MapX to features in
MapXtreme .NET.
Feature
*
Purpose
Tables, Layers, Features Maps in MapXtreme consist of geographic features like point
locations, boundaries and street networks. The feature information
is stored in tables and display in the map as layers.
Data access MapXtreme supports data from a wide variety of sources, including
spatial and non-spatial RDBMS, MS Access, dBase and ASCII, as
well as its own native type the MapInfo Table (.TAB). All data
operations are carried out via the MapInfo.Data namespace.
Operations include adding and removing tables, and inserting,
updating and deleting records from a variety of data sources.
.NET Dataset Provider support: allows any ADO.NET dataset
provider to be treated as a table in MapInfo.Data. This will allow you
to use external non-mappable data.
Web Services MapXtreme provides clients and APIs for you to access several
popular web services: geocoding, routing, WMS and WFS.
Selections and Searches This common mapping operation allows you to find just the data
that matches your criteria, by using attributes or spatial queries.
Thematic mapping One of the most widely used ways of analyzing your data is to show
the visual relationship and underlying data through theme maps.
MapXtreme supports the creation and use of six themes: ranged,
individual value, graduated symbol, dot density, and pie and bar
charts.
Labeling MapXtreme provides a sophisticated labeling capability for you to
label features with names or other information (column data or
expressions), and create ranged and individual value themes on
the labels themselves to impart your message without relying on
text alone.
Map Styling Labeling is one form of map styling that you can control on your
map in nearly infinite ways. Style also refers to the color, patterns,
fonts, line styles and symbols of map features that is used in many
areas of MapXtreme, including features, adornments (map titles),
dialog boxes and text.
MapXtreme v7.1 23 Developer Guide
Chapter 1: Introduction to MapXtreme
Migrating to MapXtreme
Feature
Geographic processing and
analysis
Projections and Coordinate
Systems
* Some features or tools in this product may not be supported for some languages or in some regions.
Please consult your local customer service representative for details.
*
Migrating to MapXtreme
The following is a table that compares features and functionality from MapX and MapXtreme v3.0
with that of MapXtreme .NET. As with any new architecture of a product, note that the equivalent
may not be exact. Use the MapXtreme topics in the right column of this list to find further details
elsewhere in this Developer Guide and in the online help and object model. A full list of the MapX
object model and the equivalent functionality in MapXtreme is covered in Appendix J: Migrating to
MapXtreme.
Purpose
This refers to making new features from existing ones, such as
combining postal code boundaries to create sales territories. It also
refers to using the feature’s location coordinates to learn more
about its relationship to other features. For example, create a buffer
around a point that measures five miles in radius to find out what
other points fall within the buffer zone.
These are ways of representing locations on a two-dimensional
map. Knowing the coordinate system of your data allows you to line
up features properly for accurate display and measurement.
MapXtreme supports a wide variety of projections and coordinate
systems and provides information for creating your own.
MapX5.0 /MapXtreme3.0 MapXtreme
Map object Map class: holds collection of Layers.
MapControl: way to view a map on a form.
MapInfo.Mapping namespace
MapXBroker Session class: starting point for all MapXtreme-based
applications.
Related topics: MICommand, Catalog, Pooling
MapInfo.Engine namespace
Layer-centric model Tablecentric model
Related topics: Table metadata (TableInfo class), Feature class,
Column class (MI_Geometry, MI_Style, MI_Key), MapInfo
ADO.NET data provider.
MapInfo.Data namespace
MapXtreme v7.1 24 Developer Guide
Chapter 1: Introduction to MapXtreme
Migrating to MapXtreme
MapX5.0 /MapXtreme3.0 MapXtreme
Datasets, data binding Add a temporary column to an Table using the
Table.AddColumns() method.
Related topic: Geodictionary Manager
MapInfo.Data namespace
Geosets. Geoset Manager Workspaces (.MWS): XML format. Geosets are supported.
Related topics: Workspace Manager.
MapInfo.Persistence namespace
Annotations Adornments: a Legend, a Title, a Scalebar, or some other similar
user-defined object in a single map.
MapInfo.Mapping namespace
Thematic mapping Same thematic map types. Themes are no longer layers.
Related topics: ModifierThemes (graduated symbol, pie and bar
themes), ObjectThemes (ranged, individual value, dot density
themes.
MapInfo.Mapping.Thematic namespace
Feature layer and Feature
Collections
FeatureGeometry: all geometries are now objects. Includes point,
multipoint, curve, multicurve, polygon, multipolygon ring.
Geometries include rectangle, rounded rectangle, ellipse, legacy
arcs, legacy text.
Related topics: CoordSysFactory (registered coordinate systems),
object processing (see FeatureProcessor, below)
MapInfo.Geometry namespace
FeatureFactory FeatureProcessor class: object processing Buffer, Combine,
Intersection, ConvexHull.
Related topic: Difference (formerly Erase) in FeatureGeometry
class.
MapInfo.Geometry namespace
Tools Desktop tool SelectRegion can assign to mouse buttons and
configure mouse wheel for zooming.
MapInfo.Tools namespace
MapXtreme v7.1 25 Developer Guide
Chapter 1: Introduction to MapXtreme
Learning to Use MapXtreme
MapX5.0 /MapXtreme3.0 MapXtreme
Raster and Grid Images New table structure, RasterImageInfo, GridImageInfo.
Related topics: controllable styles: brightness, contrast,
color/grayscale, translucency, one-color transparency.
MapInfo.Raster namespace
Label objects and Label
collections
Selection object Selection class: a multi-feature collection of lists of features that
Spatial Server connectivity MI ADO.NET data providers, MapInfo SQL language.
Style Object Style class: new object model. Styles are now objects, not
LabelLayer: allows the separate ordering of labels and layers.
LabelSource: information from the data source that is used for
labeling.
MapInfo.Mapping namespace
are tied to a table.
MapInfo.Engine namespace
MapInfo.Data namespace
properties of other objects; information is stored in column
MI_Style.
Related topics: FeatureStyleModifiers,
FeatureOverrideStyleModifiers in the MapInfo.Mapping
namespace.
MapInfo.Styles namespace
Learning to Use MapXtreme
MapXtreme has a lot to offer beginning and experienced .NET developers alike. This section
describes several support mechanisms we have created to get you up and running quickly and with
minimal disruption in your development timetable.
Support Resources
MapInfo is committed to supporting new MapInfo developers as well as our long time customers. We
provide a wide variety of tools to help you make the transition or get up and running quickly in the
Visual Studio environment with the following resources.
MapXtreme v7.1 26 Developer Guide
Chapter 1: Introduction to MapXtreme
Learning to Use MapXtreme
MapXtreme Learning Resources Page
Accessible from the Start Menu after you install MapXtreme, the Learning Resources Page brings
together a wide variety of information about MapXtreme, including best development practices, code
samples, tutorial web applications, links to all documentation and online resources on the MapInfo
website, and much more. Refer to this page often to get comfortable with MapXtreme and as you
continue to develop mapping applications that match your business needs.
Documents and Help Systems
This MapXtreme Developer Guide provides an overview of the MapXtreme development
environment and namespaces. The Visual Studio-integrated Help System provides the more specific
API-level information you need to use these tools to develop integrated Windows desktop and
web-based applications with the MapInfo powerful mapping components. If you have comments
regarding the documentation, you can send them to support.pbbi@pb.com.
L The above-mentioned email address should not be used for questions specific to the
software or clarification about subjects contained in the documentation. Please send those
questions to Technical Support (see below).
If you are new to using or developing with MapInfo mapping products, be sure to see Chapter 3:
Mapping Concepts.
To get the latest release information, be sure to download a copy of the MapXtreme Release Notes
from the Pitney Bowes Software website.
Technical Support
Pitney Bowes Software offers unparalleled technical support for users of MapInfo software products.
Our Technical Support department provides technical assistance to registered users of MapInfo
software – so you don't need to be an expert in all aspects of our products in order to get results.
See the Pitney Bowes Software Web site at www.pb.com/software for information on the tech
support offerings.
MapXtreme v7.1 27 Developer Guide
Getting Started
This chapter provides all the information you need to install, configure, and
deploy your first MapXtreme application.
In this chapter:
Installation Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29
Types of Installations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30
MapXtreme Licensing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31
Before You Install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37
Installing MapXtreme in Your Environment . . . . . . . . . . . . . . . . . .40
Upgrading to MapXtreme. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
Migrating Web Sites to 64-bit Web Applications . . . . . . . . . . . . . .43
Creating Applications in Visual Studio . . . . . . . . . . . . . . . . . . . . .46
Building ASP.NET Web Applications Without a Template . . . . . .50
Deploying Your Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52
2
Installation Requirements
Pitney Bowes Software Inc.has tested and supports MapXtreme on the following.
Architecture • 64-bit
Operating Systems • Windows 7 (x86, x64)
Chapter 2: Getting Started
Installation Requirements
• 32-bit
• Windows Vista with SP2 (x86 , x64)
• Windows Server 2008 R2 (x64)
• Windows Server 2008 with SP2 (x86 , x64)
• Windows Server 2003 R2 with SP2 (x86 , x64)
• Windows Server 2003 with SP2 (x86 , x64)
• Windows XP with SP3 (x86 , x64)
Development Framework and IDE
Support
*
• Microsoft .NET Framework 4.0
• Visual Studio 2010 with SP1 (Professional, Premium,
Ultimate)
Browsers
• Internet Explorer 8.0 , 9.0
**
• Firefox 3.5 , 13 and higher
• Chrome 20
For web application and deployment: • IIS 6 (Windows Server 2003)
• IIS 7 (Windows Vista, Windows Server 2008, and
Windows 7)
Supported databases
• Microsoft Access 2007 and Excel 2007
• Microsoft Access 2003
• Oracle 11G (11.1.0.6.0 and 11.1.0.7.0)
• Oracle 10G, 10GR2
• Microsoft SQL Server 2012 (with SQL Native Client 11)
• Microsoft SQL Server 2008 (with SQL Native Client 10)
• MapInfo SpatialWare® 4.9 and 4.9.2 for Microsoft SQL
Server 2005
• MapInfo SpatialWare® 4.9.2 for Microsoft SQL Server
2008 32- and 64 bit editions
For data access: • MDAC 2.8
* Recommended development environments (IDE). Others can be used, however, the MapXtreme installer will
not integrate its templates, samples, and help system.
**
The MapXtreme Learning Resources displays in Internet Explorer automatically, regardless of your default
browser setting. This will not change your default browser setting.
MapXtreme v7.1 29 Developer Guide
Chapter 2: Getting Started
Types of Installations
L MapXtreme does not support the Express Editions of Microsoft Visual Studio.
L MapXtreme does not support the Borland Delphi development framework, nor does it
support the Cold Fusion or HAHT Web development frameworks.
Minimum System Requirements
Memory Windows 7: 1 gigabyte (GB) RAM (32-bit), 2 GB RAM (64-bit)
Windows Vista: 1 GB RAM
Windows Server 2008: 512 megabytes (MB) RAM
Windows Server 2003: 256 MB RAM
Windows XP: 256 MB RAM
Processor Windows Vista, Windows 7: 1 GHz processor
Windows Server 2008: 1.6 GHz (x64) processor
Windows XP: 800-MHz Pentium III-class processor
Video Card Graphics card that supports at least 256 colors
Types of Installations
MapXtreme provides two installation types: one for Development (SDK) and one for Deployment
(Runtime). Each is selectable from the product CD Browser.
Development (SDK) Installations
The Development Installation installs the MapXtreme Software Development Kit (SDK) on your
computer. Choose this installation to develop your desktop and web applications. Upon installation,
this SDK is automatically integrated with Microsoft Visual Studio and works in conjunction with the
.NET Framework. The SDK provides C# and VB application templates for simplified development.
For instructions on how to install the SDK, see Installing MapXtreme in Your Environment.
Instructions are also available from the Help buttons on the installation dialog boxes.
MapXtreme v7.1 30 Developer Guide
Chapter 2: Getting Started
MapXtreme Licensing
Deployment (Runtime) Installations
The Deployment installation option installs the Location Runtime Environment which lays down the
MXTRuntimeNCP.exe (or MXTRuntimeSCP.exe for software-copy protected versions of
MapXtreme). For instructions on installing the Runtime installer see Deploying With the Runtime
Installer.
Side-By-Side Installations and Use
You may have more than one version of MapXtreme installed on your system at the same time.
Each version of MapXtreme installs into its own directory.
You may also build a desktop and web application against an earlier version of MapXtreme and run
it against a later version.
You may run more than one ASP.NET application on the same computer if they are built with
different versions of MapXtreme. Create an application pool for each version of MapXtreme and
place the appropriate ASP.NET application in it. Restart IIS by issuing an iisreset from a command
prompt or recycle the application pool that the application is assigned. When an application runs in
its own process space, it will load the appropriate version of MapXtreme.
This does not affect desktop applications created with different versions on MapXtreme. Each
desktop application always runs in its own process space.
MapXtreme Licensing
All MapXtreme installations require a license (.lic) file. Some licenses are provided in the installation,
others must be obtained from Pitney Bowes Software Inc. The following topics describe the types of
licenses and how you can obtain one from Pitney Bowes Software.
Types of Licenses
Depending on your purpose and needs, three types of licenses are available for MapXtreme— SDK
(developer), runtime (deployment), and trial licenses.
SDK License
The SDK (Software Development Kit) license (MapXtremeSDK.lic) is for developers to create
desktop and web applications. Applications developed using this license will display a small
watermark in the upper-left corner of the map window.
Runtime License
Runtime, or deployment, licenses are required for all runtime desktop and web installations.
• For desktop runtime deployments built using the NCP version of MapXtreme, the license (e.g.,
MapXtremeDesktop.lic) can be used on multiple installations.
MapXtreme v7.1 31 Developer Guide
Chapter 2: Getting Started
MapXtreme Licensing
• For desktop runtime deployments built using the SCP version of MapXtreme, a license (e.g.,
MapXtremeDesktopIntl.lic, for example) is required for every installation.
• For web runtime deployments built using the NCP or SCP version of MapXtreme, a license (e.g.,
MapXtremeWeb.lic) is required for every installation.
See Runtime Licenses for Deployment for information on packaging licenses in your distribution.
Trial License
The trial license (MapXtremeTrial.lic) is provided in the SDK and the Evaluation version of
MapXtreme. It expires 60 days from the date of installation. Applications that are developed using
the trial license display a watermark on the map that also indicates the number of days remaining for
the trial license.
Obtaining a License
SDK Licenses for Development
Users of the non-copy protected Software Development Kit (NCP SDK) automatically receive a
perpetual SDK license (MapXtremeSDK.lic), as well as a trial license when they install. With the
perpetual license you can continue to use the SDK as long as you want. No other SDK license is
necessary.
Users of the copy-protected SDK (SCP SDK) receive a trial license only. To use the SDK
permanently, you must obtain a perpetual SDK license from Pitney Bowes Software. To do this, run
MILicenseNodeID.exe (found under Program Files\Common files\MapInfo\MapXtreme\7.x.x\License
Tool) to generate a unique machine-specific hardware ID contained in a text file called
MILicenseNodeID.txt. Pitney Bowes Software uses this information to generate a custom license for
your particular installation. For complete details on obtaining a license, see the Software Copy
Protection Notice in the product box or installed under Program Files\MapInfo\MapXtreme\7.x.x\
Documentation\PDF\SoftwareCopyProtectionNotice_SCP.pdf. Contact Pitney Bowes Software (or
its representative) at the appropriate email or fax number for your region as provided on the notice.
When you receive your permanent license, copy it to the Program Files\Common Files\
MapInfo\MapXtreme\7.x.x folder prior to first use of the deployed application.
Evaluation users will be required to purchase the product before receiving a permanent license.
Runtime Licenses for Deployment
MapXtreme requires that you include a runtime license in every deployment. To do so, you must
either provide the license in your package or include a licensing tool for your customers to obtain the
license themselves. Runtime licenses are obtained from Pitney Bowes Software. This license type
also removes all watermarks from the map.
The type of runtime license you need depends on what type of application you are building and the
version of MapXtreme you use. Find your situation in the table below:
MapXtreme v7.1 32 Developer Guide
Chapter 2: Getting Started
MapXtreme Licensing
Deployment
Typ e
Desktop Non-copy-protected
Desktop Copy-protected
Web NCP Yes Generate a node ID file for each seat and
Web SCP Yes Generate a node ID file for each seat and
To generate a node ID for the deployment machine, run the licensing tool MILicenseNodeID.exe and
submit the resulting text file to Customer Service. The license tool is installed with the MapXtreme
SDK into Program Files\Common Files\MapInfo\MapXtreme\7.x.x\License Tool. See the Software
Copy Protection license application document in your MapXtreme package or under Program
Files\MapInfo\MapXtreme\7.x.x\Documentation\PDF.
The license tool is included in the merge module MapInfoMXTConfig_7.x.x.msm. Your users will get
this tool automatically when you include the MapInfoCoreEngine.msm in your distribution. See
Steps for Deploying an Application Using the Runtime Installer.
SDK Version of
MapXtreme
(NCP)
(SCP)
Node-
Locked? How to Obtain Runtime License
No Contact Customer Service for a runtime
license for one or more seats.
Yes Generate a node ID file for each seat and
submit to Customer Service.
submit to Customer Service.
submit to Customer Service.
L Generally, web licenses cannot be used for desktop deployments and vice versa. If it is an
SCP version, then the license (web or desktop) is node-locked to the machine on which you
are deploying.
When contacting Pitney Bowes Software for a license, specify the version of MapXtreme.
Locations of License Files
Use the following chart to determine where your license is located or where you should place it:
License
Type License Name Location of License
Developer
SDK NCP MapXtremeSDK.lic Program Files\Common
Files\MapInfo\MapXtreme\7.x.x
SDK SCP MapXtremeSDK.lic Program Files\Common
Files\MapInfo\MapXtreme\7.x.x
Runtime
MapXtreme v7.1 33 Developer Guide
Chapter 2: Getting Started
MapXtreme Licensing
License
Type License Name Location of License
Desktop NCP MapXtremeDesktop.lic In the same folder as the application executable to
avoid potential conflicts with other applications
Desktop SCP MapXtremeDesktopIntl.lic In the same folder as the application executable to
avoid potential conflicts with other applications
Web NCP MapXtremeWeb.lic Program Files\Common
Files\MapInfo\MapXtreme\7.x.x
Web SCP MapXtremeWeb.lic Program Files\Common
Files\MapInfo\MapXtreme\7.x.x
Trial
SDK NCP
SDK SCP
Evaluation
MapXtremeTrial.lic Program Files\Common
Files\MapInfo\MapXtreme\7.x.x
MapXtreme v7.1 34 Developer Guide
Chapter 2: Getting Started
MapXtreme Licensing
Troubleshooting
If you encounter problems with MapXtreme licensing, use the following table to help analyze and
solve the problem. For any issue, always check that the correct licenses are installed in the correct
locations (see Locations of License Files).
Troubleshooting Licensing Problems
Problem Description Possible Cause Solution
"Licensing ErrorUnable to
Initialize MILicensing object."
“No valid license found for
MapXtreme 200x”
Occurs when the MapXtreme
licensing service is not running.
The MapXtreme licensing for
64-bit applications requires a
Windows Service to be
operational on the local
application host. The service is
automatically installed during
the MapXtreme installation
process, and, as a Windows
Service, is managed using
Services.msc.
Could occur when using
Remote Desktop. Need a new
license with a format that has
Terminal Services activated.
Corrupt license file Remove license from machine,
Permissions needed Ensure the ASP.NET user
Verify that the
MILicensingService is installed
with a status of 'Started'.
Reset the server, place new
license in the appropriate
directory, then restart IIS and the
ASP.NET worker process.
regenerate license, place new
license in the appropriate
directory, then restart IIS.
account has Read/Write access
to the Temp directory and
Framework directories (see
Permissions to Temp Directory
for Deployed Web
Applications).
COM+ Activation error Usually a bad or corrupt license
file. It stops the COM+ object
from initializing and therefore
causes a low-level OS fault in
COM+.
MapXtreme v7.1 35 Developer Guide
Remove license from machine,
regenerate license, place new
license in the appropriate
directory, and then restart IIS.
Chapter 2: Getting Started
MapXtreme Licensing
Troubleshooting Licensing Problems (continued)
Problem Description Possible Cause Solution
A license exception occurs
when using a trial version
downloaded from the Pitney
Bowes Software website
(System.ComponentModel.Li
censeException' occurred in
mapinfo.coreengine.dll.)
The merge modules (MSM) in
the trial version are missing
(\Common files\Merge
Modules\).
The Volume Shadow Copy
Service prevents licenses
from being found.
A MapXtreme folder (from a
previous) prevents valid
licenses from being found.
The MapXtreme trial license is
invalid due to a detected
system clock setback.
The merge modules are left out
of the trial version because the
it is not meant to be deployed.
Related to a Veritas backup.
There is a possibility of a
network change based on the
backup software. The backup
process is locking files and
possibly not allowing access.
An invalid license file may have
been present in the old
directory and would have
caused the failure.
Install the trial on a different
machine or purchase a valid
license.
Purchase a runtime license.
Check whether the backup
process is running under the
same ID as the Exponare
process. If yes, then there is a
possibility of Terminal Services
being the problem. A new license
will fix the problem.
Find and delete old invalid
licenses. Place new license in the
appropriate directory.
The MapXtreme license
distributed with Exponare
unlocks some sites but fails to
Multiple network cards are
present in the system.
Obtain the correct license file.
Place new license in the
appropriate directory,
unlock others.
A license file will not unlock
MapXtreme unless it is both in
the MapXtreme\7.x.x folder
and the web application
Permission errors in how the
server is run and which user ID
is used.
Set the correct permissions (see
Permissions to Temp Directory
for Deployed Web
Applications).
folder.
MapXtreme license files
appear to expire after
approximately 15 days.
Terminal Services Make sure you are using the
latest build of the license
generator that accommodates
terminal services.
MapXtreme v7.1 36 Developer Guide
Chapter 2: Getting Started
Before You Install
Troubleshooting Licensing Problems (continued)
Problem Description Possible Cause Solution
MapXtreme license node ID
changes and causes
Exponare license to revert to
trial license when a Virtual PC
is moved.
Directly after installation and
first use, user gets the error
message “Your MapXtreme
trial license has expired”.
Known Issues with Licensing
The following are known issues with MapXtreme licensing. Contact Technical Support to assist you
in dealing with these problems (see Technical Support).
• Virus software strips content from license email, leaving Null in the license file.
• License generator occasionally creates corrupt license files.
Before You Install
The following are things to be aware of prior to installing MapXtreme.
Moving a Virtual PC changes
the network node ID and thus
invalidates the license.
Installing a generated runtime
(deployment) license instead of
using the NCP SDK license
they already had.
Obtain a new license
Use the perpetual SDK license
that comes with the NCP SDK..
Administrator Privileges
To install MapXtreme, you must be an Administrator on the machine or the current user must be a
member of the group Administrator. This applies to both types of installation (SDK and Runtime).
L For Windows Vista, Windows 7 and Windows Server 2008, regular administration rights are
not sufficient because the installer must register the COM+ object. Vista users must rightclick Setup.exe and choose: 'Run as administrator' to obtain system privileges for the
installer.
Install .NET Framework and Visual Studio First
Before you install MapXtreme, be sure that you have the .NET Framework and the Visual Studio
environment appropriate for the framework installed.
L You may use a different development environment than Visual Studio, however, the
templates, samples, and the online help system will not be integrated.
MapXtreme v7.1 37 Developer Guide
Chapter 2: Getting Started
Before You Install
IIS 7.x and IIS 6 Support
MapXtreme supports web deployment under Internet Information Services (IIS) 6 and IIS 7.
For IIS 6, the operating system requirement is Windows Server 2003. For IIS 7, the operating
system requirement is Windows Vista, Windows Server 2008 or Windows 7. MapXtreme does not
support web deployment on Windows XP.
Throughout the Developer Guide references to IIS will refer to IIS 7. Where necessary, instructions
for using IIS 6 for backward compatibiltiy are provided.
IIS 7.x is included (although not necessarily installed) with Windows Vista, Windows Server 2008
and Windows 7 Ultimate. MapXtreme supports IIS 7.0 in both classic mode and integrated pipeline
mode.
Prior to installing MapXtreme, configure IIS 7.x following the steps below. These steps apply to
Windows VIsta, Windows Server 2008 and Windows 7.
1. Enable Windows Authentication and Anonymous Authentication.
a. Go to Control Panel > Administrator Tools, right-click IIS and choose to “Run As
Administrator”.
b. Select Default Web Site.
c. Under the IIS group, double-click Authentication.
d. Rright-click Anonymous Authentication and choose Enable. Do the same for Windows
Authentication.
2. Enable the Web Managment Tools.
a. Go to Control Panel > Programs and Features.
b. Click Turn Windows features on or off. The Windows Features dialog box opens.
c. Select the Internet Information Services checkbox.
d. Double-click (or expand) Web Management Tools, and select all checkboxes below it.
3. Enable World Wide Web Services.
a. In the Windows Features dialog, double-click (or expand) the World Wide Web Services and
check the boxes itemized below.
b. Application Development Features - select all.
c. Common HTTP Features: Default Document, Directory Browsing, HTTP Errors, Static
Content and WebDAV Publishing
d. Health and Diagnostics: HTTP Logging, Request Monitoring
e. Performance: Static Content Compression
f. Security: Request Filtering and Windows Authentication
MapXtreme Web Controls and IIS
MapXtreme's Web Controls have always modified the web.config file of your ASP.NET automatically
to include the required modules and handlers. With MapXtreme 7.1, we fully support IIS7 integrated
pipeline mode, and will also auto-modify the web.config file to include the necessary code under the
system.webServer node. To maintain compatibility with previous ASP.NET applications built to run in
IIS6, or IIS7's 'Classic' pipeline mode, the Integrated Pipeline code will only be entered into the
web.config file if the MapInfo.Engine.Session.PipelineMode property is set to 'Integrated'. This
property is added to the 'appSettings' node of the web.config file when any ASP.NET project is
MapXtreme v7.1 38 Developer Guide
Chapter 2: Getting Started
Before You Install
loaded into VS2010 with MXT 7.1 installed on your system. Initially, this property is commented out.
Simply uncomment to make the proper edits for an application running in Integrated Pipeline mode
in IIS7. Change the value to 'classic', or simply recomment the property, to comment out the
system.webServer node for backwards compatibility with Classic Pipeline more or IIS6.
Default Install Directories for MapXtreme
MapXtreme is a 64-bit application that installs by default into C:\Program Files on 64-bit computers
or in C:\Program Files (x86) on 32-bit computers.
Both default paths are included in the Web.config files of the MapXtreme sample applications. If you
have installed MapXtreme to another location, you must edit the Web.config files to point to that
location for the samples to run properly.
L For non-English US (ENU) installations of Windows, the default installation directory
C:\Programmer\ is considered a custom install location by MapXtreme. You must edit the
samples Web.config files to point to your install directory, as the example below shows.
<configuration>
<appSettings>
<add key="MapInfo.Engine.Session.Workspace"
value="C:\Programmer\MapInfo\MapXtreme\7.x.x\Samples\Data\World.mws"
/>
</appSettings>
</configuration>
Additional Installation Features
MapXtreme provides online installation instructions to follow. You can also access the instructions
via the Help button on the install dialogs during installation.
MapXtreme provides free sample data for a variety of world locations. To install the data, choose
Install Sample Data from the CD Browser. You can control how much of the data you wish to install
by choosing the Custom option. The Complete option (default) will install about 450 MB of world data
sets under Program Files\MapInfo\MapXtreme\7.x.x\Samples\Data.
L You do not need to run this data installer in order to use the sample applications that ship with
MapXtreme. Basic sample data is automatically installed to the \Data folder for this purpose.
The MapXtreme CD Browser also provides a link to the PDF version of this Developer Guide.
MapXtreme v7.1 39 Developer Guide
Installing MapXtreme in Your Environment
Installing MapXtreme in Your Environment
To install MapXtreme:
1. Place the MapXtreme product media in the disk drive.
2. At the CD Browser main page, click Install. The Install Description page appears.
3. Choose either Development Install to install the SDK or Deployment Install to install the runtime
version.
L The Deployment installation requires a runtime license. See Runtime Licenses for
Deployment.
4. Choose Install SDK or Install Runtime. At the Welcome dialog box, click Next to proceed. For
deployment installations skip to step 10.
L You may also review the installation instructions and install sample data from this page.
5. At the Installer Welcome dialog box, read the information in the panel and click Next to proceed.
Chapter 2: Getting Started
6. Choose to accept the License Agreement. Click Next. The Customer Information dialog box
appears.
MapXtreme v7.1 40 Developer Guide
Chapter 2: Getting Started
Installing MapXtreme in Your Environment
7. At the Customer Information dialog box, enter your user name and company name in the
appropriate fields and, if necessary, the product serial number which is located on the package.
Click Next. The Setup Type dialog box appears.
8. At the Setup Type dialog box, select Complete or Custom. Choose Custom if you want the
features to be installed or to install to a location other than the default (C:\Program
Files\MapInfo\MapXtreme\7.x.x). Click Next. If you chose Complete proceed to step 10. If you
chose Custom continue to step 9.
L If you install MapXtreme to a location other than the default or on a version of Windows
XP other than the English US (ENU), you will need to edit the web.config file of any
sample web application you intend to run after installation. See the sample web
application’s ReadMe.rtf file for instructions on editing the web.config file.
MapXtreme v7.1 41 Developer Guide
Chapter 2: Getting Started
Installing MapXtreme in Your Environment
9. If you chose Custom in the previous step, select the components that you want to install, or click
the Change button to specify a new installation path. Click Next.
10. At the Ready to Install the Program dialog box, click Install.
11. The Installing MapXtreme dialog box launches.
MapXtreme v7.1 42 Developer Guide
12. At the InstallShield Wizard Completed dialog box, uncheck the Launch Learning Resources
checkbox if you do not wish to view the MapXtreme Learning Resources page, and then click
Finish to leave the software installer.
The MapXtreme Learning Resources page is available anytime from the Windows Start menu
from an SDK installation It is not available for a runtime installation.
Upgrading to MapXtreme
Chapter 2: Getting Started
Upgrading to MapXtreme
MapXtreme installs into its own directory using the form \<installdir>\MapInfo\MapXtreme\7.x.x.x,
where X.x.x is the current release. It will not overwrite a previous version. This allows you to
maintain side-by-side installations of different releases of the product.
For a side-by-side installation, copy your old license file to the location of the newest installation
(Program Files\Common Files\MapInfo\MapXtreme\7.x.x.).
Note, when using a side by side install, you must close Visual Studio before opening a project of a
different type. For web applications, you will also need to reset Internet Information Services (IIS).
Use the iisreset.exe command in a console window or from the Start > Run menu option.
Migrating Web Sites to 64-bit Web Applications
MapXtreme supports creating 64-bit web applications. If you have an existing Web site, you will
need to migrate them to a Web application to take advantage of 64-bit processing. You may continue
to build MapXtreme-based Web sites that are 32-bit only (see Updating Existing Web Sites on
page 44).
There is nothing specific to MapXtreme when migrating a Web site to a Web application. For more
infromation, see the following Microsoft topics Web Application Projects versus Web Site
Projects and Walkthrough: Converting a Web Site Project to a Web Application Project in
Visual Studio.
MapXtreme v7.1 43 Developer Guide
Chapter 2: Getting Started
Migrating Web Sites to 64-bit Web Applications
Updating Existing Web Sites
Follow the instructions in this section if you wish to update a 32-bit MapXtreme Web Site to use the
latest assemblies.
In order to run a Web site created with a previous release of MapXtreme, you must edit your
application’s Web.config file to point to the new versions of the assemblies.
Assemblies are located in C:\Windows\Microsoft.NET\assembly\GAC_32.
At a minimum, you must include MapInfo.CoreEngine.dll, MapInfo.CoreEngine.Wrapper.dll,
MapInfo.CoreTypes.dll and MapInfo.WebControls.dll.
When you are finished editing, save your Web.config file and rebuild your web site.
Check that the Copy Local property for your web controls is set to False. See Set Copy Local
property to False on page 45.
Updating Existing Desktop Applications
Desktop applications created with a previous release of MapXtreme can be recompiled to work in
the current release. Controls may have to be re-added to the form.
There are several things you need to do first.
• Set Copy Local property to false
• Add new assemblies to project
• Redirect assemblies to the new assemblies
MapXtreme v7.1 44 Developer Guide
Chapter 2: Getting Started
Migrating Web Sites to 64-bit Web Applications
Set Copy Local property to False
Verify that the Copy Local property for your controls is set to False. There exists a known issue that
when you drag and drop a MapXtreme desktop control onto a Windows form, references are loaded
that have the Copy Local property set to True. MapXtreme references must point to assemblies
residing in the Global Assembly Cache (GAC), not to the local bin path, which is what happens when
Copy Local is set to True.
The same behavior exists for ASP.NET Web applications when dragging and dropping MapXtreme
web controls onto a form or when building a console application that is not based on a MapXtreme
template. The same workaround applies here: Set the Copy Local property to FALSE.
This does not occur when using the MapXtreme web application template or sample applications,
which are based on the MapXtreme web application template.
Add New Assemblies to Project
The illustration below highlights the assemblies used for MapXtreme desktop applications.
Redirecting MapXtreme Assemblies To Newer Versions
You must redirect your application to use the current version of the assemblies. Microsoft provides
several mechanisms to redirect assemblies. For more detailed information, see Microsoft’s .NET
Framework Developer Center.
Application Configuration File
It is recommended that you use an application configuration file to accomplish assembly redirection.
The configuration file must be located in the same directory as the application and is named after the
application. For example, the configuration file for myApp.exe must be named myApp.exe.config.
The application configuration file overrides settings in the publisher's policy file.
To redirect assemblies, you must identify the version numbers and PublicKey tokens for the current
release and add them to your application configuration file. The version number is in the form
X.x.x.x, for example, 7.1.0.200.
MapXtreme assemblies are located in C:\Windows\Microsoft.NET\assembly\GAC_32.
Publisher Policy File
A publisher policy file containing redirection settings could be installed in the GAC with the
assembly. However, this is not a supported Pitney Bowes Software configuration.
MapXtreme v7.1 45 Developer Guide
Machine Configuration File
Specifying redirection settings in the machine configuration file will cause all applications referencing
the assembly to use the upgraded version. Use this method of redirection carefully, since the
machine configuration file overrides settings in both the application configuration file and the
publisher's policy file.
Creating Applications in Visual Studio
With MapXtreme, it's easy to add a map to your application. Visual Basic.NET and Visual C# project
templates are provided that allow you to create simple mapping applications without writing any
code.
Sample desktop and web applications are also provided for you to review, experiment with and
adapt to your own situation. For a step-by-step tutorial on how to use these sample applications, see
Appendix A: How to Create and Deploy a MapXtreme Application.
MapXtreme also ships with a collection of tutorial applications to help you understand how to include
useful mapping functionality in a web application. Each tutorial application is accompanied by
documentation that explains how the application was built. See Learning Resources from the Start >
Program menu for the documentation. The tutorial applications are included in a single Visual Studio
solution called MapXtremeTutorials.sln, located in the \Tutorials folder of your MapXtreme
installation (default location is c:\Program FIles\MapInfo\MapXtreme\7.x.x.\Tutorials, where 7.x.x is
the release version).
Chapter 2: Getting Started
Creating Applications in Visual Studio
The following procedure outlines the steps to make a simple desktop mapping application. For steps
to create a web application, see ASP.NET Web Applications.
Map Applications
L This example is specific to Visual Basic.NET. To create a Visual C# Map application
substitute Visual C# for Visual Basic in the following steps.
1. From the Visual Studio File menu, select New Project. The New Project dialog box appears.
2. In the Installed Templates frame of the New Project dialog box, under the Visual Basic folder,
choose Windows.
3. In the Templates frame of the New Project dialog box, select MapXtreme 7.x.x MapForm
Application.
MapXtreme v7.1 46 Developer Guide
Chapter 2: Getting Started
Creating Applications in Visual Studio
4. Choose an appropriate name and click OK. MapXtreme creates the application.
Under Solution Explorer double-click MapForm.vb and MapForm.vb [Design] appears.
5. On the Debug menu, click Start Debugging to run the application.
6. Click the Open Table icon and load your data. The default location for sample data is Program
Files\MapInfo\MapXtreme\7.x.x\Samples\Data.
MapXtreme v7.1 47 Developer Guide
Chapter 2: Getting Started
Creating Applications in Visual Studio
7. Use the controls in the toolbar to manipulate the map as you would with any other Pitney Bowes
Software mapping application.
ASP.NET Web Applications
The following procedure outlines the steps to make a simple ASP.NET Web Application using the
MapXtreme 7.1.0 Web Application template. The template is pre-configured for both IIS 6 and IIS 7.
This example is specific to Visual Basic.NET. To create a Visual C# ASP.NET map application
substitute Visual C# for Visual Basic in the following steps.
1. From the Visual Studio File menu, click New Project. The New Project dialog box appears.
2. From the Installed Templates list, choose Visual Basic and Windows. From the available web
templates, choose MapXtreme Classic Web Application or MapXtreme Integrated Web
Application.
3. Set the name of the application and solution and the location for the project. Click OK.
4. Under Solution Explorer double-click MapForm.aspx to see the design view view of the
MapControl and some tools.
MapXtreme v7.1 48 Developer Guide
Chapter 2: Getting Started
Creating Applications in Visual Studio
5. Build the project.
6. On the Visual Studio Debug menu, click Start Debugging to run the application.
7. Use the controls in the toolbar to manipulate the map as you would with any other Pitney Bowes
Software mapping application.
If you are unable to run the application, be sure to check that the ASP.NET State Service is running
on your system (Control Panel > Administrative Tools > Services > ASP.NET State Service).
MapXtreme v7.1 49 Developer Guide
Chapter 2: Getting Started
Building ASP.NET Web Applications Without a Template
MapXtreme Controls
Once you have created a basic application using one of our templates, enhancements are possible
using a variety of MapXtreme controls provided in the Toolbox.
For desktop map applications built using Windows Forms, MapXtreme Windows Controls are
available. Any of the controls found in the MapXtreme Windows Controls tab of the Visual Studio
Toolbox can be added to your form. See Chapter 7: Desktop Applications, Controls, Dialogs,
and Tools.
For MapXtreme ASP.NET web applications, MapXtreme Web Controls are available. Any of the
controls found in the MapXtreme Web Controls tab of the Toolbox, can be added to your form. See
Chapter 5: Web Applications, Controls, and Tools for more information.
Building ASP.NET Web Applications Without a Template
You may also build your ASP.NET map application without using the MapXtreme templates. For
example, to create a Visual Basic web application:
1. Choose File > New Project from the Visual Studio menu. Under Visual Studio Installed
Templates, navigate to the Web section under your preferred programming language. Choose
the generic ASP.NET Web Application template and click OK..
2. From the MapXtreme Web Controls group in the Toolbox, choose a control and drag it onto the
form. This will add MapXtreme assemblies as references in your project: MapInfo.WebControls.
MapInfo.CoreEngine, MapInfo.CoreTypes and MapInfo.CoreEngine.Wrapper. It will also update
your web.config file with assembly information.
MapXtreme v7.1 50 Developer Guide
Chapter 2: Getting Started
Building ASP.NET Web Applications Without a Template
3. In this situation, you will notice that the MapXtreme web controls and tools will display red X’s in
the Designer, instead of their icons. To display the icons properly, copy the
MapXtremeWebResources folder from one of the MapXtreme sample applications and paste it
into your project where your Web.config and default.aspx files are located. Close and re-open
the web page to see the icons.
4. To run the web application under IIS 7 classic mode or IIS 6, copy the following code into the
Web.config file. To run in integrated pipeline mode, skip to step 6.
<system.web>
<compilation debug="true" targetFramework="4.0">
<assemblies>
<add assembly="System.Design, Version=4.0.0.0, Culture=neutral,
PublicKeyToken=B03F5F7F11D50A3A" />
<add assembly="MapInfo.CoreEngine, Version=7.1.0.90,
Culture=neutral, PublicKeyToken=93e298a0f6b95eb1" />
<add assembly="MapInfo.CoreEngine.Wrapper, Version=7.1.0.90,
Culture=neutral, PublicKeyToken=93e298a0f6b95eb1" />
<add assembly="MapInfo.CoreTypes, Version=7.1.0.90,
Culture=neutral, PublicKeyToken=93e298a0f6b95eb1" />
<add assembly="MapInfo.WebControls, Version=7.1.0.90,
Culture=neutral, PublicKeyToken=0a9556cc66c0af57" />
</assemblies>
</compilation>
<sessionState mode="StateServer"
stateConnectionString="tcpip=127.0.0.1:42424"
sqlConnectionString="data source=127.0.0.1;userid=sa;password="
cookieless="false" timeout="20" />
<httpHandlers>
<add verb="*" path="MapController.ashx"
type="MapInfo.WebControls.MapController, MapInfo.WebControls,
Version=7.1.0.90, Culture=neutral, PublicKeyToken=0a9556cc66c0af57" />
</httpHandlers>
<httpModules>
<add type="MapInfo.Engine.WebSessionActivator,
MapInfo.CoreEngine, Version=7.1.0.90, Culture=neutral,
PublicKeyToken=93e298a0f6b95eb1" name="WebSessionActivator" />
</httpModules>
</system.web>
5. Save Web.config. Build the project and run the application.
6. To run the web application under IIS 7 integrated pipeline mode, add the following key in bold
text to the <appSettings> section:
<appSettings>
<!--Use this setting to set config sections for Classic or
Integrated Pipeline Mode-->
<add key="MapInfo.Engine.Session.PipelineMode" value="Integrated"
/>
</appSettings>
Copy the following code into the Web.config file below the
<appSettings> section.
<system.webServer>
MapXtreme v7.1 51 Developer Guide
<modules>
<add name="WebSessionActivator"
type="MapInfo.Engine.WebSessionActivator, MapInfo.CoreEngine,
Version=7.1.0.90, Culture=neutral, PublicKeyToken=93e298a0f6b95eb1" />
</modules>
<handlers>
<add name="MapController" verb="*" path="MapController.ashx"
type="MapInfo.WebControls.MapController, MapInfo.WebControls,
Version=7.1.0.90, Culture=neutral, PublicKeyToken=0a9556cc66c0af57" />
</handlers>
</system.webServer>
7. Save Web.config. Build the project and run the application.
Deploying Your Application
There are essentially two strategies for installing the MapXtreme components on the server machine
where you wish to host your application: either 1) use the included runtime installer or, 2) create your
own installer and add the appropriate merge modules (MSM).
The MapXtreme SDK ships with the MXTRunNCP.exe runtime installer for the NCP version. The
SCP version of the SDK ships with MXTRunSCP.exe.
Chapter 2: Getting Started
Deploying Your Application
Deploying With the Runtime Installer
Use the runtime installer (MXTRunNCP.exe or MXTRunSCP.exe) as part of your custom installation
process. This will install the MapXtreme assemblies and create the needed registry entries. It will
also include the required .NET Framework v4.0. Runtime assemblies and files are included for both
Web and Desktop applications. Additionally, you will need to install your runtime license file which
you get from Pitney Bowes Software or your reseller in the path Program Files\Common
Files\MapInfo\MapXtreme\7.x.x. See Runtime Licenses for Deployment.
For web-based applications, using the runtime installer is the better strategy. All of the runtime
components are installed in their default locations. There are no user-configurable options.
One disadvantage of using the runtime installer executable is that, depending on your application,
unnecessary files may be installed. Additionally, if you expect to install more than one
MapXtreme-enabled application, you will need to maintain your own reference counts when using
the runtime installer. By using the MSMs directly with your own installer, references are maintained
automatically.
Steps for Deploying an Application Using the Runtime Installer
You must have Administrator permissions on the computer in order to run the installer. You also
need IIS permissions to install to the Web server.
1. From the MapXtreme product media, choose Install. The Install options page appears.
2. Choose Deployment Installation and choose Install Runtime Environment. The install wizard
opens.
MapXtreme v7.1 52 Developer Guide
Chapter 2: Getting Started
Deploying Your Application
3. Follow the prompts to proceed with the installation.
4. Deploy your Windows or Web application as you wish (for example, create a deployment project
in Visual Studio and add your application).
5. Install your runtime license file in the path \\Common Files\MapInfo\MapXtreme\7.x.x under
Program FIles or Program Files(x86), depending on whether you are installing the 64-biti or 32bit runtime.
If you wish to run the runtime installer from a command line, follow these instructions. The
executable is located in the [CD root]:\Install\InstallRuntime folder on the product media.
• To run the runtime installer with minimal UI, execute the runtime installer like this:
MXTRunNCP.exe /v"/qb"
• To run the runtime installer silently, execute the runtime installer like this:
MXTRunNCP.exe /v"/qn"
If you are using a software copy protected version of MapXtreme, the runtime executable is called
MXTRunSCP.exe.
Deploying With Your Own Installer
Create your own installer using Windows Installer technology (MSI) and include the MapXtreme
merge modules. A merge module (MSM file) is a single package that contains all files, resources,
registry entries, and setup logic necessary to install a component. Merge modules cannot be
installed alone; they must be assimilated into an MSI file. Use this strategy if you want to fine-tune
exactly which components are installed, or if you want to create your own MSI-based installer.
One disadvantage of using the MSMs is that you will have to create your own patch or updated
installer if Pitney Bowes Software provides updates to this product.
An advantage of using the MSMs is that you control which components get installed and reference
counts are maintained automatically. Assemblies of a particular version will be copied into the Global
Assembly Cache (GAC) only once, and reference counts will be maintained for each application
using those assemblies. If one application is subsequently removed, the reference count (which then
decreases by one) will preserve the assemblies in the GAC. When the last application using those
assemblies is removed, then the assemblies themselves will be removed.
Several developer tools are available to help you create an MSI installer. InstallShield Developer
(Acresso Software Corporation) and Visual Studio (Microsoft) are examples. See the Windows
Installer topic in the Microsoft MSDN library.
MapXtreme v7.1 53 Developer Guide
Chapter 2: Getting Started
Deploying Your Application
MapXtreme Merge Modules
The following are the merge modules for MapXtreme. Include them as necessary in your installer
MSI. See Packaging Your Desktop Application for more information on using merge modules.
Note the 7.x.x in each MSM filename represents the current version of the product. MSMs are
located in \Program Files\Common Files\Merge Modules.
When
Name of Merge Module Included Assemblies Purpose
Required
Custom Symbols
MapInfoCustSymb_7.x.x.msm
Desktop
MapInfoDesktop_7.x.x.msm
Fonts
MIFonts_7.x.x.msm
none Contains custom
symbols
MapInfo.Windows
MapInfo.Windows.Dialogs
MapInfo.Windows.Framework
MapInfo.CommonDialogExt
Contains
assemblies with
.NET controls for
use in C# and VB
.NET desktop
applications
none Contains
MapInfo fonts
such as
Symbols,
Cartographic,
Real Estate,
Arrows,
Miscellaneous,
Oil&Gas,
Transportation,
Weather, and
Shields.
Required
when the
application
expects to
use the
stock
bitmap
symbols
Required
when the
application
uses the
'Desktop'
tools
Required
when the
application
expects to
use the
stock
TrueType
® fonts
MapXtreme v7.1 54 Developer Guide
Chapter 2: Getting Started
Deploying Your Application
Name of Merge Module Included Assemblies Purpose
When
Required
Mapping
MapInfoCoreEngine_7.x.x.msm
MapinfoMXTConfig_7.x.x.msm
MapInfoCoreEngineIntl.msm
*
MapInfoCoreResJPN_7.x.x.msm
†
MapInfoCoreResCHN_7.x.x.msm
Web Controls
MapInfoWeb_7.x.x.msm
MapInfo.CoreEngine
MapInfo.CoreEngine.Wrappe
r
MapInfo.CoreTypes
MapInfo.WMS.Client
MapInfo.Windows.Printing
MapInfo.Ellis.ExtensibleData
‡
Provider
MapInfo.LinearReferencing
MapInfo.Ogc
MapInfo.WorkspaceManager.
Extension
MapInfo.Web
MapInfo.WebControls
Provides the
core mapping
functionality.
They also install
the common
configuration and
default reference
files for these
assemblies.
Installs the.NET
assembly
MapInfo.Web,
and a number of
'web resources'
to be used in
web-based
applications.
Required
Required
for any
application
that uses
the stock
web
controls
It also starts the
ASPNetState
service, and
creates a virtual
directory for the
'web resources'
(if IIS is
installed).
Web Services Clients
MapInfoServices_7.x.x.msm
MapInfo.Services Contains the
assemblies for
geocoding and
routing
Required if
your
application
requires
geocoding
and
routing
MapXtreme v7.1 55 Developer Guide
Chapter 2: Getting Started
Deploying Your Application
Name of Merge Module Included Assemblies Purpose
When
Required
WFS
MapInfo.WFS.Server Contains the
MapInfoWFS_7.x.x.msm
WMS
MapInfo.WMS.Server Contains the
MapInfoWMS_7.x.x.msm
* Include if you are deploying applications built with MapXtreme SCP.
† Include if you are deploying applications built with MapXtreme JPN.
‡ Include if you are deploying applications built with MapXtreme CHN.
assemblies
needed for WFS.
assemblies
needed for
WMS.
Required if
your
application
uses a
Web
Feature
Service for
data
transforma
tion
Required if
your
application
uses a
Web Map
Service for
retrieving
digital
images.
Steps to Deploying an Application With Your Own Installer
Here are the tasks you must do to get MapXtreme to install with your installer:
1. Include the MSMs you need.
By default, Visual Studio and InstallShield look in C:\Program Files\Common Files\Merge
Modules for merge modules to include. This allows you to build installers immediately, without
having to re-configure your development environment.
2. Include your runtime license file.
Deploying a Web Application
If you create your own deployment for a Web application, you will need to add the MSMs manually.
The web setup project does not detect the assemblies that are referenced within the Web.config file;
thus the assemblies (and the corresponding MSMs) are not detected as dependencies. To add the
MSMs manually, right-click on your Web setup project and choose Add>Merge Module. Select
MapInfoCoreEngine_7.x.x, MapInfoMXTConfig_7.x.x, MapInfoWeb_7.x.x and any other MSMs you
need.
MapXtreme v7.1 56 Developer Guide
Chapter 2: Getting Started
Deploying Your Application
Deploying Applications that Access Data
Any Visual Basic or Visual C# application that includes data access has a dependency on Microsoft
Data Access Components (MDAC) version 2.7 or later. MDAC must be installed on a target
computer prior to installing your application or the application will fail.
MapXtreme Web Applications Behind Proxy Servers
If you are deploying your web application behind a proxy server, be sure to add the MapXtreme
Server URL to the proxy server’s bypass cache list. This will allow MapXtreme to deliver dynamic
maps for every request, which it is designed to do.
Proxy servers rely on cached images for display. MapXtreme’s images, however, are built for every
request, so in the case of the web application located behind the proxy server, no images are sent to
the cache. The web application displays a red X in place of the map image.
Permissions to Temp Directory for Deployed Web Applications
For deployed web applications, if you are using integrated security, ensure all users who will access
the site have permissions on the temp directory and any other resources. MapXtreme executes in
the ASP.NET process space and this process executes with the security token passed from the IIS
process. You must grant access to any user who will log in access to this directory. If you are using
anonymous access then you must grant access to the temp directory to the
IUSR_LocalMachineName system account. MapXtreme gets the temp directory from the current
TEMP environment setting.
Application Data Files
Application data files are nonexecutable files used by an application. MapXtreme installs and uses
the following set of application data files. For information about customizing these file locations, see
Location of Application Data Files:
File Type Filename
Abbreviation file MAPINFOW.ABB
Pen file MAPINFOW.PEN
Projection file MapInfoCoordinateSystemSet.xml
Vector symbol file MapInfow.fnt
Custom symbol directory CustSymb
Nadcon files *.las, *.los
jgd2000 files jgd2000.*
MapXtreme v7.1 57 Developer Guide
Chapter 2: Getting Started
Deploying Your Application
By default, MapXtreme applications look in the following directories for data files:
• Program Files\Common Files\MapInfo\MapXtreme\7.x.x—This is the directory the MapXtreme
installer places these files.
• The directory where your application is located. For a Windows application, this is the directory
where the .exe file is located. For web applications, this is the directory where the Web.config file
is located.
Deployment Installation Troubleshooting
Consider the following questions when troubleshooting a deployment installation:
• What was used to deploy the application (for example runtime, SDK, Setup.exe, NCP/SCP?)
• Is the license file located in C:\Program Files\Common Files\MapInfo\MapXtreme\7.x.x?
• Are there additional .lic files on the machine? If so, remove them.
• Is the customer on the deployment machine logged on as the administrator?
• Is the 4.0 Framework installed on the deployment machine?
• Is the CoreEngine registered as a COM+ application on the deployment machine?
• Is the Visual C++ 10.0 CRT (runtime) installed on the machine?
MapXtreme v7.1 58 Developer Guide
Mapping Concepts
Before you create a mapping application, it’s helpful to understand basic
mapping concepts and how these concepts are implemented in MapXtreme.
This chapter discusses the common concepts you will come across as you learn
MapXtreme.
At the end of this Developer Guide, we have provided Appendix L: Glossary
containing mapping and programming terms that you will also find useful.
In this chapter:
Mapping and MapXtreme. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
Geocoding with MapXtreme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64
Routing with MapXtreme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65
3
Mapping and MapXtreme
The central element to a mapping application is the map. This chapter presents a short overview of
the most important mapping terms that you will likely encounter while building your application with
MapXtreme. The introductions also point you to the appropriate namespace in the MapXtreme
object model so that you can quickly get the technical information you need. The topics include:
Maps
Tables
Layers
Features
Labels and Legends
Themes
Tools
Workspaces
Coordinate Systems and Projections
Maps
A map displays the spatial relationship among map features, such as town boundaries, customer
locations, or power lines. The map visually orients you to where those features are and what they
represent. In addition to features, elements on the map can include labels, titles, legends, and
themes. Themes are created based on some action taken involving the features and information on
the map.
Chapter 3: Mapping Concepts
Mapping and MapXtreme
The map is contained in a MapControl. The MapControl also provides basic tools for viewing the
map (pan, zoom in, zoom out, center).
You create a map in a variety of ways:
• Use the MapXtreme Workspace Manager to build and save a map workspace. (See Features of
the Workspace Manager).
• Use a MapXtreme template that provides a MapControl that you are drag and drop onto a Visual
Studio form (See Chapter 7: Desktop Applications, Controls, Dialogs, and Tools for desktop
applications and Chapter 5: Web Applications, Controls, and Tools for web applications.
• Use the MapXtreme Object Model to programmatically build mapping into your application (See
MapFactory and the MapInfo.Mapping namespace in the Developer Reference (online help).
Tables
Tables contain the data you wish to display on the map. Tables hold rows and columns of information
that describe the features, including their geometry, style, and attributes. MapXtreme supports tables
from a wide variety of sources including, native tables (MapInfo .TAB), relational database
management systems (RDBMS), dBase, MS Access, ASCII files, and ESRI ShapeFiles. Speciality
tables include raster, grid, seamless, views, WMS, and ADO.NET. The type of table is available
through the TableInfo class. Tables are opened and closed via the Catalog in the MapInfo.Data
namespace. See Chapter 8: Working with Data.
MapXtreme v7.1 60 Developer Guide
Chapter 3: Mapping Concepts
Mapping and MapXtreme
Layers
Maps are made up of layers. Layers contain map features, such as postal code boundaries, schools,
or streets networks. It is important to understand the order of the layers. The bottommost layer is
drawn first and the topmost layer drawn last. Layers containing features that would obscure the
features of other layers should be placed lower, respectively. For example, a layer of boundary
regions should be placed beneath a layer of points.
Layers in MapXtreme can represent more than features. Layers can be raster or grid images,
seamless maps (joined maps), contain labels or user-drawn features, or contain an object theme,
such as a pie theme. Layers can be grouped for easier positioning and to facilitate animation of their
features. The main interface is IMapLayer. For more information see Layers.
Features
Features are described by their geometry, style, data source, key and attributes. Typically a feature
is a row in a table. Supported geometries include closed objects that cover a given area (Polygons,
MultiPolygons, Rings, Rectangle, RoundedRectangles, and Ellipses); point objects that represent
single locations of data (Points, MultiPoints); and line objects that cover a given distance (Curves,
MultiCurves and LegacyArcs).
One of the main uses of computerized maps is to gather information about the features. In
MapXtreme features are returned in FeatureCollections by any of several methods, either created
from scratch using a schema, selected using selection tools or methods or by searching the Catalog
for those that meet a specific set of criteria.
Feature classes are located in the MapInfo.Data namespace.
Labels and Legends
Maps without elements to describe what is displayed are not very useful. Maps need text such as
labels and legends. Labels have been mentioned above as belonging to a type of layer called a
LabelLayer. This allows you to control every aspect of a label’s visibility, position, style, and content.
MapXtreme classes for working with labels include LabelSource, LabelProperties, and
LabelModifiers. See Introduction to the MapInfo.Mapping Namespace.
MapXtreme v7.1 61 Developer Guide
Chapter 3: Mapping Concepts
Mapping and MapXtreme
Other text elements can also be used in a map to help deliver its message properly. Legends are
cartographic elements that describe the features in a coded manner. For example, the legend may
describe the boundaries as school districts, the lines as a power line network, or points as corporate
office locations. Legends also contain a title to describe collectively what the map represents.
In MapXtreme, legends are part of the Adornments class, along with map titles and scalebars.
Adornments reside in the MapInfo.Mapping namespace.
Themes
Computer maps are not only useful for visibly showing spatial relationships among the map features,
but you can analyze the underlying data that is associated with the features to learn more about
what you see. A common analytical technique is to create a theme based on a feature layer in which
the data is ranked in specific ways. For example, a ranged theme shows color blocks where each
color represents features on the map that meet the same criteria. A graduated symbol theme is
useful for showing distributions of populations for example, with the largest symbol representing the
largest population.
MapXtreme v7.1 62 Developer Guide
Chapter 3: Mapping Concepts
Mapping and MapXtreme
Themes can also be created for labels. For example, use a ranged label theme to show the relative
population size among cities. The largest labels represent the cities with the largest populations.
The MapInfo.Mapping.Thematics namespace contains classes that implement themes as style
overrides on Feature layers and as Object themes. Modifier themes change the style, while object
themes add a new layer. All themes implement the ITheme interface.
Tools
Most mapping applications provide an assortment of toolbar buttons (tools) to aid with common
drawing tasks (such as drawing a line on the map) and navigation tasks (such as zooming in).
MapXtreme provides a number of mapping tools, plus you can also create your own custom tools.
The tools are divided into desktop tools and web tools, the API for each contained in their own
namespace (MapInfo.Tools for desktop and MapInfo.WebControls for web tools.)
For more information on desktop tools in MapXtreme see MapXtreme Desktop Tools API. For
more information on web tools see Chapter 5: Web Applications, Controls, and Tools.
Workspaces
While not strictly a mapping concept, workspaces are included here because they will make working
with all the mapping elements easier. MapXtreme supports an XML-based workspace format that
uses the .MWS extension. In it are all the settings for your maps. The format for the workspace is
explained in Appendix C: Understanding the MapInfo Workspace. MapXtreme provides a utility
called Workspace Manager to help you construct workspaces and save them for later use. See
Chapter 23: Workspace Manager.
Coordinate Systems and Projections
Coordinate systems and projections are two important mapping concepts about which you should
have a basic understanding. Projection refers to how a map is displayed on a flat surface such as a
paper map or computer screen, while a coordinate system describes how map features are spatially
arranged. Both are important considerations when developing applications, especially those where
spatial precision and accuracy are important.
MapXtreme v7.1 63 Developer Guide
A projection is a method of reducing the distortion that occurs when objects from a spherical surface
are displayed on a flat surface. There are two main trade-offs to be considered: the preservation of
equal area, and the preservation of the true shape of a feature. There are many different types of
projections, each designed to reduce the amount of distortion for a given area. Some projections
preserve shape; others preserve accuracy of area, distance, or direction.
A coordinate system is a set of parameters that tells you how to interpret the locational coordinates
for objects. One of those parameters is projection. Coordinates can be of two types: Spherical or
Cartesian. Spherical relates to locations on the curved surface of the Earth, while Cartesian
describes flat surface locations in two dimensions. Both are represented by x and y coordinates. The
difference comes when calculating distance or area of features that represent real Earth locations
such as streets or rivers (Spherical), or relative locations, such as a map of brain anatomy or a chess
board (Cartesian).
Knowing which coordinate system your map uses is an important consideration when developing
applications. Analytical operations involving distance and area calculations, such as buffering,
routing, and querying use the coordinate system and projection to yield the correct results.
Coordinate system and projection classes are part of the MapInfo.Geometry namespace. For more
information see Chapter 16: Spatial Objects and Coordinate Systems.
Geocoding with MapXtreme
Chapter 3: Mapping Concepts
Geocoding with MapXtreme
The maps discussed above all use data that provide additional information beyond what you can see
on the map. For example, a table of store locations not only includes geographic coordinates to
place the stores in the correct map location, it may contain data about the locations, such as store
hours, customer service phone numbers and manager name. This gives the application the power to
analyze and yield information that would otherwise be lost in rows and columns of tables.
Typically a table of custom data is included on a map along with reference layers, such as streets,
town boundaries and water features that represent the true environment of the area. These
references layers are usually purchased ready to display on a map. Pitney Bowes Software sells a
wide variety of reference data for locations around the world. Additionally, MapXtreme provides
more than 400 MB of sample data for world locations. To install, from the MapXtreme product CD
browser, choose Install Sample Data. Use the Custom installation option to install as much of this
data set that you need.
But the custom data, like your store locations or call center regions, may not be ready to display on a
map. The table must contain geographic coordinates so the mapping engine knows where to draw
the objects. The process of assigning coordinates to data is called geocoding. Any table of data that
contains locational information, such as address or postal code, can be geocoded. The process
involves matching the custom table against an already geocoded table covering the same location. If
an address match is made, the coordinates from the geocoded table are assigned to the custom
data. Then the custom data is ready to be viewed on a map.
Geocoding is a typical early step in the process of creating a map. As a developer of mapping
applications, you will need to consider the type of data you wish to display on the map and its need
to be geocoded.
MapXtreme v7.1 64 Developer Guide
The MapXtreme framework provides classes for using a geocoding client that can access Pitney
Bowes Software’s server geocoding products. For more information about geocoding see
Chapter 18: Geocoding and the MapInfo.Geocoding namespace in the online Help (accessible via
Visual Studio).
Routing with MapXtreme
Another component available to developers of MapXtreme is routing. Driving direction applications
and those involved in planning routes for deliveries or laying cable, for example, utilize routing.
Typically the goal is to locate the route by shortest distance or shortest travel time.
MapXtreme provides four types of routing: point-to-point routing, multi-point routing, matrix routing,
and isogram routing. Each type offers numerous options for creating the appropriate routing network
for your needs.
Like the provision for geocoding, MapXtreme allows developers to use a pre-built routing client in
their application that interacts with Pitney Bowes Software’s routing server products. See
Chapter 20: Routing and the MapInfo.Routing namespace in the MapXtreme Online Help.
Chapter 3: Mapping Concepts
Routing with MapXtreme
MapXtreme v7.1 65 Developer Guide
Understanding the
MapXtreme Architecture
This chapter focuses on the design of the MapXtreme architecture so you can
make informed choices for your development needs. Understanding the
architecture of the product will help you to create applications that efficiently use
the features and capabilities of the product.
In this chapter:
MapXtreme Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67
Object Model Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .68
Application Architectures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71
Web Application Architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . .72
Desktop Application Architecture . . . . . . . . . . . . . . . . . . . . . . . . .74
4
MapXtreme Architecture
MapXtreme is built on top of Microsoft’s .NET framework and utilizes the functionality that its
infrastructure includes. This Pitney Bowes Software initiative enables you to leverage the power and
adaptability of developing your applications on the .NET framework. We have also worked hard to
combine the power and ease of our Windows products into one comprehensive object model. The
object model is the basis for Pitney Bowes Software’s partners and customers, as well as Pitney
Bowes Software itself, for developing Windows-based products for the foreseeable future.
With similar code, you can develop an application that can be deployed on either a desktop or the
Web. If you develop an application for the desktop, you can then adjust the application for
subsequent web deployment with only minimal code changes.
The following figure illustrates the MapXtreme architecture. The MapInfo.CoreEngine.dll assembly
and MapInfo.CoreTypes.dll assembly contain most of the core mapping and data access
functionality. On top of the Core Engine are the MapInfo.Windows and MapInfo.Web namespaces
that contain controls, tools, and other functionality specific to each deployment environment. Any
application that gets developed from the MapXtreme object model is built atop of the
MapInfo.Windows or MapInfo.Web namespace.
Chapter 4: Understanding the MapXtreme Architecture
MapXtreme Architecture
MapXtreme Architecture
MapXtreme v7.1 67 Developer Guide
Object Model Overview
The MapXtreme Object Model is made up of many namespaces. A .NET namespace is a type
classification system that differentiates specific classes, methods, and properties from others with
the same name. By utilizing namespaces, .NET developers can avoid collisions between names of
objects and their methods and properties.
MapXtreme ships with a full-color poster of the key interfaces and classes and shows how they
relate to each other via namespace segregation. A PDF version of the poster is viewable from the
Learning Resources page, which is accessible from the Windows Start menu. Specifically, the
Learning Resources page can be accessed from: Start > All Programs > MapInfo > MapXtreme >
Learning Resources.
The list below contains several of the namespaces implemented in the MapXtreme Object Model. A
broad overview of each namespace is included in the following sections. Each description contains a
reference to the part of this manual that contains detailed information about it and its use.
• MapInfo.Data Namespace
• MapInfo.Data.Find Namespace
• MapInfo.Engine Namespace
• MapInfo.Geometry Namespace
• MapInfo.Mapping Namespace
• MapInfo.Persistence Namespace
• MapInfo.Raster Namespace
• MapInfo.Styles Namespace
• MapInfo.WebControls Namespace
• MapInfo.Tools Namespace
• MapInfo.Geocoding Namespace
• MapInfo.Routing Namespace
The complete object model is organized by namespace in the MapXtreme Programmer’s Reference,
which is integrated into Visual Studio.
Chapter 4: Understanding the MapXtreme Architecture
Object Model Overview
If you have used MapX or the non-.NET version of MapXtreme (MapXtreme for Windows v3), be
sure to review Appendix J: Migrating to MapXtreme for a comparison of the two product’s object
models.
MapInfo.Data Namespace
The MapInfo.Data namespace contains the classes and interfaces that implement the MapInfo Data
Provider. The object model has several different classes to access data. Depending on the format in
which your data is stored, there are specific classes to use to access it. Additionally, we now
implement ADO.NET access to any data that is contained in formats not covered by any other class.
For details on the MapInfo.Data namespace, see Chapter 8: Working with Data and Chapter 11:
Accessing Data from a DBMS.
MapXtreme v7.1 68 Developer Guide
Chapter 4: Understanding the MapXtreme Architecture
Object Model Overview
MapInfo.Data.Find Namespace
The MapInfo.Data.Find namespace contains the classes used for searching through data. The
namespace facilitates the search for an object by specifying a mappable table and column (it must
be indexed) on which to perform the search. For details on the MapInfo.Data.Find namespace, see
Chapter 13: Finding Locations.
MapInfo.Engine Namespace
The MapInfo.Engine namespace contains all classes directly related to the core functionality that
drives all applications based on MapXtreme. This includes the core Session class which is the
starting point for all MapXtreme applications. For details on the MapInfo.Engine namespace, see
Chapter 9: Working with Core MapXtreme Classes.
MapInfo.Geometry Namespace
The MapInfo.Geometry namespace is an extensible hierarchy based on OGC (Open GIS
Consortium) standards, coordinate system interoperability, and object processing. The
MapInfo.Geometry namespace contains classes, interfaces, and enumerations for creating and
editing Geometry objects. For details on the MapInfo.Geometry namespace, see Chapter 16:
Spatial Objects and Coordinate Systems.
MapInfo.Mapping Namespace
The MapInfo.Mapping namespace contains classes, interfaces, and enumerations for creating,
displaying, and exporting maps, layers, modifiers, and labels. For details on the MapInfo.Mapping
namespace, see Chapter 12: Adding Mapping Capability to Your Applications.
MapInfo.Mapping.Legends Namespace
The MapInfo.Mapping.Legends namespace contains classes, interfaces, and enumerations for
creating and displaying Cartographic and Thematic Legends. For more information, see Legends
and Using Themes and Legends.
MapInfo.Mapping.Thematics Namespace
The MapInfo.Mapping.Thematics namespace contains classes that implement themes as styles of
layers and as layers themselves. Themes can be applied to Modifier themes to change the style,
while object themes add a new layer. All themes implement the ITheme interface. For details on the
MapInfo.Mapping.Thematics namespace, see Chapter 14: Using Themes and Legends.
MapInfo.Persistence Namespace
The MapInfo.Persistence namespace contains classes that support the reading and writing of XMLbased workspaces to enable the saving and retrieval of mapping workspaces. See Appendix C:
Understanding the MapInfo Workspace.
MapXtreme v7.1 69 Developer Guide
Chapter 4: Understanding the MapXtreme Architecture
Object Model Overview
MapInfo.Raster Namespace
The MapInfo.Raster namespace exposes the full functionality of Pitney Bowes Software’s C/C++
Raster and Grid APIs. Raster images can be opened for querying using
MapInfo.Raster.RasterRead. Grid images can be opened for querying using
MapInfo.Raster.GridRead. Hillshading can be added to existing grids using
MapInfo.Raster.HillshadeWrite. Related classes include MapInfo.Raster.RasterInfo and
MapInfo.Raster.GridInfo. For details on the MapInfo.Raster namespace, see Chapter 17: Working
with Rasters and Grids.
MapInfo.Styles Namespace
The MapInfo.Styles namespace highlights the Styles object model. The Styles class is the base
class of all styles. For details on the MapInfo.Styles namespace, see Chapter 15: Stylizing Your
Maps.
MapInfo.WebControls Namespace
The MapInfo.WebControls namespace provides support for using Visual Studio templates for a
MapXtreme ASP.NET application. There are MapControl and LayerControl design-time
enhancements available from this namespace, as well as web tools. For details on the
MapInfo.WebControls namespaces, see Chapter 5: Web Applications, Controls, and Tools.
MapInfo.Windows Namespace
The MapInfo.Windows namespace contains classes that implement various windows controls and
their requisite components for use with developing forms in Windows applications. The
Windows.Dialogs namespace contains classes that implement various dialog boxes and dialog box
components to be used in Windows applications. For details on the MapInfo.Windows namespace,
see Chapter 7: Desktop Applications, Controls, Dialogs, and Tools.
MapInfo.Tools Namespace
The MapInfo.Tools namespace contains classes for creating and implementing many types of tools
to use in your desktop map application. For details on the MapInfo.Tools namespace, see Overview
of the MapInfo.Tools Namespace.
MapInfo.Geocoding Namespace
The MapInfo.Geocoding namespace contains the classes, interfaces and enumerations that define
the MapXtreme client for geocoding. Geocoding using either the MapInfo geocoding server or the
MapInfo Location Utility service is supported. The URL of a running geocoding server or Location
Utility service must be available in order to perform geocoding. The interface of the geocoding server
and Location Utility service are similar, since they both use the same classes for geocode requests,
constraints, responses, result codes, and input and candidate addresses. See Chapter 18:
Geocoding.
MapXtreme v7.1 70 Developer Guide
MapInfo.Routing Namespace
The MapInfo.Routing namespace contains classes, interfaces, and enumerations which comprise
the .NET client for Routing. The MapInfo.Routing namespace contains classes that support
point-to-point, multi-point, matrix and isogram routing. optimized for shortest time or shortest
distance. It interacts with other MapInfo routing server products. The ability to avoid certain points is
also available. Routing results can include step by step directions and/or a route geometry which
can be displayed on a map. See Chapter 20: Routing.
Application Architectures
Now that you have had an overview of the MapXtreme namespaces, the next step is to consider the
architecture of the application you plan to build.
Using MapXtreme, you can build both web and desktop applications. The follow sections illustrate
possible architectures for web and desktop applications. The designs are based on the Model-ViewController paradigm that separates an application's data model, user interface, and control logic into
three distinct components. This allows for modifications to one component with minimal impact to
the others. Chapter 5: Web Applications, Controls, and Toolsand Chapter 7: Desktop
Applications, Controls, Dialogs, and Tools provides important additional information on key
design elements and decisions you need to consider when planning your MapXtreme application.
Chapter 4: Understanding the MapXtreme Architecture
Application Architectures
MapXtreme v7.1 71 Developer Guide
Web Application Architecture
Chapter 4: Understanding the MapXtreme Architecture
Web Application Architecture
Architecture Description
The Web application illustrated above takes into account the following components and capabilities:
• MapXtreme Web Application
• Microsoft .NET Infrastructure
• Map-building Tools
• Data Access
MapXtreme Web Application
A typical MapXtreme web application contains views (presentation layer), a model (to interact with
data source and application internal data model), and controller (the business logic that controls the
flow of the application).
MapXtreme provides web templates that are integrated into Microsoft Visual Studio to help you
create your initial web application. For a tutorial on building a web application, see Building a Web
Application.
MapXtreme v7.1 72 Developer Guide
Chapter 4: Understanding the MapXtreme Architecture
Web Application Architecture
Build views by dragging and dropping MapXtreme web controls onto a Visual Studio web form. Build
your internal data structures and interact with external data sources, base maps and dynamic
content by using objects under MapInfo.Engine and MapInfo.Data namespaces. Use the controller
code to tie the views and data together and provide the user with an engagement sequence to
effectively use the application to resolve a business need or problem.
Microsoft .NET Infrastructure
MapXtreme runs under Microsoft .NET 2.0 Framework. An application built using MapXtreme runs
as an ASP.NET application under the worker process of IIS.
The Microsoft ASP.NET framework provides COM+ object pooling for developers of high
performance enterprise applications so that objects such as workspaces can be preloaded.
MapXtreme’s object model operates very efficiently under this framework. The framework also
provides application state management tools such as StateServer and SQL Server, as well as
automatic and manual state management control. Chapter 6: Understanding State Management
presents important information on these topics.
Map-building Tools
Use the MapXtreme Workspace Manager to create your application’s base maps. Here you can
manage each layer of a map and control its zoom level, labeling, styles, themes and adornments to
give you exactly the presentation you need for your application. The information is saved to an XMLbased workspace for easy retrieval at a later date. See Chapter 23: Workspace Manager.
Data Access
A key element of this architecture is the ability to access to dynamic data content. Objects that exist
within the MapInfo.Data namespace provide this data access. Data content can come from a
number of sources, such as WMS, WFS, remote database management systems, live feeds from
GPS or driving directions from the MapInfo Routing service. To make the most of disparate data, you
can concurrently use information from different data sources. See Chapter 8: Working with Data.
MapXtreme v7.1 73 Developer Guide
Chapter 4: Understanding the MapXtreme Architecture
Desktop Application Architecture
Desktop Application Architecture
The desktop application architecture is similar to the web application architecture in its Model-ViewController design.
Separate components are used for the presentation layer, application model and business logic. Use
the Workspace Manager to build any base maps that you need. Use Windows controls and dialogs
to give your application a rich user experience. You can also concurrently use dynamic data content
from a variety of sources, and control the flow and logic of the application.
See Chapter 7: Desktop Applications, Controls, Dialogs, and Tools for more information.
MapXtreme v7.1 74 Developer Guide
Web Applications,
Controls, and Tools
This chapter brings together a host of information related to building
ASP.NET web applications using the web controls, tools, and conveniences
provided with MapXtreme.
In this chapter:
Web Application Request/Response Lifecycle . . . . . . . . . . . . . . .76
Components of a MapXtreme Web Application. . . . . . . . . . . . . . .76
MapXtreme Web Controls and Tools . . . . . . . . . . . . . . . . . . . . . . .80
Web Control Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83
Using the MapXtreme Web Controls . . . . . . . . . . . . . . . . . . . . . . .86
Managing Your Web Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87
Creating a Custom Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88
Using and Distributing Custom Web Controls . . . . . . . . . . . . . . .90
Adding an InfoTool to a Web Application . . . . . . . . . . . . . . . . . . .92
ASP.NET AJAX and MapXtreme Web Applications. . . . . . . . . . . .92
MapXtreme Tile Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94
HTML/XHTML Validation Issues . . . . . . . . . . . . . . . . . . . . . . . . . . .98
Migrating Post-back Web Controls to JavaScript Web Controls.99
Specialized Topics for Web Controls . . . . . . . . . . . . . . . . . . . . . .100
5
Chapter 5: Web Applications, Controls, and Tools
Web Application Request/Response Lifecycle
Web Application Request/Response Lifecycle
In order to plan and build an effective web application, you need a solid understanding of the behind
the scenes interactions between the client (browser) and the server (web application). In its simplest
form, a web application is a software application that is accessed through a web browser over an
Internet or intranet connection. The capabilities of the application are presented to a user as an
HTML page, and through user interaction with the elements on the web page, HTTP requests are
sent to a web server for processing. The web server sends back a response that satisfies the user’s
request.
A MapXtreme web application typically presents the user with an image of a map and some tools to
interact with the map. A single request/response cycle could be as simple as the user clicks a ZoomIn tool to display a different view of the map. Behind the scene, the request to zoom in is sent to the
server. The server processes the request and responds with a refreshed image of the map showing
the new view.
For information on the architecture of a MapXtreme web application, see Chapter 4:
Understanding the MapXtreme Architecture.
For a tutorial on building a MapXtreme application, see Appendix A: How to Create and Deploy a
MapXtreme Application.
For a discussion of creating ASP.NET web applications, see ASP.NET Web Application Projects in
the MSDN library.
Components of a MapXtreme Web Application
The following sections cover the major components that make up a typical MapXtreme web
application, including:
• MapXtreme Session
• Background Map
• MapControl
• Map Tools
MapXtreme Session
The MapXtreme Session is the starting point for all MapXtreme applications. It manages the
initialization of resources needed for a MapXtreme application. The MapXtreme Session also
provides access to other important objects such as Catalog, MapFactory, CoordSysFactory,
Selections, and others.
To access the MapXtreme Session, call the MapInfo.Engine.Session.Current() method. Each thread
in your process has a MapXtreme Session object available. There can be only one MapXtreme
Session per thread and this session cannot be shared by multiple threads. See Session Interface.
Web applications can have one MapXtreme Session object per user, or pooled MapXtreme
Sessions available to many users. Both development models are discussed in Chapter 6:
Understanding State Management.
MapXtreme v7.1 76 Developer Guide
Chapter 5: Web Applications, Controls, and Tools
Components of a MapXtreme Web Application
Background Map
The background map, in the form of an image, is the most visual component of a MapXtreme web
application. It provides the user of the application with information about map features and shows
their relationship to other map features. Typically, a background map is made up of reference layers,
such as administrative boundaries, street networks, and points of interest. Custom data related to
the application, such as points representing office locations, cell towers, or ATM machines, are
additional layers. The reference layers and the custom layers do not change based on the user’s
interaction with the application. What typically changes is the display of the map. A user may zoom
into a particular location or create a thematic shading that overlays the map based on criteria the
user submitted in a web request.
The background map is presented to the user in its initial, or "clean" state. This state is an important
consideration when you design a pooled application since your application must handle changes in
user state.
The background map is pre-loaded into the application from an XML-based workspace (.mws). The
workspace is identified in the Web.config file of the application. See What Should the Initial Map
Look Like?. The MapXtreme web template and sample applications provide Web.config files that
include hard-coded paths to sample data. If you base your web application on one of these, be sure
to adjust the path to your own data.
The Workspace Manager utility provided with MapXtreme is an example of a desktop application
that assists you with building a background map. See Chapter 23: Workspace Manager.
MapControl
MapControl is a MapXtreme web server control containing an instance of a Map object. The
MapControl is the main web control in a MapXtreme application; it displays the background map and
responds to tool interactions on the map. Behind the scenes, the Map object is obtained from the
MapFactory using the MapAlias property of the MapControl. The map is rendered and exported as
an image and returned to the browser in the control’s <img> tag.
The sample applications that ship with MapXtreme have a MapControl built in, as does the
MapXtreme Web application template. You will see, however, that in design mode, the map is not
rendered. That is because to get a map from a web MapControl, there must be a running web
application on the server to serve up the map image along with some dynamically generated
javascript. That is only available at run/debug time.
L If you start from a Visual Studio Visual Basic or C# ASP..NET template, you must manually
add the MapControl and tools to your web form in order for the MapXtreme resources to be
included in your project.
For more information, see MapXtreme Web Controls and Tools.
MapXtreme v7.1 77 Developer Guide
Chapter 5: Web Applications, Controls, and Tools
Components of a MapXtreme Web Application
Figure: a MapXtreme Web Application View at Design Time
MapXtreme v7.1 78 Developer Guide
Chapter 5: Web Applications, Controls, and Tools
Components of a MapXtreme Web Application
Figure: a MapXtreme Web Application View at Run Time
Map Tools
MapXtreme provides a number of map tools to assist you in navigating and interacting with the
background map. These tools are contained in the Visual Studio toolbox. Use them by dragging and
dropping the tool onto a web form.
Many of these tools are built into the MapXtreme web application template and sample applications,
including:
• Basic tools for Center, Pan, Zoom-in, and Zoom-out
• ZoomBarTool with pre-set zoom levels between 500 and12,500 map units
• Directional tools (N, NE, E, SE, S, SW, W, NW) for direct line panning in 45-degree increments
The LegendControl, Distance tool and selection tools are located in the MapXtreme portion of the
Visual Studio toolbox.
Tools are discussed in Description of Web Controls and Tools.
A generic WebTool, the base tool for all MapXtreme map tools is also located in the toolbox. Use this
tool if you wish to add custom behaviors to a tool. See Creating a Custom Tool.
MapXtreme v7.1 79 Developer Guide
Chapter 5: Web Applications, Controls, and Tools
State Management and Pooling Capabilities
One of your goals in building a MapXtreme web application is to make it stable, scalable and offer a
satisfying experience for your users. MapXtreme provides configurations to help you manage the
state of your application, and allow it to grow with the numbers of users.
The MapXtreme web application template and the sample applications are configured to manage
state manually. This means that only the changes your users make during their interaction with your
application are saved and restored. You accomplish this by writing code that is specific to your
application and save/restoration needs.
To more efficiently serve the potentially growing number of users of your application, the template
and sample applications are configured to use the Microsoft COM+ pooling service in which
MapXtreme Session objects are available and shared across multiple requests.
State management and pooling need careful consideration when you are planning your web
application. See Chapter 6: Understanding State Management.
MapXtreme Web Controls and Tools
MapXtreme’s web controls and tools are embedded in a web page. Web controls respond to
interactions by web tools. Information that is captured using a tool is processed on the server by the
web page and returned to the client, typically as a new map image.
MapXtreme Web Controls and Tools
MapXtreme provides three web controls (MapControl, LayerControl, and LegendControl) and a
number of map tools. The web controls show content, such as a map, a list of map and label layers
and their properties, or a legend to identify what the layers represent. The tools interact with the
MapControl to change the view of the map, select features on the map for further analysis, and
more. For a description of the web controls and tools see Description of Web Controls and Tools.
The Web controls and tools are available from several places within Visual Studio:
• Visual Studio toolbox under the MapXtreme heading. Drag and drop these controls onto your
Web Form to add mapping functionality to your project.
• Web Application template: Start with the MapXtreme web application template (Visual Studio
File > New Project menu) to build a mapping prototype that requires no coding.
• Sample Applications: Task-oriented samples are located In the \Samples\Visual Studio
20xx\Web\Features folder. Source code is also provided for you to learn from or extend for your
own needs.
The API for Web controls and tools is contained in the MapInfo.WebControls namespace. See the
Developer Reference for more information.
JavaScript-Enabled for Partial-Page Updates
MapXtreme web controls and tools use a combination of a web page and JavaScript to tell the
MapXtreme server what needs to be done. Each map tool specifies a JavaScript ClientInteraction
that defines what must happen (for example, click, draw a rectangle, line, or polygon) and a
JavaScript ClientCommand that sends a URL request to the server to process the command (for
example, pan, zoom, or select an object).
MapXtreme v7.1 80 Developer Guide
Chapter 5: Web Applications, Controls, and Tools
MapXtreme Web Controls and Tools
These JavaScript-enabled tools do not trigger a full page postback with each use. Typically, only the
image of the map is refreshed after each tool use. See Map Tools Architecture for an
understanding of this development model. See Managing Your Web Controls for information on
event handling, error management and state management.
Previous MapXtreme controls (pre-v6.5 releases) required a postback that called Page_Load and
Page_Unload every time a tool was used. These tools are provided for backward compatibility and
are not recommended for new development projects. See Migrating Post-back Web Controls to
JavaScript Web Controls.
Customizable
If the provided tools do not offer you the functionality to meet your needs, consider modifying them.
This can be as simple as changing a built-in tool property or as complicated as writing your own
JavaScript and server-side class to extend its functionality. Source code for the web controls and
tools is provided in the Samples\MapXtremeWebControlsSourceCode folder. See Creating a
Custom Tool.
MapXtreme provides an ASP.NET AJAX sample application that demonstrates how to use
Microsoft's ASP.NET AJAX controls in a MapXtreme web mapping application. See ASP.NET AJAX
and MapXtreme Web Applications.
Description of Web Controls and Tools
The following are the available MapXtreme Web controls and tools.
Web Controls Description
MapControl Allows you to display an instance of a Map object. Each Map object is
referred to by a MapAlias, such as Map1.
At runtime, the MapControl displays the map which is obtained from a
MapFactory by using the map’s MapAlias property. The map is drawn
by exporting the map image, and referencing this image in the HTML
<img> tag. If the MapAlias property is not specified or is invalid, the first
map from the MapFactory is chosen. Set the MapControl MapAlias
property at design time.
LayerControl Allows you to display map feature layers and label layers in a tree view
structure. This control can turn the visibility on or off for a particular layer
and displays a read-only current zoom value. The visibility changes are
persistent only for the active life of the application using the
LayerControl.
MapXtreme v7.1 81 Developer Guide
Chapter 5: Web Applications, Controls, and Tools
MapXtreme Web Controls and Tools
LegendControl The LegendControl allows you to display a legend for a given
MapControl. The legend that is returned is a non-interactive image. The
default export format is .GIF.
The legend to display can be specified at design time using its
LegendAlias or its index in the map's legend list. This can also be set
using JavaScript on the page. JavaScript can also be used to show and
hide the legend. You can arrange for the legend to be scrollable.
Both thematic and cartographic legends are supported in the
LegendControl.
The Legend Control web sample application supports this control. It
demonstrates how to create and use a customized LegendControl
based on our current web control architecture, and how to create a
theme and display a legend by sending requests to the server using
JavaScript without needing to refresh the whole page. For more
information, see the MapXtreme Learning Resources browser on your
Program menu or from the MapInfo website under Support & Training.
Expand the Learning Resources link and click on Sample Applications.
Map Tools
Description
CenterTool Allows you to recenter the map by clicking on the map.
DistanceTool Allows you to get the distance between two or more points by clicking
on the map.
NavigationTools Allow you to pan the map by fixed directions: North, South, East, West,
NorthEast, NorthWest, SouthEast, and SouthWest.
PanTool Allows you to reposition the map within its window by dragging in any
direction.
PointSelectionTool Allows you to select a feature (nearest to the point) when clicked on the
map.
PolygonSelectionTool Allows you to select all features whose centroids lie within the polygon.
The selection area is drawn on the map using mouse clicks
representing the nodes of the polygon. A double click closes/ends the
polygon.
RadiusSelectionTool Allows you to select all features whose centroids lie within the radius.
The radius is drawn on the map using mouse clicks representing the
center and boundary of the circle. The selection radius is drawn on the
map using a click and drag operation.
RectangleSelectionTool Allows you to select all features whose centroids lie within the rectangle.
The rectangle selection area is drawn on the map using a click and drag
operation.
MapXtreme v7.1 82 Developer Guide
Chapter 5: Web Applications, Controls, and Tools
Web Control Architecture
ZoomBarTool Allows you to zoom a map to a series of preset levels between 500 and
12,500 map units.
ZoomInTool Allows you to zoom a map by either a single click or by selecting a
rectangular area
ZoomOutTool Allows you to draw a rectangle representing the view to zoom out of the
map.
InfoTool Sample Web
Application
An example of an InfoTool is included in the sample Web applications. It
demonstrates how to create and use a customized map tool based on
the MapXtreme Web control architecture.
Web Control Architecture
The MapXtreme Web control architecture follows the ASP.NET model for creating Web applications.
The general architecture is a Model-View-Controller (MVC) design pattern, in which the web
application represents the Model, the web page (HTML, JavaScript) represents the View, and the
MapXtreme Server that responds to requests for information represents the Controller.
The user interacts with the web application through web controls and tools that capture data and
send instructions and commands to the server which processes and returns the information.
In MapXtreme, controls and tools are rendered when the web page is rendered at initialization time.
After initialization time, when a tool is used, only the map image is rendered. These JavaScriptenabled tools are an improvement over the pre-v6.5 web controls that performed a full page
postback with every tool operation.
MapXtreme controls provide the following behaviors and functionality:
• A background map is loaded via a pre-defined workspace. At design time, set the MapControl
MapAlias property to the map alias of the map defined in the preloaded workspace. At runtime,
the corresponding map is loaded into the MapControl, ready for users to interact with it using
map tools.
• The first time a page is rendered, Page_Load and Page_Unload are called. Page_Load
initializes the state of the application, either to a default state for a new session, or restores state
if the session is not new. Page_Unload stores the state of any changes, in anticipation of another
request.
• The StateManager is implemented in an application as a class, and an instance of that class is
put in the MapXtreme Session. SaveState and RestoreState methods are called from this object.
The SaveState and RestoreState methods are called every time a tool is used. If Manual mode is
used for state management, a StateManager class instance must be in the session.
(MapInfo.Engine.Session.State is set to Manual in your Web.config file.) For more on state
management, see State Management.
• Error processing is done in the global_asax.cs/.vb file in the application_error event handler. See
Error Management.
• Events are handled through client-side JavaScript commands that send a request to the server.
A server-side command class does server-side processing. See Event Handling.
MapXtreme v7.1 83 Developer Guide
Chapter 5: Web Applications, Controls, and Tools
Web Control Architecture
The MapXtremeWebResources folder included with the Visual Studio MapXtreme Web templates
contains dependencies for the web controls and map tools. Make sure to include these files when
deploying an application.
Map Tools Architecture
MapXtreme map tools are used to interact in some way with the map, such as panning to a different
view or selecting an area of the map to collect data for further analysis. A basic set of navigational
tools are provided in the MapXtreme Web application template. These tools, along with others for
selecting map features and creating a legend, are located in the Visual Studio toolbox.
The map tools are made up of client-side and server-side components. On the client side, the tools
have a JavaScript interaction component and a JavaScript client command component. On the
server side, the tools have server command class component.
The client-side map tool components are responsible for:
• Drawing and mouse operations (for example, rubber band rectangle, mouse click)
• Collecting data from mouse operations (for example, getting the screen coordinates for a zoomin operation)
• Sending the url request to the server
The server-side map tool components are responsible for:
• Carrying out the business logic of the tool (for example, calculating the distance between two
points)
Client Side Map Interaction
The client side map tool interaction is implemented with JavaScript classes. These are generic
classes that can be used by any user interface to perform an interaction on any HTML element. The
base Interaction class, located in Interaction.js, is extended to create all of the individual interactions
such as ClickInteraction and RectInteraction. The constructor for Interaction is:
Interaction(elementID, onComplete)
where elementID is the IMG tag of the map and onComplete is the function which is called
when the interaction is complete.
For example, the Interaction class can a draw a rubber band rectangle over the map and collect all
the point features that are contained within it.
Client Side Command Execution
A map tool has a client side JavaScript command object that is responsible for performing a specific
task. The base Command class, located in Command.js, is extended to create all of the individual
commands such as PanCommand and ZoomCommand. After the map tool interaction is complete,
the tool executes the client command The Command class constructor is:
Command(name, interaction)
where name is the server side Command class name and interaction is the data gathered
during the client interaction.
MapXtreme v7.1 84 Developer Guide
Chapter 5: Web Applications, Controls, and Tools
Web Control Architecture
The client Command generates a URL request that is sent to the server, which then processes the
response to display the new map.
The interaction object can be null. This means there is no client side interaction, such as pan, zoom,
point select, that will fire off the command automatically. The command can still be fired, but it would
have to be done programmatically.
Server Side Command Architecture
On the server, the MapInfo.WebControls.MapControlModel class handles the URL request sent
from the client. This class contains methods for carrying out basic map navigation commands such
as pan and zoom, as well as selection commands for selecting points, polygons, and features within
drawn rectangles and radii. The InvokeCommand method locates the specified tool command and
calls its Execute method. Execute calls the RestoreState, then Process, and then finally SaveState.
To perform commands other than those provided in this class, you must write a Command class that
extends the WebControls.MapBaseCommand class.
How a Map Tool Works
The following describes a typical request/response cycle for a web map tool, in this case, a Zoom-In
tool. You can create custom map tools using this same architecture. See Creating a Custom Tool.
The numbers in the diagram refer to the stages described below.
1. A user draws a rectangle around the general area of Europe displayed in a MapControl using a
Zoom-In tool.
MapXtreme v7.1 85 Developer Guide
Chapter 5: Web Applications, Controls, and Tools
2. The tool’s ClientInteraction property called RectInteraction collects the screen coordinates that
define the rectangle. RectInteraction is defined in Interaction.js.
3. The tool’s ClientCommand property MapCommand creates a URL request and assigns it to the
MapControl’s image.src property. ClientCommand is defined in Command.js. The URL request
looks like:
MapController.ashx?Command=Zoom&Width=300&Height=300&ZoomLevel=1200&Po
ints=1,50,100&MapAlias=Map1
4. The URL request is sent to the server.
5. The MapController receives the request and invokes the MapControlModel. The MapController
derives from System.Web.IHttpHandler.
6. The MapControlModel parses the URL request and invokes the ZoomInCommand class.
7. The ZoomInCommand gets the map from the MapFactory and carries out the operation to zoom
in on the map. The map image is updated to reflect the new view.
8. The map image is exported to an image, and written to the HTTP response as a stream, and
returned to the client.
Using the MapXtreme Web Controls
Using the MapXtreme Web Controls
To use the MapXtreme Web controls in your web application:
1. Do one of the following:
a. Create a MapXtreme web application from Visual Studio File > New Project and choose the
MapXtreme Web Application template. The MapControl, LayerControl and map navigation
tools are built in.
b. Open one of the sample web applications and modify it for your needs.
c. Drag and drop what you need onto the web form from the MapXtreme Web 7.x.x toolbox in
Visual Studio.
d. Create a MapXtreme web application from Visual Studio File > New Project and choose the
1
generic ASP.NET Web Application template
.
2. In your application’s Web.config file, specify the path and name of a workspace that contains
map layers for pre-loading into the MapControl. This is necessary regardless of which choice
you made in step1.
The Web.config file for the template and samples contains a path to the default location of the
installed sample data, as shown below:
<configuration>
<appSettings>
1. In this situation, you will notice that the MapXtreme web controls and tools display red X’s in the Designer
instead of their icons. To display the icons properly, copy the MapXtremeWebResources folder from one of
the MapXtreme sample applications and paste it into your project where your Web.config and default.aspx
files are located. Close and re-open the web page to see the icons. To avoid this manual step. choose
option "a" instead.
MapXtreme v7.1 86 Developer Guide
<add key="MapInfo.Engine.Session.Workspace" value="c:\Program
Files\MapInfo\MapXtreme\7.x.x\Samples\Data\World.mws" />
</appSettings>
</configuration>
If your application requires multiple maps, they can exist in one or more workspaces, each with a
unique MapAlias property. To preload more than one workspace in the Web.config file, use a
semicolon between the full path of each workspace.
3. Make sure that MapAlias property of the MapControl is set. The default MapAlias for the
MapControl in the template is Map1. If this property is not set, MapXtreme will render the first
map from the session which may not be the map you expect.
To determine the MapAlias, open the .mws file in a text editor and look for the MapDefinition
element. The MapAlias is stored as an alias attribute.
You can also find the MapAlias from Workspace Manager. When you hover the mouse pointer
over the map node (top node in the layer list), the alias appears in a ToolTip.
4. Set the MapControlID property for all map tools, LayerControl, LegendControl and custom
controls (if any) to point to the appropriate MapControl.
Managing Your Web Controls
Chapter 5: Web Applications, Controls, and Tools
Managing Your Web Controls
An important part to using Web controls is managing them effectively. This section explains how to
perform:
• Event Handling
• Error Management
• State Management
Event Handling
Map tool events are handled through client-side JavaScript commands that send a request to the
server. On the server-side a command class derived from MapBaseCommand does processing for
the tool.
In many command cases, the result of the server-side processing is sent back to the client. This is
an image in the case of the MapControl or XML in the case of the LayerControl. Then, only a portion
of the web page is updated with the command result via client-side JavaScript (for example, a new
map image is displayed after panning).
Error Management
Error handling in the Web controls can be handled in many ways, and it is very specific to the
application. Therefore, this section only explains one of the ways of handling errors. Since the
response expected by the client side is an image, we can catch the exception using a detailed
message, and send the response back with both an image and an error message. As a result, the
MapControl will now contain the error message.
MapXtreme v7.1 87 Developer Guide
The Global.asax files provided with our sample applications demonstrate an example of handling
application errors. If the application encounters an error while processing a request for a map image,
the Application_Error method creates an image containing an error message, and returns that to the
client.
For more information on Error Management, refer to the MSDN site on error handling with ASP.NET.
State Management
The MapInfo.WebControls.StateManager is an abstract class that includes methods SaveState and
RestoreState. MapXtreme’s map tools call RestoreState and SaveState before and after the
processing, respectively. Since state management is application specific, it is your responsibility to
implement these methods in a concrete class in the application. This allows you to control what gets
restored and saved and how things are restored and saved.
For more information on state management, see Chapter 6: Understanding State Management.
Creating a Custom Tool
To create a custom tool, you can modify or add behavior to a built-in tool or write your own custom
commands and tools.
Chapter 5: Web Applications, Controls, and Tools
Creating a Custom Tool
For example, you may wish to modify a Zoom-In tool to zoom-in and select a feature with one click.
This tool requires a server command class that contains code to zoom-in and perform the selection.
Since we provide the source code for all the server command classes, you can simply modify the
ZoomIn command class to add the selection code.
If our source code does not provide a starting point for your customization, you must write your own
commands and tool classes. The source code is located in your MapXtreme installation under
\Samples\MapXtremeWebControlsSourceCode.
As you plan your customization, keep the following MapXtreme tool architecture in mind. A
MapXtreme map tool consists of:
• A client-side tool class that inherits from MapInfo.WebControls.WebTool.
• Properties on the tool class that control the behavior of the tool, including:
• JavaScript that describes the interaction of the tool with the MapControl (click, draw
rectangle, etc.)
• JavaScript that creates the url request for the tool.
• A server-side command class that is derived from MapInfo.WebControls.MapBaseCommand
that carries out the desired tool behavior.
Properties for the tool are defined either in the class or on the web page. The custom tool is
referenced on the web page by the tool class name.
The code used in the following procedure can be found under the Samples folder under
\Web\Features\CustomTools\CustomToolsCS.
To create a custom tool:
MapXtreme v7.1 88 Developer Guide
Chapter 5: Web Applications, Controls, and Tools
Creating a Custom Tool
1. Drag the generic WebTool from the MapXtreme toolbox onto your web form. You can also use
one of the existing map tools if you want to extend the existing behavior.
2. In the WebTool property page, set the properties for MapControlID, InActive/ActiveImageUrl and
CursorImageUrl.
3. Set the appropriate ClientInteraction property by selecting from the drop-down list.
The built-in interactions include mouse operations for clicking and dragging, drawing lines,
polygons, rectangles and radii, which will cover the needs of most web application. See the
Interaction.js in the MapXtremeWebResources folder in your project.
4. Set the appropriate ClientCommand property by selecting from the drop-down list.
The built-in client commands for mapping, panning, zooming, etc., create the URL request that is
sent to the server. For a description of these commands, see the Command.js in the
MapXtremeWebResources folder in your project.
If one of the built-in commands does not meet your needs, either modify the existing
Command.js or write your own. The custom command takes the name of the interaction from
step 3 as input. See CustomCommand.js in the CustomToolsCS or CustomToolsVB sample for
an example of how to get multiple responses from the server with a single click.
5. Register the JavaScript manually in your .aspx page. Insert the following line within the web
page body.
<script language="javascript" src="CustomCommand.js"
type="text/javascript"></script>
6. Create a new server command class that derives from
MapInfo.WebControls.MapBaseCommand. Include code that carries out the behavior that the
client command requested. Alternatively, you can extend an existing server command class.
7. In the server command class, assign the name of the server command in the constructor.
namespace ToolsSample
{
public class AddPinPointCommand : MapInfo.WebControls.MapBaseCommand
{
/// <summary>
/// Constructor for this command, sets the name of the command
/// </summary>
/// <remarks>None</remarks>
public AddPinPointCommand()
{
Name = "AddPinPointCommand";
}
8. In the server command class, override the Process() method by adding code that carries out the
business logic for the command.
public override void Process()
{
// Your code here.....
}
9. In the Page_Load method of the webform1.aspx, add your server command to the collection of
commands in the MapControlModel.
MapXtreme v7.1 89 Developer Guide
Chapter 5: Web Applications, Controls, and Tools
Using and Distributing Custom Web Controls
MapInfo.WebControls.MapControlModel controlModel =
MapControlModel.SetDefaultModelInSession();
controlModel.Commands.Add(new AddPinPointCommand());
10. Add the tool to the Visual Studio toolbox by creating a new assembly. See Using and
Distributing Custom Web Controls.
11. Drag and drop the custom tool onto the web form and set the properties to the names of the
ClientCommand and ClientInteraction, as set forth in your JavaScript from steps 3and 4.
12. Set the property for the server Command, as defined in step 6.
13. Register the tag prefix in the web form by specifying the assembly and namespace in which this
control exists.
<%@ Register TagPrefix="cc1" Namespace="MapInfo.WebControls"
Assembly="MapInfo.WebControls, Version=4.0.0.476, Culture=neutral,
PublicKeyToken=0a9556cc66c0af57" %>
<%@ Page language="c#" Inherits="ToolsSample.WebForm1"
CodeFile="WebForm1.aspx.cs" %>
<%@ Register TagPrefix="cc2" Namespace="CustomizedWebTools" %>
If the existing behaviors of the WebTool do not meet your needs, you can write your own server
Command class and Javascript to handle client-side commands and interactions. See Adding an
InfoTool to a Web Application for an example.
Using and Distributing Custom Web Controls
Once you have created a custom web tool, you must include it in an assembly so that it is available
in the Visual Studio toolbox or to distribute to others.
MapXtreme provides the source code for our Web controls so you can learn from them, modify
them, and distribute them as you need. The source code for the Web controls is installed in the
\Samples\WebControlsSourceCode folder. In order to use and distribute the modified web controls,
you must create a new assembly and register it in Visual Studio.
Whether you modify the MapXtreme source code or create your own tool class from scratch,
consider the following important factors regarding the MapXtreme web control assembly.
• The assembly name is MapInfo.WebControls.dll and is installed in the global assembly cache.
This assembly has a specific version number which is used by our templates and sample
applications.
• The controls in the assembly are installed in the toolbox in Visual Studio.
• The assembly has references to MapInfo.CoreEngine.dll, MapInfo.CoreEngine.Wrapper.dll and
MapInfo.CoreTypes.dll.
• Resources such as images and scripts are installed in the C:\Program Files\Common
Files\MapInfo\MapXtreme\7.x.x\MapXtremeWebResources folder.
MapXtreme v7.1 90 Developer Guide
Chapter 5: Web Applications, Controls, and Tools
Using and Distributing Custom Web Controls
• The following files are used by the Web controls:
• *.GIF images that represent tool actions (for example, DistanceToolControlActive,
DistanceToolControlInactive).
• *.BMP images that represent tool icons (for example, label, selection arrow)
• JavaScript defining tool interactions and behaviors (Interaction.js, Command.js,
LayerControl.js, LegendControl.js and Tool.js)
• *.CUR (cursor) files that display images when the mouse is used.
Creating a Web Assembly
To create a custom web control assembly:
1. Copy the customized web control source files to another directory so the original is preserved.
2. Remove the original assembly from the global assembly cache and from the Visual Studio
toolbox.
The assemblies are located in C:\Progiram Files\Windows\Assembly\GAC_32 or GAC_64,
depending on if you installed the 32- or 64-bit MapXtreme.
3. Create a strongly named key file (.snk) using sn - k MapInfo.WebControls.snk and copy
this key file to the main project folder (same level as the project files).
4. Change the AssemblyInfo.cs or AssemblyInfo.vb file to reflect the version number of your web
assembly.
5. Open the project in Visual Studio, make any changes you need and build the project. The new
assembly should be in the bin\Release directory so you can distribute the release version of the
assembly.
6. Register your new assembly in the global assembly cache, and in the Visual Studio toolbox using
the following syntax as a model. For more information see Global Assembly Cache Tool.
gacutil /i MapInfo.WebControls.dll
7. Write your application using the new assembly. Drag and drop the new controls onto your form
from the Visual Studio toolbox.
8. In the installer for your Web application, make sure the new assembly is installed in the global
assembly cache. As long as the Web application points to this version of the assembly, it will use
the new controls.
Consider the following scenarios:
• You can insert the Web controls project and resources right into your Web application solution. In
this case, change the URLs for your resources (scripts and images) to begin with the project
root. This prevents you from having to create virtual directories.
• You do not have to use the global assembly cache and a strongly named assembly. You can set
the Copy property for the assembly to true, and have the assembly in the bin folder of your
application.
MapXtreme v7.1 91 Developer Guide
Chapter 5: Web Applications, Controls, and Tools
Adding an InfoTool to a Web Application
Adding an InfoTool to a Web Application
MapXtreme provides a sample application for an InfoTool that can be adapted and used in a web
application. Use this tool to capture information at the point a user clicks on the map and get
information returned from the web application.
Follow these steps to modify the InfoTool sample.
1. Locate the InfoToolCS or InfoToolVB Web Application in the samples folder (default location
C:\Program
Files\MapInfo\MapXtreme\7.x.x\Samples\VisualStudio20xx\Web\Features\InfoTool\InfoToolVB.
2. Copy the following files to your project folder and add them to your project:
• CustomCommand.js from the root of the InfoTool folder
• CustomizedCommands.cs or CustomizedCommands.vb from the \App_Code folder
• stylesheet.css from the root of the InfoTool folder.
3. Add a PointSelect tool to your Web Form and add the code below in the form’s Page_Load
method:
MapInfo.WebControls.MapControlModel controlModel =
MapControlModel.SetDefaultModelInSession();
controlModel.Commands.Add(new CustomWebTools.Info());
4. Match the properties of the PointSelect tool to those of the InfoTool from the sample application.
Set these in the tool’s Properties window.
These properties include: ClientCommand, ClientInteraction, Command, CursorImageURL,
InactiveImageURL. and MapControlID.
5. Switch the form to the HTML view and add the following line after the <form> tag.
<script language="javascript" src="CustomCommand.js"
type="text/javascript"></script>
6. Add a <div> like the one in the sample application to hold the information retrieved by the tool.
<div id="Info" class="infoDiv">
Div element to display selected feature information in
html table.</div>
7. Build the Web Application.
ASP.NET AJAX and MapXtreme Web Applications
MapXtreme’s web controls and tools include JavaScript which provides an efficient
request/response cycle for web applications. Each time a map tool is used, JavaScript interactions
and commands carry out the operation without requiring a full-page postback to the client. Typically,
only the map image is refreshed.
Microsoft’s ASP.NET AJAX technology takes this behavior further, by integrating scripting libraries
with the ASP.NET Framework. The principal controls are the UpdatePanel, a container for server
controls that are frequently refreshed, and the ScriptManager, which manages the scripting activities
for the web page.
MapXtreme v7.1 92 Developer Guide
Chapter 5: Web Applications, Controls, and Tools
ASP.NET AJAX and MapXtreme Web Applications
MapXtreme provides a sample application that demonstrates how to use Microsoft's ASP.NET AJAX
controls in a MapXtreme web mapping application. The sample is located in
..\MapInfo\MapXtreme\7.x.x\Samples\VisualStudio2005\Web\Features.
L The AJAXDemo sample requires that the Microsoft ASP.NET AJAX Extensions 1.0 or later
be installed on your system.
The following section provides the steps to add AJAX controls to your MapXtreme application.
Before proceeding, as an exercise in understanding AJAX, it’s a good idea to create a web
application using the "ASP.NET AJAX-Enabled Web Site" template that is provided with the AJAX
extensions. Examine its Web.config file; the httpHandlers section and the httpModules section
contain settings that you may need to copy into your application.
You should also familiarize yourself with the AJAXDemo sample web application. The steps that
follow refer to JavaScript code and Web.config settings taken from this sample.
Adding ASP.NET AJAX Controls to a MapXtreme Web Application
To add ASP.NET AJAX controls to an existing MapXtreme web application:
1. Open your web form in Visual Studio’s Design mode.
2. From the "AJAX Extensions" section of the Visual Studio Toolbox, drag a ScriptManager control
onto the form. (It does not matter where you place the ScriptManager, as it will not be visible at
run-time.)
3. Drag an AJAX UpdatePanel control onto your form.
4. Move standard controls, such as Button controls, inside the UpdatePanel, to prevent the Button
from causing a full-page update.
L Do not move MapXtreme controls, such as the MapControl or the LayerControl, inside
the UpdatePanel. For a detailed example, see the AJAXDemo sample application.
5. Open your application's Web.config file, and locate the httpHandlers section. Depending on the
contents of your web application, the httpHandlers section might contain just one or two entries one for MapController.ashx, and, if your application contains the LayerControl, one for
LayerController.ashx.
<httpHandlers>
<add verb="*" path="MapController.ashx" . . .
<add verb="*" path="LayerController.ashx" . . .
</httpHandlers>
6. Open the Web.config file from the AJAXDemo sample application, and locate its httpHandlers
section, which contains additional entries needed by ASP.NET AJAX:
<httpHandlers>
<remove verb="*" path="*.asmx"/>
<add verb="*" path="*.asmx" . . .
<add verb="*" path="*_AppService.axd" . . .
MapXtreme v7.1 93 Developer Guide
Chapter 5: Web Applications, Controls, and Tools
MapXtreme Tile Handler
<add verb="GET,HEAD" path="ScriptResource.axd" . . .
<add verb="*" path="MapController.ashx" . . .
<add verb="*" path="LayerController.ashx" . . .
</httpHandlers>
If any of those first four httpHandlers entries are missing from your Web.config file, copy the
missing entries from the AJAXDemo Web.config file, and paste them into your Web.config file. (It
is not necessary to copy the LayerController.ashx entry; if you place the LayerControl on your
page in Designer mode, the LayerController.ashx entry will be generated automatically.)
7. Locate the httpModules section of your Web.config file. The httpModules section probably
already contains one entry, for MapInfo.Engine.WebSessionActivator. Copy the "ScriptModule"
entry from the AJAXDemo Web.config file, so that your httpModules section resembles this:
<httpModules>
<add name="ScriptModule" type="System.Web.Handlers.ScriptModule. . .
<add type="MapInfo.Engine.WebSessionActivator. . .
</httpModules>
If the controls in your UpdatePanel affect the map in some way, you will need to add JavaScript
to the page to force the map image to update. The AJAXDemo sample application contains
sample JavaScript that demonstrates how you can update the map image whenever the
designated UpdatePanels cause a page update.
8. Open the AJAXDemo application's MapForm.aspx page in Source mode. Copy the <script>
block and paste it into your aspx page. NOTE: You must paste the <script> block after the
ScriptManager tag, because the script makes use of objects provided by the ScriptManager.
9. In the <script> block, delete the DisplayEventInfo function and any calls to it. The
DisplayEventInfo function is a debugging tool for the AJAXDemo application; it is not needed in
other applications.
10. If you renamed your UpdatePanel, edit the <script> block to use the new UpdatePanel name.
(The UpdatePanel name is passed as the second parameter to the TargetPanelWasUpdated
function; the default name is "UpdatePanel1".)
11. If you use more than one UpdatePanel in your application, but you do not want all of the
UpdatePanels to affect the map, then you should set each UpdatePanel's UpdateMode property
to Conditional. For details, see the ReadMe file provided with the AJAXDemo sample
application.
For additional details about the Web.config settings required by ASP.NET AJAX extensions, please
consult Microsoft's ASP.NET AJAX documentation.
MapXtreme Tile Handler
MapXtreme provides a REST-based tile handler and public URLs that are used to request map tiles
and information. With a REST-based handler, you can embed all the arguments of your map request
in a single URL.
Map tiles are becoming essential today in web mapping as they can be pre-rendered and stored,
awaiting requests from a user. You can design a tile server that stores base maps as static images
since these do not need to be updated during the user’s session. For dynamically changing data that
MapXtreme v7.1 94 Developer Guide
Chapter 5: Web Applications, Controls, and Tools
MapXtreme Tile Handler
contain information exclusive to the user, such as information returned from a query, these maps are
generated on the fly. Because they are tiled, only the tiles that would be visible in the map window
(based on the tile size, map window size and zoom level) would be returned.
For an example of a web application that takes advantage of the MapXtreme Tile Handler, see the
MapXtreme Tile Handler example located on the MapInfo Developers Code Exchange.
MapXtreme provides support for:
• requesting tiles by their row and column positions in the map
• requesting a list of available maps
• requesting a description of a map
• specifying the cache instructions for better tiling performance
The MapXtreme Tile Handler API is included under the MapInfo.WebControls.Tiling namespace.
See the Developer Reference for details. Source code for the Tile Handler is provided in the
\Samples\WebControlsSourceCode folder.
Using the MapXtreme Tile Handler
In its simplest form, to access the MapXtreme Tile Handler and request map tiles and information
from a tile server:
1. Modify your web.config file to point to the handler, as follows.
<httpHandlers>
<add verb="*" path="TileServer/*"
type="MapInfo.WebControls.Tiling.TileHandler" />
<add verb="*" path="TileServer/*/*"
type="MapInfo.WebControls.Tiling.TileHandler" />
<add verb="*" path="TileServer/*/*/*"
type="MapInfo.WebControls.Tiling.TileHandler" />
<add verb="*" path="TileServer/*/*/*/*"
type="MapInfo.WebControls.Tiling.TileHandler" />
</httpHandlers>
2. Provide a workspace (.MWS) that contains multiple maps.
For example, for a coverage locator application where the user wants to know if their location is
inside or outside your coverage (cell network, trade area, school districts, etc.) include:
• a base map layer to server as a background and reference map.
• an overlay map containing reference points and lines such as point locations and road
networks.
• a coverage layer containing your coverages
3. Request a list of available maps using the following URL format.
http://server/TileServer/maplist.{ext}
where ext is an extension denoting the format of the information returned (current support for
JSON only)
This query will return a JSON object (JavaScript Object Notation) with the following format:
{
[
"Map1Alias",
MapXtreme v7.1 95 Developer Guide
Chapter 5: Web Applications, Controls, and Tools
MapXtreme Tile Handler
"Map2Alias",
"Map3Alias"
]
}
4. Using the listed map names from step 3, request more information about a map using the
following URL format:
http://server/TileServer/{mapname}/description.{ext}
where mapname is the name of the map on the Tile Server to get metadata about. The value is
case-insensitive.
ext is an extension denoting the format of the information returned (current support for JSON
only)
This returns the metadata of a specified map.
{
"numberOfLevels": 20,
"coordSys": "epsg:41001",
"description": "Map of the World",
"name": "World",
"tileWidth": 256,
"tileHeight": 256,
"bounds": {
"minX": -3.756380109844111E7,
"minY": -4.497601034176671E7,
"maxX": 3.773376466605809E7,
"maxY": 4.49763662218225E7
}
"outputTypes":
[
"png"
]
}
5. With information collected from steps 3 and 4, request the map by providing all the necessary
arguments in the URL (explained below):
http://server/webapp/TileServer/{mapname}/{level}/{x;y}/tile.{ext}
For example:
http://<server>/<mywebapp>/TileServer/WorldOverlay/3/0;0/tile.png
This will request the upper left tile of a WorldOverlay map consisting of 64 tiles.
The arguments are explained in the table below.
Argument Description
server Your web server
webapp The name of the web application running on the
server.
MapXtreme v7.1 96 Developer Guide
Chapter 5: Web Applications, Controls, and Tools
MapXtreme Tile Handler
Argument Description
TileServer The path to your instance of the MapTiling handler.
This must match the beginning of the "path" entries
in the "httpHandlers" section of your web.config.
See above.
mapname The name of the map on the Tile Server.
level The level of requested tiles. Zero-based.
x;y The x and y ordinates of the requested tile (zero-
based).
For example, at level 3 the map consists of 64 tiles
in 8 rows and 8 columns. The x and y arguments for
the upper left tile would be 0;0. For the lower left
tile, it would be 0;7.
ext An extension denoting the format of the tile (e.g.,
.gif, png). Must match a supported format.
Caching
The MapXtreme Tile Handler supports caching of frequently used tiles so that application
performance does not suffer. Caching instructions are included in the web.config file following
Microsoft’s.NET Framework HttpCacheability.
Five types of caching (plus a no cache option) are supported. These enumerated values are used to
set the Cache-Control HTTP header.
NoCache Sets the Cache-Control: no-cache header. Without a field name, the
directive applies to the entire request and a shared (proxy server)
cache must force a successful revalidation with the origin Web
server before satisfying the request. With a field name, the directive
applies only to the named field; the rest of the response may be
supplied from a shared cache.
Private Default value. Sets Cache-Control: private to specify that the
response is cacheable only on the client and not by shared (proxy
server) caches.
Public Sets Cache-Control: public to specify that the response is cacheable
by clients and shared (proxy) caches.
MapXtreme v7.1 97 Developer Guide
Chapter 5: Web Applications, Controls, and Tools
HTML/XHTML Validation Issues
Server Specifies that the response is cached only at the origin server.
Similar to the NoCache option. Clients receive a Cache-Control: nocache directive but the document is cached on the origin server.
Equivalent to ServerAndNoCache.
ServerAndNoCache Applies the settings of both Server and NoCache to indicate that the
content is cached at the server but all others are explicitly denied the
ability to cache the response.
ServerAndPrivate Indicates that the response is cached at the server and at the client
but nowhere else. Proxy servers are not allowed to cache the
response.
To specify a cache option, modify your web.config file to point to the key
MapInfo.Engine.Session.Cacheability, as follows.
<appSettings>
<add key="MapInfo.Engine.Session.Cacheability"
value="private"></add>
</appSettings>
Caching Expiration
You can also set an expiration date for your cached tiles. Set an expiration date when the data in the
tile needs to be refreshed. By expiring tiles, users of your application will receive only the most
up-to-date information displayed.
To set the cache expiration, add a key to the web.config file, as follows:
<appSettings>
<add key="MapInfo.Engine.Session.CacheExpires"
value="4/1/2010"></add>
</appSettings>
The value can be any string that can be successfully parsed by Microsoft’s DateTime.Parse(String)
method.
Note that Microsoft limits the expiration date to one year. Any date beyond one year will not be
honored.
HTML/XHTML Validation Issues
If you create a MapXtreme web application and run the resulting HTML through a validator service,
you might see the following validation error, depending on what version DOCTYPE tag you use:
value of attribute "ID" invalid. "_" cannot start name
This validation error is in reference to a hidden field with the attribute
id="__VIEWSTATE"
MapXtreme v7.1 98 Developer Guide
Chapter 5: Web Applications, Controls, and Tools
Migrating Post-back Web Controls to JavaScript Web Controls
The id attribute that causes this validation error is not output by MapXtreme; it is an attribute that is
output by ASP.NET.
To resolve this validation error, you may need to replace the DOCTYPE tag on your .aspx page.
Specifically, if you update your DOCTYPE tag to an XHTML DOCTYPE tag, the resulting page will
validate, even with the id attribute shown above. (ASP.NET will wrap the offending tag in a DIV tag,
all of which will validate against the XHTML DOCTYPE.) As an example, you might use the same
DOCTYPE tag that is generated for you when you create a new Web Application from Visual
Studio's ASP.NET template:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
Migrating Post-back Web Controls to JavaScript Web Controls
The process of migrating your pre-v6.5 Web controls1 to the MapXtreme Web controls in versions
6.6 and higher is not automatic. Every application and migration process is different and depends on
how tightly coupled the application is with the functionality and design of the older Web controls.
The recommended migration process is to take a phased approach. In some cases code
restructuring might have to be done. The following processes need to be considered while migrating
your Web controls:
• Loading Data
• Replacing Controls
• State and Event Management
Loading Data
The only way to load data with MapXtreme Web controls is by using a preloaded workspace. The
MapControl points to the MapAlias in the workspace and tries to display the map, not load the map.
The preloaded workspace is specified in the Web.config file. See What Should the Initial Map
Look Like?.
In the case where the MapControl is used to display multiple map images, set up the data so that all
maps are in one location, and change the MapAlias of the MapControl to choose the maps.
1. In MapXtreme releases prior to version 6.5, the web controls required a postback page that called
Page_Load and Page_Unload every time a tool was used. These controls have been replaced by more
efficient JavaScript-enabled partial-page update controls. We provide the postback controls for backward
compatibility, but they have been marked Obsolete. Information on these controls is contained in the
MapInfo.Web.UI.WebControls namespace. For the JavaScript controls API, see the MapInfo.WebControls
namespace.
MapXtreme v7.1 99 Developer Guide
Chapter 5: Web Applications, Controls, and Tools
Specialized Topics for Web Controls
Replacing Controls
Replacing controls can be done in various ways, either by deleting the older Web controls from the
form and dragging and dropping the new Web controls on the form, or by creating new Web forms,
dragging and dropping the new controls and then start adding functionality from the old forms to the
new forms. Make sure to set the appropriate MapAlias for the MapControl and set the appropriate
MapControlID for all dependent tools and the LayerControl.
State and Event Management
In most cases, the older method of state management is to restore state in Page_Load and save
state in Page_Unload. This code must be moved to the new class which derives from the
StateManager into the RestoreState and SaveState methods.
If your web application handles state manually, then you must implement the StateManager and put
this in the ASP.NET session. It is a best practice with MapXtreme to manually handle state so that
you are only restoring the information needed. See Chapter 6: Understanding State Management.
In the case where Server.Transfer or Response.Redirect is used in a web page, the session is no
longer new. You must put the StateManager in the ASP.NET session if it previously does not exist.
Specialized Topics for Web Controls
The following sections refer to special usage of MapXtreme Web controls:
• Using Web Controls in Frames
• Using the MapControl in Table Cells
• Web Control Localization
Using Web Controls in Frames
The MapXtreme Web controls work in frames. For information on how to create frames, framesets,
and assign pages to frames see the Visual Studio documentation.
When using Web controls in frames, remember that a frame points to a web page and a frameset
contains one or more frames. Take the following scenario: A page with a MapControl and other
pages with tools or a LayerControl that depend upon the MapControl. All of the pages form a
frameset.
Given the above scenario, the following rules apply:
• The MapControlID must be manually entered into the properties for the dependent controls. If
there is a MapControl on the same page as the dependent control with the same ID, the tools
and LayerControl will pick that one.
• Since the frame pages render in a particular order, the MapXtreme session will not be a new
session for frames rendered after the first frame. To ensure the StateManager is in place,
implement the following code. Ensure there is a StateManager class registered regardless of
what page is loaded, The following code is executed before RestoreState is called.
MapXtreme v7.1 100 Developer Guide
Loading...