MapXtreme Developer Guide Version 9.4 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 Precisely, 2 Blue Hill Plaza, #1563, Pearl River, NY 10965. © 2004, 2020 Precisely. All rights reserved. Contact and support information is located at: http://support.precisely.com. 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-binx86-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. November 2020 Table of Contents Table of Contents Table of Contents 3 Web Applications 49 Application Data Files 49 Deployment Installation Troubleshooting 50 1 - Introduction to MapXtreme 13 Overview of MapXtreme 14 3 - Mapping Concepts 51 Key Features 15 Mapping and MapXtreme 52 Migrating to MapXtreme 17 Learning to Use MapXtreme 19 Maps 52 Tables 53 Support Resources 19 Layers 53 Features 54 2 - Getting Started 21 Labels and Legends 54 Themes 55 Installation Requirements 22 Tools 56 Minimum System Requirements 23 Workspaces 56 Types of Installations 24 Coordinate Systems and Projections 56 Development (SDK) Installations 24 Geocoding with MapXtreme 57 Deployment (Runtime) Installations 24 Routing with MapXtreme 58 Side-By-Side Installations and Use 24 Before You Install 25 4 - Understanding the MapXtreme Administrator Privileges 25 Architecture 59 Install .NET Framework and Visual Studio First 25 IIS 7/8.5/10 Support 25 MapXtreme Architecture 60 Default Install Directories for MapXtreme 27 Object Model Overview 61 Additional Installation Features 27 MapInfo.Data Namespace 61 Installing MapXtreme in Your Environment 29 MapInfo.Data.Find Namespace 62 Upgrading MapXtreme 32 MapInfo.Engine Namespace 62 MapInfo.Geometry Namespace 62 Migrating Web Sites to 64-bit Web Applications MapInfo.Mapping Namespace 62 33 MapInfo.Mapping.Legends Namespace 62 Updating Existing Web Sites 33 MapInfo.Mapping.Thematics Namespace 63 Updating Existing Desktop Applications 34 MapInfo.Persistence Namespace 63 Creating Applications in Visual Studio 35 MapInfo.Raster Namespace 63 Map Applications 36 MapInfo.Styles Namespace 63 ASP.NET Web Applications 38 MapInfo.WebControls Namespace 63 MapXtreme Controls 40 MapInfo.Windows Namespace 63 Building ASP.NET Web Applications Without a MapInfo.Tools Namespace 64 Template 40 MapInfo.Geocoding Namespace 64 Deploying Your Application 43 MapInfo.Routing Namespace 64 Deploying With the Runtime Installer 43 Application Architectures 64 Deploying With Your Own Installer 44 Web Application Architecture 65 Deploying a Web Application 49 Desktop Application Architecture 67 Deploying Applications that Access Data 49 MapXtreme Web Applications Behind Proxy Servers 49 5 - Web Applications, Controls, and Permissions to Temp Directory for Deployed MapXtreme 9.4 3 Developer Guide MapXtreme 9.4 Developer Guide Tools 69 What is State Management? 106 What State Management Options are Available? Web Application Request/Response Lifecycle 106 70 Questions to Ask Before Writing Your Application 107 Components of a MapXtreme Web Application InProc Development Model 109 70 Pros and Cons of the InProc Development Model MapXtreme Session 70 110 Background Map 71 InProc Management: A Walk-Through 110 MapControl 71 Configuring an Application to Use the InProc Map Tools 73 Development Model 111 State Management and Pooling Capabilities 73 Using the MapXtreme Template with the InProc MapXtreme Web Controls and Tools 74 Development Model 112 Description of Web Controls and Tools 76 State Management For Pooled Objects 113 Web Control Architecture 78 What is Pooling? 113 Map Tools Architecture 79 Pros and Cons of Pooling 114 How a Map Tool Works 81 Saving State for Pooled Applications 114 Using the MapXtreme Web Controls 82 Manual State Management: A Walk-Through Managing Your Web Controls 83 116 Event Handling 83 Configuring a Pooled Application to Use Manual Error Management 84 State Management 117 State Management 84 A Detailed Look at Manual State Management Creating a Custom Tool 84 119 Using and Distributing Custom Web Controls Overview of the Thematics Sample 119 87 Application Settings 120 Creating a Web Assembly 88 Implementing a StateManager 121 Adding an InfoTool to a Web Application 89 Serializing MapXtreme Objects in the Proper ASP.NET AJAX and MapXtreme Web Order 123 Applications 90 Automatically Deserializing MapXtreme Objects Adding ASP.NET AJAX Controls to a MapXtreme 124 Web Application 90 Handling Initial Requests 124 MapXtreme Tile Handler 92 Handling Subsequent Requests 125 Using the MapXtreme Tile Handler 93 A Closer Look at the MapXtreme Session 126 Caching 95 Configuring Microsoft COM+ Object Pooling 126 HTML/XHTML Validation Issues 97 Migrating Post-back Web Controls to 7 - Desktop Applications, Controls, JavaScript Web Controls 98 Dialogs, and Tools 129 Loading Data 98 Replacing Controls 98 Planning a Desktop Application 130 State and Event Management 99 Best Practices for Desktop Applications 130 Specialized Topics for Web Controls 99 MapXtreme and COM 131 Using Web Controls in Frames 99 Sample Applications and Project Templates 131 Using the MapControl in Table Cells 100 MapInfo.Windows.Controls Namespace 132 Web Control Localization 100 Key Controls to Use in Desktop Applications 133 6 - Understanding State Management MapControl 134 103 MapToolStripButtons 135 The MapToolBar 137 Overview 104 Layer Control 139 Terminology 104 MapInfo.Windows.Dialogs Namespace 141 MapXtreme 9.4 4 Developer Guide Table of Contents CreateThemeWizard 142 Feature 204 Customizing Controls and Dialog Boxes 147 Feature Collections 205 Overview of the MapInfo.Tools Namespace Searching for Features 205 147 Catalog Search Methods 206 MapXtreme Desktop Tools API 149 SearchInfo and SearchInfoFactory 207 View Tools 150 Saving Opened Table as GeoJson File 211 Select Tools 150 Analyzing Data 211 Add Tools 151 Improving Data Access Performance 214 Custom Tools 152 Shape Tools 152 9 - Working with Core MapXtreme Distance Map Tool 154 Using InfoTips 154 Classes 215 Customizing Tools 155 Tool Events 156 Session Interface 216 Editing a FeatureGeometry with the Select Tool Session Management 216 157 Using Session.Dispose Method 217 ISessionEventHandlers 218 Reshaping a Feature 158 Adding Nodes 160 Serialization and Persistence 219 Reshaping and Adding Nodes Programmatically Serialization 219 160 Persistence 220 Opening and Saving a Workspace Containing Named Resources 221 8 - Working with Data 163 Opening an MWS: ResolveResource() 222 Saving an MWS: GetResourceName() 222 Overview of MapInfo.Data Namespace 164 Registering Your Implementation with Catalog and Tables 165 MapXtreme 222 Tables 165 Setting Preferences 222 Catalog 170 Selection Class 223 Supported Table Types 172 Using Selection Properties 223 Working with Catalog and Tables 175 Selection Highlighting and Exporting 224 Locating Open Tables 176 SelectionChangedEvent 224 Closing a Table 177 ISerializable Interface on Selection and Packing a Table 177 Selections Classes 224 Listening to Table and Catalog Events 178 Selection Code Examples 225 Table Metadata (TableInfo) 179 Selecting Features Within Another Feature 225 Examining TAB File Metadata 180 Checking a Table for Selections 225 Creating a New Table 181 Returning All Columns From a Table 226 Adding Expression Columns to a Table 183 Changing the Map View Following a Selection Data Sources 185 226 Choosing the Correct Data Source 185 Event Arguments 226 Methods for Accessing Data 186 Exceptions 227 Data Readers, MemTables and Result Sets 187 Using an ADO.NET Data Provider 188 10 - Creating Expressions 229 Data Binding 192 Making Tables Mappable 196 MapInfo ADO.NET Data Provider 199 Expressions Overview 230 MIConnection 199 Creating Expressions 230 MICommand 200 Where Clause – Boolean Expressions 231 MIDataReader 202 Functions In Expressions 232 MapInfo SQL 203 DateTIme and Time Expressions 232 Features and Feature Collections 204 Expression Examples 232 MapXtreme 9.4 5 Developer Guide MapXtreme 9.4 Developer Guide 11 - Accessing Data from a DBMS 237 Your Applications 267 Accessing Remote Spatial Data 238 Introduction to the MapInfo.Mapping Accessing Remote Tables Through a .TAB File Namespace 268 238 Base Mapping Classes 268 Accessing Remote Tables Without a .TAB File MapExport 268 238 Map 269 Mapping DBMS Data with X/Y Columns 239 MapFactory 270 Accessing Data from Oracle 239 MapLoader 270 Geometry Conversion 239 MapViewList, MapView 270 Oracle Support for Z and M Values 241 MapControl 271 SDO_GEOMETRY Arc and