ArcGIS Spatial Query Server Object Extension


Description:

This sample includes a Web application that uses the ArcGIS Server ArcObjects API to access custom functionality on the server to make a series of fine-grained ArcObjects method calls. It does this by extending the GIS server with a server object extension component that exposes a coarse-grained method to perform the bulk of the ArcObjects work within the server. The server object extension is added and managed as part of the server object. If working with ArcCatalog, a property dialog can provide a means for setting values used by the server object extension when the server object is initialized.

This sample is divided into four parts. 1) The server object extension consisting of business logic classes and the implemented interfaces. Both must be registered on the ArcGIS Server SOC machine. 2) Server object extension property pages for use in administering the custom extension. One is for use within the ArcCatalog desktop application and needs to be registered on the same machine as ArcCatalog. The other is for integration with the ArcGIS Server Manager web administration application and must be registered on the machine hosting Manager. 3) A registration console application adds server object extension information to an ArcGIS Server SOM. 4) A .NET Web application to consume the server object extension. The extension interfaces must be registered on the same machine as the client application.

In order to use this sample, you must have the ArcGIS Server Web Application Developer Framework for the Microsoft .NET Framework installed on the Web server machine. You must also have an ArcGIS Server to connect to that has a pooled map server object called Yellowstone that is serving the Yellowstone.mxd map document.

Sample data location: <ArcGIS install location>\DeveloperKit\SamplesNet\Server\data\Yellowstone
Products:
Server: C#

Platforms: Windows

Minimum ArcGIS Release: 9.3.1

