ArcGIS Simple Server Object Extension



Description:

This sample is designed to illustrate the basic framework for adding a simple server object extension and exposing the extension the ArcGIS Server SOAP service handler. It includes a Web application that calls into a server object extension via ArcObjects over DCOM and SOAP over HTTP. In both cases custom functionality executes on the server. The remote ArcObjects portion of the sample accepts a user-defined point, uses the ESRI.ArcGIS.Geometry.ITopologicalOperator interface to buffer the point, and returns the buffer polygon to the client. The SOAP portion of the sample illustrates how to use a SOAP proxy to request the time on the server (ArcSOC.exe hosting the server object\SOE).

The server object extension is added and managed with a server object/service. Configuring the server object extension is accomplished when a service is created in ArcCatalog. In this sample, the server object extension is merely checked on for a service.

Note, the SOAP interface for ArcGIS Server services is implemented at the server object level. This means that SOAP messages are processed directly by a server object or extension (SOE). The ArcGIS Server SOAP Web service handler directs SOAP messages to a server object or SOE. The SOAP Web service handler contains logic to discover custom SOEs with a SOAP interface.

The SOAP implementation in this sample is merely instructive, so it just provides the basics of custom SOE development. To expose a WSDL for the custom SOE and make it available via an ArcGIS Server SOAP Web service handler, create a WSDL and put it in the <ArcGIS Install>\XmlSchema folder on the machine where the SOM is running. The name of the registered server object extension and the name of the *.wsdl file must be the same. To process SOAP requests, implement the IRequestHandler and IRequestHandler2 interfaces in the custom SOE class. In this sample, the implementation code parses the incoming SOAP request and generates a raw SOAP response string. The response should match the WSDL definition. Currently there is no standard pattern for constructing the WSDL the defines what your SOE can do - namely the SOAP request and response structure. Processing SOAP messages will likely involve language (.NET) specific patterns for handling XML structures. Generating a SOAP response will be somewhat more difficult since the response structure must match the WSDL definition. In any case, once the custom SOE is deployed and enabled on a map service, you can use the following url (CSharp version) to get the WSDL: http://localhost/arcgis/services/<service name>/MapServer/SimpleSOE_CSharp?wsdl

