Envinsa
®
Version 4.1
.NET SDK INSTALL 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 MapInfo Corporation,
One Global View, Troy, New York 12180-8399.
© 2007 MapInfo Corporation. All rights reserved. MapInfo, the MapInfo logo and Envinsa are trademarks of MapInfo Corporation and/or its affiliates.
MapInfo Corporate Headquarters:
Phone: 518 285 6000
Fax: 518 285 6070
Sales: 800 327 8627
Government Sales: 800 619 2333
Technical Support: 518 285 7283
www.mapinfo.com
MapInfo UK and EMEA Headquarters:
Phone: 44 1753 848200
Fax: 44 1753 621140
Technical Support: 44 1753 848229
www.mapinfo.co.uk
MapInfo Asia Pacific Headquarters:
Phone: 61 2 9437 6255
Fax: 61 2 9439 1773
Technical Support: 61 7 3844 7744
www.mapinfo.com.au
Contact information for all MapInfo offices is located at: www.mapinfo.com/contactus.
Adobe Acrobat® is a registered trademark of Adobe Systems Incorporated in the United States.
Products named herein may be trademarks of their respective manufacturers and are hereby recognized. Trademarked names are used editorially, to the benefit of the trademark
owner, with no intent to infringe on the trademark.
February 2007
Table of Contents
Chapter 1: Installing the Envinsa Client SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5
Installing the SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5
Integrating and Using Web Controls in Visual Studio . . . . . . . . . . . . . . . . . . . . . . . . . . .6
Uninstall the Old Envinsa Web Controls in Visual Studio 2003 . . . . . . . . . . . . . . . . . . . .6
Register the Web Controls in Visual Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
Create a New Project and Wire Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
Chapter 2: Installing miTrip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Installing miTrip. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10
Configuring miTrip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10
Using MapInfo Hosted Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10
Using Locally Hosted Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11
Changing miTrip Service Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11
Appendix A: Registering the Web Controls Manually . . . . . . . . . . . . . . . . . . . . . 13
Manually Registering the Web Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14
Installing the Envinsa
Client SDK
Welcome to the Envinsa™ Client Software Development Kit (SDK). This guide
provides instructions for the installation and configuration of the Envinsa .NET
Client SDK, integrating the Web Controls, and installing the miTrip sample
application.
For details on developing applications with the client SDK and the miTrip
sample application, refer to the .NET Client Developer Guide.
In this section:
Š
Š
Š
Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5
Installing the SDK. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5
Integrating and Using Web Controls in Visual Studio . . . . . . . . . .6
1
Chapter 1: Installing the Envinsa Client SDK
Before You Begin
Ensure that the following requirements are met before installing the client SDK:
•
For runtime, you must have either Microsoft .NET Framework version 1.1 or 2.0 installed.
•
For development, it is recommended that you install and use Microsoft Visual Studio® 2003 or
Microsoft Visual Studio® 2005.
Note: Visual Studio is not required to create .NET applications and services, although it is highly
recommended. Developers can download the .NET Framework for free; this download
includes compilers for Visual Basic .NET, Visual C++ .NET, and Visual C# .NET.
Installing the SDK
The client SDK is contained in the zip archive file Envinsa41dotNetSDK.zip. To install the client SDK,
simply unzip the contents of this file to a directory on a filesystem where application development is
to be done. A shared filesystem is recommended if multiple developers are using the client SDK.
The following directories are created when the zip file is unarchived. The SDK_HOME directory is
the root directory where the client SDK zip file has been unarchived.
<SDK_HOME>
index.html
/docs
/lib
/samples
/tools
/WebControls
where:
•
•
•
•
•
•
index.html – The landing page for the client SDK. This page contains links to all of the resources
required to develop applications using the SDK, including links to SDK API documentation, code
samples, applications, and Web controls documentation.
/docs – Documentation for the client SDK, excluding the .NET Client Developer Guide and
service references. These documents can be found at reference.mapinfo.com.
/lib – The Envinsa assembly libraries bundled with the client SDK.
/samples – Code samples and applications for Visual Studio 2003 and 2005 bundled with the
client SDK.
/tools – The TCPMonitor utility (allows you to capture the messages exchanged between the
client and the Envinsa Web Services) and the Web Controls Registration Tool.
/WebControls – The Web controls bundled with the client SDK.
5
.NET SDK Install Guide
© 2007 MapInfo Corporation. All rights reserved.
Integrating and Using Web Controls in Visual Studio
Integrating and Using Web Controls in Visual Studio
Envinsa Web Controls can be integrated into your Visual Studio 2003 or 2005 IDE. The Web
Controls are then available for rapid application development. You can drag and drop the controls
into your application using the Visual Studio designer.
Perform the following steps to use the Envinsa Web Controls:
•
•
•
Uninstall the Old Envinsa Web Controls in Visual Studio 2003
Register the Web Controls in Visual Studio
Create a New Project and Wire Controls
Uninstall the Old Envinsa Web Controls in Visual Studio 2003
Note: Only perform this step if you have the existing Envinsa Web Controls in your Visual Studio
2003 and are updating to the new Envinsa Web Controls.
Unistall the Web Controls in Visual Studio:
1. Start your Visual Studio 2003 application.
2. In the Toolbox, right-click on the EnvinsaWSControls tab and click Delete Tab.
3. Click Yes to remove the Envinsa Web Controls from the toolbox.
The Visual Studio Toolbox should no longer contain the Envinsa Web Controls. You are now ready to
register the new Envinsa Web Controls.
Register the Web Controls in Visual Studio
The Envinsa Web Controls can be registered in both Visual Studio 2003 and 2005. To register the
Web Controls for use in Visual Studio, perform the following steps:
1. Start your Visual Studio 2003 or 2005 application.
2. Launch the Envinsa Web Control registration utility, WebControlsRegistrationTool.exe, found
in the <SDK_HOME>/tools/web_components/ directory.
3. Click the
button. In the Browse For Folder dialog, select your Envinsa .NET SDK root
installation directory (<SDK_HOME>).
4. Select either VS 2003 or VS 2005, representing the version of Visual Studio where you are
registering the Envinsa Web Controls.
5. Click the Register Path button.
6. Check the Envinsa Web Controls you want to register with Visual Studio.
7. Click the Register button. You will be prompted for each of the Web Controls that have been
successfully registered in Visual Studio.
In Visual Studio, the EnvinsaWSControls tab will appear in the Toolbox. If you do not see the
EnvinsaWSControls tab, either select Show All in the Toolbox or open an ASP.NET project.
Note: If you prefer to register the Web Controls manually, refer to Registering the Web Controls
Manually in Appendix A on page 13.
6
Envinsa 4.1
© 2007 MapInfo Corporation. All rights reserved.
Chapter 1: Installing the Envinsa Client SDK
Create a New Project and Wire Controls
To get started using the Web Controls:
1. Create a New ASP.NET project. Make sure your project points to your instance of IIS.
2. Drag-and-drop the Web Controls from the MapInfo tab to create your application.
3. Wire the Envinsa Web Controls so they can communicate with one another. You are required to
wire all of the Web Controls used in your application. The following table provides the list of Web
Controls, the dependant Web Controls required to wire, and the properties used for the wiring:
Web Control
Route Locations
Dependency
Properties
Description
Route
Preferences
RoutePreferenceControlID The Route Preferences
Control identifier.
Mapping
MapControlID
The identifier of the Mapping
Control.
Search
Preferences
FindNearestControlID
FindNearestWebForm
For searching, the
SearchPreferences identifier
and the name of the popup
webform
Route
Instructions
RouteInstructionsControlID The identifier of the Route
Instructions Control.
Mapping
MapControlID
The identifier of the Mapping
Control.
Route Instruction
Mapping
MapControlID
The identifier of the Mapping
Control.
Geocode
Mapping
MapControlID
The identifier of the Mapping
Control.
ZoomInTool
Mapping
MapControlID
The identifier of the Mapping
Control.
ZoomOutTool
Mapping
MapControlID
The identifier of the Mapping
Control.
PanTool
Mapping
MapControlID
The identifier of the Mapping
Control.
MapWidthTool
Mapping
MapControlID
The identifier of the Mapping
Control.
Search Preferences Mapping
MapControlID
The identifier of the Mapping
Control.
Search Results
FindNearestControlID
The identifier of Search
Preferences Control.
Route Preferences
Search
Preferences
7
.NET SDK Install Guide
© 2007 MapInfo Corporation. All rights reserved.
Integrating and Using Web Controls in Visual Studio
4. At this time you may want to modify the envinsa-config.xml file or add other business logic to
your application. The envinsa-config.xml file can be used to configure default service behavior.
This file is located in your applications IIS Web root directory (for example C:/Inetpub/wwwroot/
<my_application>/config).
5. After all Web Controls are wired, rebuild the project.
8
Envinsa 4.1
© 2007 MapInfo Corporation. All rights reserved.
Installing miTrip
Included with the Envinsa client SDK is the miTrip sample application. This
section describes how to install and configure the application
In this section:
Š
Š
Installing miTrip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10
Configuring miTrip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10
2
Installing miTrip
Installing miTrip
To run an application developed using the Web Controls, for example the miTrip sample application,
you must deploy the application with controls in IIS (Internet Information Services) with ASP.NET
enabled.
To install the miTrip sample application:
1. Copy the miTrip directory (<SDK_HOME>/samples/applications/miTrip) to the IIS Web root
directory (for example c:/Inetpub/wwwroot).
2. Add a virtual directory for miTrip under the Default Web Site in IIS. The virtual directory should
have an alias of "miTrip" and point to the path of the miTrip application (for example, C:/Inetpub/
wwwroot/miTrip).
3. Start the Default Web Site if it hasn’t already started.
4. Launch miTrip by pointing your Internet browser to:
http://localhost/miTrip/miTrip.aspx
To develop with miTrip, open the miTrip project file, miTrip.csproj located under the miTrip
application directory, in Visual Studio .NET.
Configuring miTrip
The miTrip sample application can be configured three ways:
•
•
•
Using MapInfo Hosted Services
Using Locally Hosted Services
Changing miTrip Service Preferences
Using MapInfo Hosted Services
The miTrip sample application comes preconfigured after installation, using the MapInfo hosted
Envinsa Web Services located at miplatform.mapinfo.com. To use the hosted services, you require
proper authentication from MapInfo to modify your miTrip configuration with your username and
password.
For miTrip to use the MapInfo hosted services:
1. Obtain your authentication by contacting MapInfo sales for a username and password at
[email protected].
2. Locate the envinsa-config.xml file in the <IIS_Web_ROOT>/miTrip/config directory and adjust
the configuration to add your username and password for all services.
Note: After changing the envinsa-config.xml file, restart IIS.
10
Envinsa 4.1
© 2007 MapInfo Corporation. All rights reserved.
Chapter 2: Installing miTrip
Using Locally Hosted Services
The miTrip sample application can be configured after installation to use your locally hosted Envinsa
Web Services. To use these services, make sure you have proper authentication.
For miTrip to use your locally hosted services:
1. If required, obtain authentication for your locally installed services.
2. Locate the envinsa-config.xml file in the <IIS_Web_ROOT>/miTrip/config directory.
3. If required, adjust the configuration to add your username and password for all services.
4. Adjust the configuration to suit your locally installed services by updating the service URLs.
Note: After changing the envinsa-config.xml file, restart IIS.
Changing miTrip Service Preferences
Each service used by the miTrip sample application is configured with default preferences that
control the behavior of the application and Web Controls.
Note: For a detailed description of service preferences and behavior of the Envinsa Web Services,
refer to the Envinsa service reference guides.
To change the service preferences, locate the envinsa-config.xml file in the <IIS_Web_ROOT>/
miTrip/config directory and modify the appropriate preference.
Note: After changing the service properties, restart IIS.
Directory Service properties:
<Directory url="http://miplatform.mapinfo.com/Directory/services/
Directory" userName="demo" userPassword="demo">
<DirectoryRequest searchDistance="2" distanceUnit="MI"
maxCandidates="5"/>
</Directory>
Location Utility Service properties:
<LocationUtility url="http://miplatform.mapinfo.com/LocationUtility/
services/LocationUtility" userName="demo" userPassword="demo">
<GeocodeRequest closeMatchesOnly="false"/>
</LocationUtility>
Gateway Service properties:
<Gateway version="3.0" url="http://miplatform.mapinfo.com/"
userName="demo" userPassword="demo">
11
.NET SDK Install Guide
© 2007 MapInfo Corporation. All rights reserved.
Configuring miTrip
<GatewayRequest vendor="String" responseType="PERSISTENT"
priority="NORMAL" horizontalAccuracy="3.14159265358979"
distanceUnit="FT"/>
</Gateway>
Presentation Service properties:
<Presentation version="3.0" url="http://miplatform.mapinfo.com/
Presentation/services/Presentation" userName="demo" userPassword="demo">
<PortrayMapRequest basemapName="MapDisplay/Low" zoomFactor="1"
defaultZoom="1" distanceUnit="MI">
<Output width="400" height="300" format="image/png" bgcolor="000000"
transparent="1" content="Data"/>
<Bounds llX="-74.22412255718116" llY="40.58208485212916" urX="73.67474447891242" urY="40.94391807729767"/>
</PortrayMapRequest>
</Presentation>
Route Service properties:
<Route version="3.0" url="http://miplatform.mapinfo.com/Route/services/
Route" userName="demo" userPassword="demo">
<DetermineRouteRequest distanceUnit="FT" timeUnit="HRS"
routeType="Fastest" transport="Driving" returnTurnIcon="base64"
viaPointsOrdered="0">
<RouteGeometry maxPoints="2" provideStartingPortion="1"
provideInstructionsGeometry="1"/>
</DetermineRouteRequest>
</Route>
12
Envinsa 4.1
© 2007 MapInfo Corporation. All rights reserved.
Registering the Web
Controls Manually
This appendix provides information about how to manually register the Web
Controls for use in Visual Studio. The operations described here are done for
you automatically when you use the Web Controls Registration Tool. If you use
the tool to register the Web Controls, you do not need to perform the manual
steps described here.
In this section:
Š
Manually Registering the Web Controls . . . . . . . . . . . . . . . . . . . .14
A
Manually Registering the Web Controls
Manually Registering the Web Controls
Use the following steps to manually register the Web Controls in Visual Studio:
1. In the Windows Registry Editor, add the following new key to the Windows registry:
HKEY_LOCAL_MACHINE\SOFTWARE\MapInfo\Envinsa4.1\Envinsa.NETSDK\EnvinsaInstall
In the new EnvinsaInstall key, add a new string value called EnvinsaInstall, and set this string
value to the full path of your .NET SDK root installation directory. This directory contains all the
resources required by the Web Controls at runtime. Everything under the WebContent
subdirectory will be copied to your ASP.NET application workspace automatically when you drag
and drop a Envinsa Web Control to your Web page at design time.
2. Start Visual Studio and display the Toolbox.
3. Create a MapInfo tab in the Toolbox. Right-click on the new MapInfo tab and choose Add/
Remove Item.
4. Browse to the <SDK_HOME>\WebContols\lib directory and add the following four Web Control
.dll files one at a time to Visual Studio: GeocodingControl.dll, MappingControls.dll,
RoutingControls.dll, and SearchControls.dll.
5. The Envinsa Web Controls now appear in the MapInfo tab of the Toolbox. You can now create a
new ASP.NET project and drag-and-drop the Web Controls from the MapInfo tab.
14
Envinsa 4.1
© 2007 MapInfo Corporation. All rights reserved.