How to use:
  1. Design Time:
    1. The instructions assume that the Web ADF and ArcGIS Server are installed on the same machine. Notes will be added to account for distribution of components, where applicable.
    2. 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.
    3. In Windows Explorer, navigate to <ArcGIS install location>\DeveloperKit\SamplesNet\Server\Web_Applications and unzip ArcGIS_Spatial_Query_SOE_CSharp.zip or ArcGIS_Spatial_Query_SOE_VBNet.zip (if available) to a location of your choice. You should see either a CSharp or VBNet folder appear where you unzipped the files.
    4. In Windows Explorer, open the directory referencing the language of your choice: CSharp or VBNet. Copy the ArcGIS_Spatial_Query_SOE_<language>, to c:\inetpub\wwwroot. The <language> variable may be either CSharp or VBNet.
    5. In Windows Explorer, navigate to c:\inetput\wwwroot\ArcGIS_Spatial_Query_SOE_<language>. Note 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 server object extension. The SpatialQuerySOE.Interfaces_<language> contains a .NET class library project that defines interfaces for interacting with the server object extension. 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 server object extension. The SpatialQuerySOE.Manager_<language> directory contains a .NET class library project that defines an extension administration page for ArcGIS Server Manager. The RegisterSOE_<language> directory contains a console application to add the server object extension to the ArcGIS Server instance. The SpatialQuerySOE_WebSite_<language> directory contains the ASP.NET Web application that consumes the COM object remotely via the SOE in ArcGIS Server.
    6. Build and register the server object extension class libraries first:
      1. Launch Microsoft Visual Studio (2005 or 2008) and open the ArcGIS_Spatial_Query_SOE_<language><version> solution (for example, ArcGIS_Spatial_Query_SOE_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 server object extension's logic. The ArcCatalog and Manager Integration folder contains projects that implement property pages for administering the server object extension in ArcCatalog and Manager. The Registration folder contains a project that will register the server object extension with the server object manager via a console application. The Client Application folder contains a website that consumes the custom extension.
      2. Under the Build menu, select the "Build Solution" item. If successful, four assemblies will be created. The SpatialQuerySOE.Interfaces.dll should be created in the SpatialQuerySOE.Interfaces_<language>\bin\Debug or the SpatialQuerySOE.Interfaces<language>\bin\Release folder. The SpatialQuerySOE.dll should be created in the SpatialQuerySOE_<language>\bin\Debug or the SpatialQuerySOE_<language>\bin\Release folder. The SpatialQuerySOE.ArcCatalog.dll should be created in the SpatialQuerySOE.ArcCatalog_<language>\bin\Debug or the SpatialQuerySOE.ArcCatalog_<language>\bin\Release folder. The SpatialQuerySOE.Manager.dll should be created in the SpatialQuerySOE.Manager_<language>\bin\Debug or the SpatialQuerySOE.Manager_<language>\bin\Release folder. First register the server object extension clas libraries - SpatialQuerySOE.dll and SpatialQuerySOE.Interfaces.dll.
      3. Open a Visual Studio 2005 or 2008 command prompt and navigate to the location of the SpatialQuerySOE.dll. To register the .NET assembly with COM, so that it is available to a COM aware client such as ArcObjects running within a server object container (ArcSOC.exe) process, use 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. The codebase option will return a warning indicating that the assembly should be signed. If you choose to sign the assembly, you can also place it in the Global Assembly Cache (GAC) and remove the "/codebase" option when using regasm. To sign the assembly and add it to the GAC, do the following:
        1. Create a strongly named key: 
                                sn -k MyKeyPair.snk
        2. Add or uncomment the following entries to the AssemblyInfo.cs file in the SpatialQuerySOE_<language> project. Change the path for the AssemblyKeyFile attribute to the key created in the previous step. 
                                [assembly: AssemblyDelaySign(false)]
                      [assembly: AssemblyKeyFile("C:/temp/MyKeyPair.snk")]
        3. Build the SpatialQuerySOE_<language> project.
        4. Run the following command: 
                                regasm SpatialQuerySOE.dll
        5. Add the assembly to the GAC: 
                                gacutil -i SpatialQuerySOE.dll
      4. The SpatialQuerySOE.dll should be registered on the ArcGIS Server Object Container (SOC) machines. Make sure that the ArcGIS Server Object Container user account has read/execute access on the directory that contains the registered assembly and type library.
      5. To unregister the assembly and type library, use the following command: 
                            regasm /unregister SpatialQuerySOE.dll
      6. Open a Visual Studio 2005 or 2008 command prompt and navigate to the location of the SpatialQuerySOE.Interfaces.dll. This assembly contains interfaces that will need to be accessible by a COM aware client, such as ArcObjects running within a server object container (ArcSOC.exe) process. Use the following command to generate a register a type library referencing these interfaces (assuming you are working with the CSharp version of the sample): 
                            regasm SpatialQuerySOE.Interfaces.dll /tlb:SpatialQuerySOE.Interfaces.tlb
        The regasm tool reads the metadata within 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.
      7. The SpatialQuerySOE.Interfaces.dll should be registered on the ArcGIS Server Object Container (SOC) machines and any .NET client machines. Make sure that the ArcGIS Server Object Container user account has read/execute access on the registered type library. On the client application machine, make sure the user account that the application is running as has read/execute access to the registered type library.
      8. To unregister the type library, use the following command: 
                            regasm /unregister SpatialQuerySOE.Interfaces.dll /tlb:SpatialQuerySOE.Interfaces.tlb
    7. Create an ArcCatalog form to set properties used by the server object extension. In this case, the feature layer and field to aggregate queries values will be set when configuring the server object extension.
      1. In Microsoft Visual Studio, open the PropertyPage code file (e.g. PropertyPage.cs) and navigate to the PropertyPage constructor. Note that the type of service the SOE is registered with is specified ("MapServer"). The name of the SOE is also defined ("SpatialQuerySOE"). This custom ArcCatalog form is linked to the custom SOE via the SOE name, therefore they must be the same. The custom SOE name is defined when registering with the GIS Server using the RegisterSOE_<language> project (covered below).
      2. Open a Visual Studio 2005 or 2008 command prompt and navigate to the location of the SpatialQuerySOE.ArcCatalog.dll. To register the .NET assembly with COM, so that it is available to a COM aware client such as ArcCatalog, use the following command: 
                            regasm SpatialQuerySOE.ArcCatalog.dll /codebase
      3. The SpatialQuerySOE.ArcCatalog.dll assembly and type library should be registered on machines where ArcCatalog will be used to configure a service with the custom server object extension.
      4. To unregister the assembly and type library, use the following command: 
                            regasm /unregister SpatialQuerySOE.ArcCatalog.dll
    8. Now register a property page for configuring the server object extension in ArcGIS Server Manager. As with the ArcCatalog administration form, this page will allow configuration of the feature layer and field used by the extension. To ensure that Manager loads the custom page properly, the assembly defining the page should be signed and installed into the
      1. In Microsoft Visual Studio, right-click the SpatialQuerySOE.Manager_CSharp project and select Properties.
      2. On the Properties page, select the Signing tab.
      3. Check the Sign the Assembly checkbox and select <New...> from the drop-down list below the checkbox.
      4. On the dialog that appears, choose a name for the key file, and, if desired, add a password to protect it.
      5. Rebuild the SpatialQuerySOE.Manager_CSharp project.
      6. Open a Visual Studio command prompt and navigate to the location of the SpatialQuerySOE.Manager.dll file.
      7. At the prompt, use the following command to install the assembly into the GAC: 
                            gacutil -i SpatialQuerySOE.Manager.dll
      8. You will need to know the PublicKeyToken of the assembly in order to update Manager's web.config file. To retrieve this, enter the following command at the Visual Studio command prompt: 
                            sn -T SpatialQuerySOE.Manager.dll
      9. In Visual Studio, open the web.config file for the ArcGIS Server Manager application. The default location of the file is C:\Inetpub\wwwroot\ArcGIS\Manager\web.config.
      10. In the Extensions section, add an Extension element to make Manager aware of the extension. The element should appear as follows, though the PublicKeyToken will differ. Use the PublicKeyToken retrieved above. 
                            <Extension name="SpatialQuerySOE" DisplayName="Spatial Query" Capabilities="" web="true" ConfiguratorType="SpatialQuerySOE.Manager.Configurator, SpatialQuerySOE.Manager, Version=1.0.0.0, Culture=neutral, PublicKeyToken=a640acaea98a8392"/>
      11. In the ServerObjectTypes section, find the MapServer ServerObjectType. Since SpatialQuerySOE extends MapServer, you need to add it to the Extensions attribute. The modified element will look similar to the following. Note the extensions listed may differ from those below, as this depends on which extensions you have installed: 
                            <ServerObjectType name="MapServer" Extensions="MapServer,WCSServer,WMSServer,WFSServer,MobileServer,KmlServer,NAServer,SpatialQuerySOE" FileExtensions=".mxd;.pmf;.msd"/>
      12. Save the web.config file.
      13. At the Visual Studio command prompt, restart IIS using the following command: 
        iisreset
      14. To remove the assembly from the GAC, use the following command: 
                            gacutil -u SpatialQuerySOE.Manager
    9. Register the server object extension with the ArcGIS Server SOM (Server Object Manager). To work with the RegisterSOE_<language> console application project, do the following:
      1. In Microsoft Visual Studio right-click on the RegisterSOE_<language> project and select Set as StartUp Project.
      2. Press F5 to build the solution and run the console application. If successful, a console window will display a message indicating the server object extension was registered with ArcGIS Server. This will add descriptive information about the server object extension to the <ArcGIS Install>\server\system\ServerTypesExt.dat file.
      3. The console application can also be used to unregister the extension by adding a command line argument of /unregister. To do this:
        1. Open the properties for the RegisterSOE_<language> project.
        2. Click the debug tab.
        3. In the Command Line Arguments textbox, type: 
          /unregister
        4. Run the application.
    10. Now you can use ArcCatalog to configure the custom server object extension. To do this:
      1. Start ArcCatalog and open an administrative connection to the ArcGIS Server instance on which the server object extension was registered. If you're working with all components on the same machine, use the local machine name or "localhost".
      2. Add a new Map Service named "Yellowstone". Use the Yellowstone data provided with the sample data (location specified in instructions above).
      3. If the service is started, stop it by right-clicking on the service and selecting Stop.
      4. Open the service's properties dialog by right-clicking on the service and selecting Service Properties.
      5. Click the Capabilities tab.
      6. On the tab, note the window with checkboxes and server extension names in the upper left corner of the dialog. Scroll to the bottom of the window and check the box next to Spatial Query. The form created in the SpatialQuerySOE.ArcCatalog_<language> project and registered with ArcCatalog should display below the extension list.
      7. On the form, set the Layer property to "Vegetation" and the Field property to "PRIMARY_".
      8. Click OK.
    11. Alternatively, you can use ArcGIS Server Manager to configure the server object extension. To do so:
      1. Open a web browser and navigate to the Manager login page.
      2. Login as a user with administrative privileges.
      3. Along the left-hand side of the page, click Services.
      4. From the list of services that appears, click the name of the service for which to configure the extension.
      5. Click the Capabilities tab.
      6. On the Capabilities tab, scroll to the bottom of the pane in the upper left that lists capabilities.
      7. Check the box next to Spatial Query.
      8. The property page created in the SpatialQuerySOE.Manager_<language> project should appear to the right of the capabilities list. From the drop-down lists, select the Layer and Field to use.
      9. Click the Save or Save and Restart button. Which button appears depends on whether the service is currently running.
    12. Note that, if you have both ArcCatalog and Manager open and use both to administer custom server object extensions on the same service, you may encounter locking conflicts that prevent Manager from accessing the service's data. You may have to close ArcCatalog to resolve the conflict.
    13. Consume the server object extension in a Web ADF application. To work with the SpatialQuerySOE_WebSite_<language> Web application project, do the following:
      1. Open the IIS Manager from Control Panel > Administrative Tools > Internet Information Services (IIS) Manager or Internet Information Services
      2. In the console tree view on the left, navigate to Local Computer > Web Sites > Default Web Site.
      3. Expand Default Web Site. Under ArcGIS_Spatial_Query_SOE_<language> right-click the SpatialQuerySOE_WebSite_<language> folder and click Properties.
      4. On the Directory tab, click the Create button in the Application Settings section of this panel. Click OK to dismiss the Properties dialog.
      5. In Microsoft Visual Studio's Solution Explorer, expand the Client Implementation folder. Right-click the SpatialQuerySOE_WebSite project and select Set as StartUp Project.
      6. Expand the SpatialQuerySOE_WebSite project, right-click Default.aspx, and select 'Set As Start Page'.
      7. Open the Default.aspx page in design view. Open the properties window for the MapResourceManager control.
      8. 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).
      9. If necessary, set the runtime identity of the Web application:
        1. At design-time, the identity of the user running Visual Studio is used to connect to an ArcGIS Server local data source. At runtime, that identity is established by the Web application. Only one identity can be used to define access to all 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 which will be used to access ArcGIS Server local resources at runtime. This information will be added to the web.config file within a standard ASP.NET identity tag. If the "Encrypt identity in web.config" checkbox is checked, the identity tag will be encrypted, otherwise the username and password will be stored as clear text.
          -or-
        2. Open the web.config file and add an <identity> element within <system.web>. Set the impersonate attribute to "true". Add a userName and password attribute and set them to a valid user account. If working with ArcGIS Server Local data sources, make sure the account has access to the GIS Server resources referenced in the Map control.
    14. Save the project.
    15. Click the "Debug" drop-down menu and choose "Start" or press F5.
  2. Run time:
    1. Open a browser and navigate to the Web application URL (for example, http://localhost/ArcGIS_Spatial_Query_SOE_CSharp/SpatialQuerySOE_WebSite_CSharp) -or- load the Web application solution within Visual Studio 2005.
    2. Enter a distance in meters to search vegetation regions within the Vegetation layer. The default is 10000.
    3. To display the summary statistics for the selected regions, check the box next to "Show Summary Results in a Table".
    4. In the toolbar, click on the tool "Vegetation Summary Proximity Search Tool".
    5. Click on the map. Note that an animated gif is used to indicate that the application is processing.
    6. When finished, a circular region in the map should be highlighted along the boundary of the features in the Vegetation layer. The summary statistics should be rendered in a table below the Toc.

Download the C# files
SpatialQuerySOE_CSharp.csproj COM SOE project.
ArcGIS_Spatial_Query_SOE_CSharp/SpatialQuerySOE_CSharp/Extension.cs
(view code)
Class that implements server object extension interfaces and performs the bulk of the fine-grained ArcObjects calls within the GIS Server.
ArcGIS_Spatial_Query_SOE_CSharp/SpatialQuerySOE_CSharp/Results.cs
(view code)
A class designed to store and package results to be passed to the client.
SpatialQuerySOE.Interfaces.csproj COM interfaces utilized by the SOE project.
ArcGIS_Spatial_Query_SOE_CSharp/SpatialQuerySOE.Interfaces_CSharp/Interfaces.cs
(view code)
Class file that contains interface definitions implemented by the custom SOE class.
SpatialQuerySOE.ArcCatalog.csproj Property page for ArcCatalog, COM class library project.
ArcGIS_Spatial_Query_SOE_CSharp/SpatialQuerySOE.ArcCatalog_CSharp/SOEPropertyPage.cs
(view code)
Abstract class to simplify custom SOE property page implementation. Abstracts away extraneous members from sub-classes. Use this class when implementing custom SOE property pages for ArcCatalog
ArcGIS_Spatial_Query_SOE_CSharp/SpatialQuerySOE.ArcCatalog_CSharp/PropertyPage.cs
(view code)
Business logic for the ArcCatalog custom SOE property page. Inherits from SOEPropertyPage to simplify the implementation.
ArcGIS_Spatial_Query_SOE_CSharp/SpatialQuerySOE.ArcCatalog_CSharp/PropertyForm.cs
(view code)
Defines the UI for the ArcCatalog property page.
SpatialQuerySOE.Manager.csproj Contains property page implementation for ArcGIS Server Manager.
ArcGIS_Spatial_Query_SOE_CSharp/SpatialQuerySOE.Manager_CSharp/Configurator.cs
(view code)
Class that defines the custom SOE property page for Manager.
RegisterSOE_CSharp.csproj Project for registering and unregistering the SOE with ArcGIS Server.
ArcGIS_Spatial_Query_SOE_CSharp/RegisterSOE_CSharp/Program.cs
(view code)
Console application to register and unregister the custom SOE with ArcGIS Server.
ArcGIS_Spatial_Query_SOE_CSharp/SpatialQuerySOE_WebSite_CSharp/Default.aspx
(view code)
Contains Web user interface to interact with server-side code.
ArcGIS_Spatial_Query_SOE_CSharp/SpatialQuerySOE_WebSite_CSharp/Default.aspx.cs
(view code)
Code behind the aspx file. References Web ADF libraries and functionality.
ArcGIS_Spatial_Query_SOE_CSharp/SpatialQuerySOE_WebSite_CSharp/App_Code/VegTool.cs
(view code)
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