This sample is divided into three parts. The server object extension component is divided into two sections: the SOE business logic component which is registered as a COM component to be consumed by a COM client (ArcGIS Server), and the COM interface which is registered on both the server and client and defines the contract (methods, types) that will be used to enable the use of DCOM components across the client and 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.3

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 two .NET class library projects. The SimpleSOEInterfaces project contains an interface that defines the public contract a client will use to interact with SOE business logic defined in the SimpleSOE project. Interfaces are built in a separate assembly which you can distribute to an ArcGIS Server client that contains ArcObjects COM proxies (e.g. ADF, Engine app). This way you only need to distribute the contract to the clients, not the business logic, which is unnecessary. 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 interacts with the SOE via DCOM and SOAP via ArcGIS Server.

      Build and register the server object extension interface and class library first.
      1. Launch Microsoft Visual Studio 2005\2008 and open the SimpleSOE_<language><vs_version> solution (for example, SimpleSOE_CSharp2008.sln). The <vs_version> references the Visual Studio version of the solution, either 2005 or 2008.
      2. Under the Build menu, select the "Build Solution" item. If successful, two assemblies will be created. The SimpleSOEInterfaces_<language>.dll should be created in the SimpleSOEInterfaces_<language>\bin\Debug or the SimpleSOEInterfaces_<language>\bin\Release folder. 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/2008 command prompt and navigate to the location of the SimpleSOEInterfaces_<language>.dll. This assembly contains an interface 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 the interface (assuming you are working with the CSharp version of the sample):
                            regasm SimpleSOEInterfaces_CSharp.dll /tlb:SimpleSOEInterfaces_CSharp.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.
      4. The SimpleSOEInterfaces_<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.
      5. To unregister the type library, use the following command:
                            regasm /unregister SimpleSOEInterfaces_CSharp.dll /tlb:SimpleSOEInterfaces_CSharp.tlb
                          
      6. Open a Visual Studio 2005\2008 command prompt and navigate to the location of 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. For deployment in a production environment you should sign the assembly and place it in the Global Assembly Cache (GAC). During registration remove the "/codebase" option when using regasm. To sign the assembly and add it to the GAC, do the following:
        1. The project already includes a public key, but you can generate a new key if you choose. To create a strongly named key use the following command:
                                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
                              
      7. 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.
      8. To unregister the assembly and type library, use the following command:
                            regasm /unregister SimpleSOE_CSharp.dll
                          
    6. To support the SOAP interface for a custom SOE, add the SOE WSDL to the <ArcGIS Install>\XmlSchema folder. The name of the registered server object extension and the name of the *.wsdl file must be the same.
    7. Register the server object extension with ArcGIS Server. To work with the RegisterSOE console application project, do the following:
      1. In Microsoft Visual Studio set the RegisterSOE project as the active project.
      2. Under the Debug menu, select the "Start Debugging" 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.
    8. 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".
    9. 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.
    10. 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 that 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 SimpleSOEInterfaces_<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. Note, a Web reference has been added to the Web site project to utilize the SOE via SOAP. The path to the WSDL used generate the SOAP proxy and value object types is (CSharp version): http://localhost/arcgis/services/<service name>/MapServer/SimpleSOE_CSharp?wsdl. Working with the SOAP service does not require a COM proxy on the client (e.g. the SimpleSOEInterfaces library) - only the SOAP proxy will be used to communicate with the SOE on the server.
    11. Save the project.
    12. 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 via SOAP" button is merely designed to show you how to work with the server object extension via SOAP on the click event of an ASP.NET button. Step though the code behind the button to see how the SOAP proxy is used call logic in the server object extension. A message box and the window status bar in the browser are updated with the time on the machine on which the ArcSOC.exe (hosting the server object\SOE) is running.

Download the C# files
ArcGIS_Simple_Server_Object_Extension_CSharp/SimpleSOE_CSharp/SimpleSOEInterfaces_CSharp/SimpleSOEInterfaces_CSharp.cs COM Interfaces for the SOE.
ArcGIS_Simple_Server_Object_Extension_CSharp/SimpleSOE_CSharp/SimpleSOE_CSharp/UtilSOE_CSharp.cs Implementation code for the SOE.
ArcGIS_Simple_Server_Object_Extension_CSharp/SimpleSOE_CSharp/SimpleSOE_CSharp/SimpleSOE_CSharp.wsdl WSDL representing the SOAP interface for the SOE.
RegisterSOE.csproj Solution referencing the console application project used to register\unregister an SOE.
ArcGIS_Simple_Server_Object_Extension_CSharp/RegisterSOE/Program.cs Registers\Unregisters the SOE with a SOM.
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
ArcGIS_Simple_Server_Object_Extension_VBNet/SimpleSOE_VBNet/SimpleSOEInterfaces_VBNet/SimpleSOEInterfaces_VBNet.vb COM Interfaces for the SOE.
ArcGIS_Simple_Server_Object_Extension_VBNet/SimpleSOE_VBNet/SimpleSOE_VBNet/UtilSOE_VBNet.vb Implementation code for the SOE.
ArcGIS_Simple_Server_Object_Extension_VBNet/SimpleSOE_VBNet/SimpleSOE_VBNet/SimpleSOE_VBNet.wsdl WSDL representing the SOAP interface for the SOE.
RegisterSOE.vbproj Solution referencing the console application project used to register\unregister an SOE.
ArcGIS_Simple_Server_Object_Extension_VBNet/RegisterSOE/Program.vb Registers\Unregisters the SOE with a SOM.
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