How to use
See How to use ArcGIS samples for help on compiling, setting up the debugger, and running the sample.
Data has been provided for your use with this sample. It can be found at <Your ArcGIS Developer Kit Install directory>/Samples/data/Yellowstone.If the sample has associated data, you will find that the sample's zip file includes a "data" folder alongside the language folders. However, you will need to update the sample to point to the location of the data once you have extracted all the files.
Build the SOE class libraries
- Verify that the Web ADF for the .NET Framework is installed and functioning properly. For information on installing and configuring the Web ADF, consult the installation guide.
- In Windows Explorer, navigate to <ArcGIS install location>\DeveloperKit10.0\Samples\ArcObjectsNET\ServerSpatialQuerySOE. This folder contains CSharp and VBNet folders.
- Go to the folder for the language you are going to use (CSharp or VBNet). Note that there are multiple application directories. The SpatialQuerySOE_<language> directory contains a .NET class library project. This project is used to build a .NET assembly that contains local ArcObjects implementation code associated with the SOE. The SpatialQuerySOE.Interfaces_<language> directory contains a .NET class library project that defines interfaces for interacting with the SOE. The SpatialQuerySOE.ArcCatalog_<language> directory contains a .NET Windows forms project. This project is used to build a form for use in ArcCatalog to edit properties of the SOE. The SpatialQuerySOE.Manager_<language> directory contains a .NET class library project that defines an extension administration page for Manager. The RegisterSOE_<language> directory contains a console application to add the SOE to the ArcGIS Server instance. The SpatialQuerySOE_WebSite_<language> directory contains the ASP.NET Web application that consumes the Component Object Model (COM) object remotely via the SOE in ArcGIS Server.
- Start Microsoft Visual Studio and open the ServerSpatialQuerySOE_<language><version> solution (for example, ServerSpatialQuerySOE_CSharp2008.sln). The solution contains four solution folders, each containing the projects for one of the four parts of the sample. The Implementation folder contains projects that define the SOE logic. The ArcCatalog and Manager Integration folder contains projects that implement property pages for administering the SOE in ArcCatalog and Manager. The Registration folder contains a project that registers the SOE with the SOM via a console application. The Client Application folder contains a Web site that consumes the custom extension.
- On the Build menu, click Build Solution. Four assemblies are created. The SpatialQuerySOE.Interfaces.dll is created in the SpatialQuerySOE.Interfaces_<language>\bin\Debug or the SpatialQuerySOE.Interfaces<language>\bin\Release folder. The SpatialQuerySOE.dll is created in the SpatialQuerySOE_<language>\bin\Debug or the SpatialQuerySOE_<language>\bin\Release folder. The SpatialQuerySOE.ArcCatalog.dll is created in the SpatialQuerySOE.ArcCatalog_<language>\bin\Debug or the SpatialQuerySOE.ArcCatalog_<language>\bin\Release folder. The SpatialQuerySOE.Manager.dll is created in the SpatialQuerySOE.Manager_<language>\bin\Debug or the SpatialQuerySOE.Manager_<language>\bin\Release folder.
Register SOE class and interface libraries
- Open a Visual Studio command prompt and navigate to the location of the SpatialQuerySOE.dll.
- Register the .NET assembly with COM—so that it is available to a COM-aware client such as ArcObjects running in a SOC process (ArcSOC.exe)—using the following command: regasm SpatialQuerySOE.dll /codebase. The regasm utility registers the assembly for use by COM clients. The codebase option registers the explicit location of the assembly and returns a warning indicating that the assembly should be signed. If you sign the assembly, you can place it in the Global Assembly Cache (GAC) and remove the /codebase option when using regasm.
- Register The SpatialQuerySOE.dll on the ArcGIS SOC machines. Confirm that the ArcGIS SOC user account has read and execute access on the directory that contains the registered assembly and type library.
- To unregister the assembly and type library, use the following command: regasm /unregister SpatialQuerySOE.dll.
- Open a Visual Studio command prompt and navigate to the location of the SpatialQuerySOE.Interfaces.dll. This assembly contains interfaces that need to be accessible by a COM-aware client, such as ArcObjects running in a SOC process (ArcSOC.exe). Use the following command to generate a type library referencing these interfaces: regasm SpatialQuerySOE.Interfaces.dll /tlb:SpatialQuerySOE.Interfaces.tlb The regasm tool reads the metadata in an assembly. Since the assembly only contains interface types, a type library must be generated using the /tlb option. The location of the tlb is stored in the registry.
Register ArcCatalog property page
- To create an ArcCatalog form to set properties used by the SOE, open the PropertyPage code file in Microsoft Visual Studio (for example, PropertyPage.cs) and navigate to the PropertyPage constructor. The type of service the SOE is registered with is specified as MapServer, and the name of the SOE is defined as SpatialQuerySOE. This custom ArcCatalog form is linked to the custom SOE via the SOE name, so they must be the same. The custom SOE name is defined when registering with the GIS server using the RegisterSOE_<language> project. In this sample, the feature layer and field to aggregate query values are set when configuring the SOE.
- Open a Visual Studio command prompt and navigate to the location of the SpatialQuerySOE.ArcCatalog.dll.
- Register the .NET assembly with ArcCatalog using the following command: esriregasm SpatialQuerySOE.ArcCatalog.dll /p:Desktop. The esriregasm utility is included the <Program Files>\Common Files\ArcGIS\bin folder.
- Register the SpatialQuerySOE.ArcCatalog.dll assembly and type library on machines where ArcCatalog will be used to configure a service with the custom SOE. Unregister the assembly and type library using the following command: esriregasm SpatialQuerySOE.ArcCatalog.dll /p:Desktop /u
- Follow the steps in the Use ArcCatalog to configure the custom SOE section below to configure the custom SOE in ArcCatalog. Alternatively, you can configure the custom SOE in Manager by following the steps in the Use ArcGIS Server Manager to configure the custom SOE section below. If you have both ArcCatalog and Manager open and use both to administer custom SOEs on the same service, you can encounter locking conflicts that prevent Manager from accessing the service's data. Close ArcCatalog to resolve the conflict.
Register Manager property page
- In Microsoft Visual Studio, right-click the SpatialQuerySOE.Manager_CSharp project and select Properties. The Properties page opens.
- Click the Signing tab.
- Check the Sign the Assembly check box and select New from the drop-down list below the check box. A dialog box opens.
- Type a name for the key file, and, optionally, add a password to protect it.
- Rebuild the SpatialQuerySOE.Manager_CSharp project.
- Open a Visual Studio command prompt and navigate to the location of the SpatialQuerySOE.Manager.dll file.
- At the prompt, use the following command to install the assembly into the GAC: gacutil -i SpatialQuerySOE.Manager.dll.
- To get the PublicKeyToken of the assembly (to update the web.config file in Manager), enter the following command at the Visual Studio command prompt: sn -T SpatialQuerySOE.Manager.dll.
- Open the web.config file for the Manager application. The default location of the file is C:\Inetpub\wwwroot\ArcGIS\Manager\web.config.
- In the Extensions section, add an Extension element to make Manager aware of the extension. The element appears as follows, though the PublicKeyToken will differ: <Extension name="SpatialQuerySOE" DisplayName="Spatial Query" ConfiguratorType="SpatialQuerySOE.Manager.Configurator, SpatialQuerySOE.Manager, Version=184.108.40.206, Culture=neutral, PublicKeyToken=a640acaea98a8392"/>. (Use the PublicKeyToken retrieved in the previous step.)
- Save the web.config file.
- At the Visual Studio command prompt, restart IIS using the following command: iisreset.
- To remove the assembly from the GAC, use the following command: gacutil -u SpatialQuerySOE.Manager.
- Follow the steps in the Use ArcGIS Server Manager to configure the custom SOE section below to configure the custom SOE in Manager.
Register the SOE with ArcGIS Server
- In Microsoft Visual Studio, right-click the RegisterSOE_<language> project and select Set as StartUp Project.
- Press F5 to build the solution and run the console application. A console window displays a message indicating that the SOE was registered with ArcGIS Server. This adds descriptive information about the SOE to the <ArcGIS Install>\server\system\ServerTypesExt.dat file.
- To unregister the extension open the properties for the RegisterSOE_<language> project, click the Debug tab, and type /unregister in the Command Line Arguments text box, and run the application. You can also use the /register flag on the command line in a console window.
Use ArcCatalog to configure the custom SOE
- Start ArcCatalog and open an administrative connection to the ArcGIS Server instance on which the SOE was registered. If you're working with all components on the same machine, use the local machine name or "localhost".
- Add a Map Service named Yellowstone. Use the Yellowstone data provided with the sample data.
- If the service is started, stop it by right-clicking the service and clicking Stop.
- Open the service's Properties dialog box by right-clicking service and selecting Service Properties.
- Click the Capabilities tab.
- Scroll to the bottom of the window in the upper left corner of the dialog box and check the Spatial Query box. The form created in the SpatialQuerySOE.ArcCatalog_<language> project and registered with ArcCatalog opens below the extension list.
- On the form, set the Layer property to Vegetation and the Field property to PRIMARY_.
- Click OK.
Use ArcGIS Server Manager to configure the custom SOE
- Open a Web browser and navigate to the Manager login page.
- Log in as a user with administrative privileges.
- On the left side of the page, click Services, then click the name of the service you want to configure the extension.
- Click the Capabilities tab, scroll to the bottom of the pane in the upper left that lists capabilities, and check the Spatial Query box. The property page created in the SpatialQuerySOE.Manager_<language> project opens to the right of the capabilities list.
- From the drop-down lists, select the layer and field to use.
- If the service is running, click Save. If the service is not running, click Save and Restart.
Build the Web application client
- In Microsoft Visual Studio Solution Explorer, expand the Client Implementation folder, right-click the SpatialQuerySOE_WebSite project, and select Set as StartUp Project.
- Expand the SpatialQuerySOE_WebSite project, right-click Default.aspx, and select Set As Start Page.
- Open the Default.aspx page in Design view, and open the properties window for the MapResourceManager control.
- If not already added, add a reference to the SpatialQuerySOE.Interfaces.dll created earlier. This assembly is only used by the client to work with strong type references to ArcObjects running in server context on the GIS server.
- If necessary, set the run time identity of the Web application by following one of the next two steps. If not necessary, proceed to step 11.
- At design time, the identity of the user running Visual Studio is used to connect to an ArcGIS Server local data source. At run time, that identity is established by the Web application. Only one identity can be used to define access to the ArcGIS Server local data sources in a single Web application. This identity can be explicitly defined when building the Web ADF application in Visual Studio by right-clicking the Web project in Solution Explorer and selecting the Add ArcGIS Identity option. Enter the identity credentials that will be used to access ArcGIS Server local resources at run time. This information is added to the web.config file in a standard ASP.NET identity tag. If the Encrypt identity in web.config check box is checked, the identity tag will be encrypted; otherwise, the username and password are stored as clear text.
- Open the web.config file, add an <identity> element in <system.web>, set the impersonate attribute to true, and add a username and password attribute and set them to a valid user account. If you're working with ArcGIS Server local data sources, ensure the account has access to the GIS server resources referenced in the Map control.
- Save the project.
- Click the Debug drop-down menu and click Start or press F5.
At run time
- Open a browser and navigate to the Web application uniform resource locator (URL) (for example, http://localhost/ServerSpatialQuerySOE_CSharp/SpatialQuerySOE_WebSite_CSharp) or load the Web application solution in Visual Studio.
- Enter a distance in meters to search vegetation regions in the Vegetation layer. The default is 10000.
- Check the Show Summary Results in a Table box to display the summary statistics for the selected regions.
- On the toolbar, click the Vegetation Summary Proximity Search Tool, then click the map. An animated gif indicates that the application is processing.
- When finished processing, a circular region on the map is highlighted along the boundary of the features in the Vegetation layer, and the summary statistics are rendered in a table below the table of contents (TOC).
|SpatialQuerySOE_CSharp\SpatialQuerySOE_CSharp.csproj||COM SOE project.|
|SpatialQuerySOE_CSharp\Extension.cs||Class that implements SOE interfaces and performs the bulk of the fine-grained ArcObjects calls in the GIS server.|
|SpatialQuerySOE_CSharp\Results.cs||Class that stores and packages results to be passed to the client.|
|SpatialQuerySOE.Interfaces_CSharp\SpatialQuerySOE.Interfaces_CSharp.csproj||COM interfaces utilized by the SOE project.|
|SpatialQuerySOE.Interfaces_CSharp\Interfaces.cs||Class file that contains interface definitions implemented by the custom SOE class.|
|SpatialQuerySOE.ArcCatalog_CSharp\SpatialQuerySOE.ArcCatalog_CSharp.csproj||Property page for the ArcCatalog COM class library project.|
|SpatialQuerySOE.ArcCatalog_CSharp\SOEPropertyPage.cs||Abstract class to simplify custom SOE property page implementation. Abstracts away extraneous members from subclasses. Use this class when implementing custom SOE property pages for ArcCatalog.|
|SpatialQuerySOE.ArcCatalog_CSharp\PropertyPage.cs||Business logic for the ArcCatalog custom SOE property page. Inherits from SOEPropertyPage to simplify the implementation.|
|SpatialQuerySOE.ArcCatalog_CSharp\PropertyForm.cs||Defines the user interface for the ArcCatalog property page.|
|SpatialQuerySOE.Manager_CSharp\SpatialQuerySOE.Manager_CSharp.csproj||Contains property page implementation for ArcGIS Server Manager.|
|SpatialQuerySOE.Manager_CSharp\Configurator.cs||Class that defines the custom SOE property page for ArcGIS Server Manager.|
|RegisterSOE_CSharp\RegisterSOE_CSharp.csproj||Project for registering and unregistering the SOE with ArcGIS Server.|
|RegisterSOE_CSharp\Program.cs||Console application to register and unregister the custom SOE with ArcGIS Server.|
|SpatialQuerySOE_WebSite_CSharp\Default.aspx||Contains Web user interface to interact with server-side code.|
|SpatialQuerySOE_WebSite_CSharp\Default.aspx.cs||Code behind the .aspx file. References Web ADF libraries and functionality.|
|SpatialQuerySOE_WebSite_CSharp\App_Code\VegTool.cs||Custom class library associated with a tool in the Web application. Calls the custom SOE in server context and processes the results.|
|SpatialQuerySOE_VBNet\SpatialQuerySOE_VBNet.vbproj||COM SOE project.|
|SpatialQuerySOE_VBNet\Extension.vb||Class that implements SOE interfaces and performs the bulk of the fine-grained ArcObjects calls in the GIS server.|
|SpatialQuerySOE_VBNet\Results.vb||Class that stores and packages results to be passed to the client.|
|SpatialQuerySOE.Interfaces_VBNet\SpatialQuerySOE.Interfaces_VBNet.vbproj||COM interfaces utilized by the SOE project.|
|SpatialQuerySOE.Interfaces_VBNet\Interfaces.vb||Class file that contains interface definitions implemented by the custom SOE class.|
|SpatialQuerySOE.ArcCatalog_VBNet\SpatialQuerySOE.ArcCatalog_VBNet.vbproj||Property page for the ArcCatalog COM class library project.|
|SpatialQuerySOE.ArcCatalog_VBNet\SOEPropertyPage.vb||Abstract class to simplify custom SOE property page implementation. Abstracts away extraneous members from subclasses. Use this class when implementing custom SOE property pages for ArcCatalog.|
|SpatialQuerySOE.ArcCatalog_VBNet\PropertyPage.vb||Business logic for the ArcCatalog custom SOE property page. Inherits from SOEPropertyPage to simplify the implementation.|
|SpatialQuerySOE.ArcCatalog_VBNet\PropertyForm.vb||Defines the user interface for the ArcCatalog property page.|
|SpatialQuerySOE.Manager_VBNet\SpatialQuerySOE.Manager_VBNet.vbproj||Contains property page implementation for ArcGIS Server Manager.|
|SpatialQuerySOE.Manager_VBNet\Configurator.vb||Class that defines the custom SOE property page for ArcGIS Server Manager.|
|RegisterSOE_VBNet\RegisterSOE_VBNet.vbproj||Project for registering and unregistering the SOE with ArcGIS Server.|
|RegisterSOE_VBNet\Program.vb||Console application to register and unregister the custom SOE with ArcGIS Server.|
|SpatialQuerySOE_WebSite_VBNet\Default.aspx||Contains Web user interface to interact with server-side code.|
|SpatialQuerySOE_WebSite_VBNet\Default.aspx.vb||Code behind the .aspx file. References Web ADF libraries and functionality.|
|SpatialQuerySOE_WebSite_VBNet\App_Code\VegTool.vb||Custom class library associated with a tool in the Web application. Calls the custom SOE in server context and processes the results.|
Download the files for all languages