ArcGIS Simple Server Object Extension



Description:

This sample is designed to illustrate the basic framework for adding a simple server object extension. It includes a Web application that uses the ArcGIS Server API to access custom functionality on the server to make a series of fine-grained ArcObjects method calls. In essense, at runtime the server object extension takes a user-defined point, uses the ESRI.ArcGIS.Geometry.ITopologicalOperator interface to buffer the point, and returns the buffer polygon to the client. This is accomplished by extending the GIS Server with a server object extension component that exposes a coarse-grained method to access ArcObjects within the server. The server object extension is added and managed as part of the server object. Configuring the server object extension is accomplished when a server object is created in ArcCatalog. In this sample, the server object extension is merely checked on for a server object.

This sample is divided into three parts. The server object extension component which is registered as a COM component to be consumed by a COM client (ArcGIS Server). A registration console application adds the server object extension to ArcGIS Server. And lastly, a .NET Web application to consume the server object extension. In order to use this sample, you must have the Web ADF 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.
Products:
Server: C#, VB.NET

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_Simple_Server_Object_ExtensionCSharp.zip or ArcGIS_Simple_Server_Object_ExtensionVBNet.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_Simple_Server_Object_Extension_<language>, to c:\inetpub\wwwroot. The <language> variable may be either CSharp or VBNet.
    5. In Windows Explorer, navigate to c:\inetput\wwwroot\ArcGIS_Simple_Server_Object_Extension_<language>. Note there are multiple application directories. The SimpleSOE_<language> directory contains the .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 RegisterSOE project contains a console application to add the server object extension to the ArcGIS Server instance. The SimpleSOEWebApp_<language> directory contains the ASP.NET Web application that consumes the COM object in the SOE remotely via ArcGIS Server.

      Build and register the server object extension class library first. To work with the SimpleSOE_<language> class library project, do the following:
      1. Launch Microsoft Visual Studio 2005 and open the SimpleSOE_<language> solution (for example, SimpleSOE_CSharp.sln).
      2. Under the Build menu, select the "Build Solution" item. If successful, the SimpleSOE_<language>.dll should be created in the SimpleSOE_<language>\bin\Debug or the SimpleSOE_<language>\bin\Release folder.
      3. Open a Visual Studio 2005 command prompt and navigate to the location of the the SimpleSOE_<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 SimpleSOE_CSharp.dll /codebase
        
        The regasm utility registers the assembly, the /tlb option creates and registers a type library for use by COM clients, and 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 SimpleSOE_CSharp 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 SimpleSOE_CSharp project.
        4. Run the following command:
          regasm SimpleSOE_CSharp.dll 
          
        5. Add the assembly to the GAC:
          gacutil -i SimpleSOE_CSharp.dll
          
      4. The .NET assembly and type library should be registered the ArcGIS Server Object Container 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 SimpleSOE_CSharp.dll 
        
    6. Register the server object extension with ArcGIS Server. 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.
    7. 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".
    8. Add a new Map Service. Define a name and the appropriate parameters. 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 SimpleSOE_<language>. Finish configuring the service and start it.
    9. Consume the server object extension in a Web ADF application. To work with the SimpleSOEWebApp_<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_Simple_Server_Object_Extension_<language> right-click the SimpleSOEWebApp_<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 SimpleSOEWebApp_<language> solution (for example, SimpleSOEWebApp_CSharp.sln) located in c:\inetpub\wwwroot\ArcGIS_Simple_Server_Object_Extension_<language>\SimpleSOEWebApp_<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 an ArcGIS Server Local data source the works with the Map service on which the server object extension has been enabled (the Map service created in the previous section).
      9. If not already added, add a reference to the SimpleSOE_<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. Save the project.
    11. Click the "Debug" drop-down menu and choose "Start".
  2. Run time:
    1. Browse to viewer's URL (for example,c:\inetpub\wwwroot\ArcGIS_Simple_Server_Object_Extension_CSharp\SimpleSOEWebApp_CSharp).
    2. Click the "Create Circle from Point" tool and click on the map. The request will take a moment to process. A buffer polygon should be rendered on the map. The ESRI.ArcGIS.Geometry.IPolygon returned from ArcGIS Server is converted to Web ADF geometry and added to a Web ADF graphics layer to be rendered. The radius is 10% of the extent width - this can be changed in the custom tool implementation.
    3. The "Call SOE Directly Example" button is merely designed to show you how to work with the server object extension on the click event of an ASP.NET button. Step though the code behind the button to see how the server object extension is used programmatically. Note that the connection to ArcGIS Server is managed by the Connection library (ESRI.ArcGIS.ADF.Connection.dll) and it not dependent on Web ADF controls, resources or functionalities.

Download the C# files
SimpleSOE_CSharp.csproj Project the Simple SOE implementation class library project and code.
ArcGIS_Simple_Server_Object_Extension_CSharp/SimpleSOE_CSharp/UtilSOE_CSharp.cs Implementation code for the SOE.
RegisterSOE.csproj Solution referencing the console application project used to register\unregister an SOE.
ArcGIS_Simple_Server_Object_Extension_CSharp/RegisterSOE/RegisterSOE/Program.cs Registers\Unregisters the SOE with a GIS Server.
SimpleSOEWebApp_CSharp.sln Solution referencing the a web application project that consumes an SOE.
Default.aspx Contains Web user interface to interact with server-side code.
ArcGIS_Simple_Server_Object_Extension_CSharp/SimpleSOEWebApp_CSharp/Default.aspx.cs The code file that contains interactive logic with an SOE.
ArcGIS_Simple_Server_Object_Extension_CSharp/SimpleSOEWebApp_CSharp/App_Code/SOETool.cs Class library containing a tool which calls the Simple SOE to perform work.
Download the VB.NET files
SimpleSOE_VBNet.vbproj Project the Simple SOE implementation class library project and code.
ArcGIS_Simple_Server_Object_Extension_VBNet/SimpleSOE_VBNet/UtilSOE_VBNet.vb Implementation code for the SOE.
RegisterSOE.vbproj Solution referencing the console application project used to register\unregister an SOE.
ArcGIS_Simple_Server_Object_Extension_VBNet/RegisterSOE/RegisterSOE/Program.vb Registers\Unregisters the SOE with a GIS Server.
SimpleSOEWebApp_VBNet.sln Solution referencing the a web application project that consumes an SOE.
Default.aspx Contains Web user interface to interact with server-side code.
ArcGIS_Simple_Server_Object_Extension_VBNet/SimpleSOEWebApp_VBNet/Default.aspx.vb The code file that contains interactive logic with an SOE.
ArcGIS_Simple_Server_Object_Extension_VBNet/SimpleSOEWebApp_VBNet/App_Code/SOETool.vb Class library containing a tool which calls the Simple SOE to perform work.

Download the files for all languages