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) The server object extension property dialog is designed to be used in ArcCatalog when administering the custom extension. It is registered on the same machine as ArcCatalog. 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.2

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_SOECSharp.zip or ArcGIS_Spatial_Query_SOEVBNet.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 VegSOE<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 VegSOEProps<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 RegisterSOE project contains a console application to add the server object extension to the ArcGIS Server instance. The VegSOEWebApp<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 and open the VegSOE<language> solution (for example, VegSOECSharp.sln). The solution contains two class library projects: VegSOEInterfaces<language> and VegSOE<language>
      2. Under the Build menu, select the "Build Solution" item. If successful, two assemblies will be created. The VegSOEInterfaces<language>.dll should be created in the VegSOEInterfaces<language>\bin\Debug or the VegSOEInterfaces<language>\bin\Release folder. The VegSOE<language>.dll should be created in the VegSOE<language>\bin\Debug or the VegSOE<language>\bin\Release folder.
      3. Open a Visual Studio 2005 command prompt and navigate to the location of the the VegSOE<language>.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 (assuming you are working with the CSharp version of the sample): 
        regasm VegSOECSharp.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 VegCOMCSharp 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 VegCOMCSharp project.
        4. Run the following command: 
          regasm VegSOECSharp.dll
        5. Add the assembly to the GAC: 
          gacutil -i VegSOECSharp.dll
      4. The VegSOE<language>.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 VegSOECSharp.dll
      6. Open a Visual Studio 2005 command prompt and navigate to the location of the the VegSOEInterfaces<language>.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 VegSOEInterfacesCSharp.dll /tlb:VegSOEInterfacesCSharp.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 VegSOEInterfaces<language>.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 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 VegSOEInterfacesCSharp.dll /tlb:VegSOEInterfacesCSharp.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. If not already open, launch Microsoft Visual Studio 2005 and open the VegSOEProps<language> solution (for example, VegSOEPropsCSharp.sln). Open the VegSOEProps code file (e.g. VegSOEProps.cs) and navigate to the VegSOEProps constructor. Note that the type of service the SOE is registered with is specified ("MapServer"). The name of the SOE is also defined ("VegSOEUtilities_<language>"). 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 project (covered below).
      2. Under the Build menu, select the "Build Solution" item. If successful, the VegSOEProps<language>.dll should be created in the VegSOEProps<language>\bin\Debug or the VegSOEProps<language>\bin\Release folder.
      3. Open a Visual Studio 2005 command prompt and navigate to the location of the the VegSOEProps<language>.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 (assuming you are working with the CSharp version of the sample): 
        regasm VegSOEPropsCSharp.dll /codebase
      4. The VegSOEPropsCSharp.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.
      5. To unregister the assembly and type library, use the following command: 
        regasm /unregister VegSOECSharp.dll
    8. Register the server object extension with the ArcGIS Server SOM (Server Object Manager). To work with the RegisterSOE console application project, do the following:
      1. If not already open, launch Microsoft Visual Studio 2005 and open the RegisterSOE solution (RegisterSOE.sln).
      2. Under the Build menu, select the "Build Solution" item. If successful, the 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.
    9. 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".
    10. Add a new Map Service named "Yellowstone". Use the Yellowstone data provided with the sample data (location specified in instructions above). On the Capabilities tab, note the window with check boxes and server extensions in the upper left corner of the dialog. Scroll to the bottom of the window and check the box next to VegUtilitiesSOE<language>. The form created in the VegSOEProps<language> project and registered with ArcCatalog should display below the extension list. Set the Layer property to "Vegetation" and the Field property to "PRIMARY_". Finish configuring the service and start it.
    11. Consume the server object extension in a Web ADF application. To work with the VegSOEWebApp_<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 VegSOEWebApp_<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. Launch Microsoft Visual Studio 2005 and open the VegSOEWebApp<language> solution (for example, VegSOEWebAppCSharp.sln) located in c:\inetpub\wwwroot\ArcGIS_Spatial_Query_SOE_<language>\VegSOEWebApp<language>.
      6. In the Solution Explorer, 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. Click the ellipsis next to the ResourceItems property. The ResourceItem Collection Editor dialog should display.
      8. Add or change the MapResourceItem to the Yellowstone ArcGIS Server Local data source. The Yellowstone map service should have the server object extension been enabled (the map service created in the previous section).
      9. If not already added, add a reference to the VegSOE<language>.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).
      10. 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.
    12. Save the project.
    13. Click the "Debug" drop-down menu and choose "Start".
  2. Run time:
    1. Open a browser and navigate to the Web application URL (for example, http://localhost/ArcGIS_Spatial_Query_SOE_CSharp/VegWebAppCSharp) -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 Vegetaion layer. The summary statistics should be rendered in a table below the Toc.

Download the C# files
VegSOECSharp.csproj COM SOE project.
ArcGIS_Spatial_Query_SOE_CSharp/VegSOECSharp/VegSOECSharp/VegUtilsSOE.cs
(view code)
Utility class which performs the bulk of the fine-grained ArcObjects calls within the GIS Server.
ArcGIS_Spatial_Query_SOE_CSharp/VegSOECSharp/VegSOECSharp/VegResultsSOE.cs
(view code)
A class designed to store and package results to be passed to the client.
VegSOEInterfacesCSharp.csproj COM interfaces utilized by the SOE project.
ArcGIS_Spatial_Query_SOE_CSharp/VegSOECSharp/VegSOEInterfacesCSharp/VegSOEInterfaces.cs
(view code)
Class file that contains interface definitions implemented by the custom SOE class.
VegSOEPropsCSharp.csproj Property pages for ArcCatalog, COM class library project.
ArcGIS_Spatial_Query_SOE_CSharp/VegSOEPropsCSharp/VegSOEPropsCSharp/VegSOEProps.cs
(view code)
Business logic behind the ArcCatalog form.
ArcGIS_Spatial_Query_SOE_CSharp/VegSOEPropsCSharp/VegSOEPropsCSharp/FormVegProps.cs
(view code)
Form UI.
RegisterSOE.csporj Register the SOE with ArcGIS Server.
ArcGIS_Spatial_Query_SOE_CSharp/RegisterSOE/RegisterSOE/Program.cs
(view code)
Console appplication to register the custom SOE with ArcGIS Server.
VegSOEWebAppCSharp.sln Web application solution.
Default.aspx Contains Web user interface to interact with server-side code.
ArcGIS_Spatial_Query_SOE_CSharp/VegSOEWebAppCSharp/Default.aspx.cs
(view code)
Code behind the aspx file. References Web ADF libraries and functionality.
ArcGIS_Spatial_Query_SOE_CSharp/VegSOEWebAppCSharp/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 VB.NET files
VegSOEVBNet.vbproj COM SOE project.
ArcGIS_Spatial_Query_SOE_VBNet/VegSOEVBNet/VegSOEVBNet/VegUtilsSOE.vb
(view code)
Utility class which performs the bulk of the fine-grained ArcObjects calls within the GIS Server.
ArcGIS_Spatial_Query_SOE_VBNet/VegSOEVBNet/VegSOEVBNet/VegResultsSOE.vb
(view code)
A class designed to store and package results to be passed to the client.
VegSOEInterfacesVBNet.vbproj COM interfaces utilized by the SOE project.
ArcGIS_Spatial_Query_SOE_VBNet/VegSOEVBNet/VegSOEInterfacesVBNet/VegSOEInterfacesVBNet.vb
(view code)
Class file that contains interface definitions implemented by the custom SOE class.
VegSOEPropsVBNet.vbproj Property pages for ArcCatalog, COM class library project.
ArcGIS_Spatial_Query_SOE_VBNet/VegSOEPropsVBNet/VegSOEPropsVBNet/VegSOEProps.vb
(view code)
Business logic behind the ArcCatalog form.
ArcGIS_Spatial_Query_SOE_VBNet/VegSOEPropsVBNet/VegSOEPropsVBNet/FormVegProps.vb
(view code)
Form UI.
RegisterSOE.vbporj Register the SOE with ArcGIS Server.
ArcGIS_Spatial_Query_SOE_VBNet/RegisterSOE/RegisterSOE/Program.vb
(view code)
Console appplication to register the custom SOE with ArcGIS Server.
VegSOEWebAppVBNet.sln Web application solution.
Default.aspx Contains Web user interface to interact with server-side code.
ArcGIS_Spatial_Query_SOE_VBNet/VegSOEWebAppVBNet/Default.aspx.vb
(view code)
Code behind the aspx file. References Web ADF libraries and functionality.
ArcGIS_Spatial_Query_SOE_VBNet/VegSOEWebAppVBNet/App_Code/VegTool.vb
(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