Migrating a .NET server object extension to 10.1

Migrating a .NET server object extension (SOE) to 10.1 requires that you copy most of your existing SOE code into the 10.1 Visual Studio templates for REST or SOAP SOEs. The reason you need to do this is because the 10.1 templates contain the packaging logic to make a .soe file. This file is new at 10.1 and allows you to deploy your SOE to ArcGIS Server in one step. The .soe file is created when you build the project.

Another advantage of the 10.1 template is that the references are already pointing at primary interop assemblies shipped with the 10.1 ArcObjects SDK. If your project requires any references other than the ones included in the template, you need to manually add those references.

SOEs created in versions 10.0 and earlier that rely on ArcGIS Server Local (DCOM) connections cannot be used at version 10.1. These SOEs should be refactored to act as REST or SOAP web services.

Below are the steps for migrating an SOE from 10.0 to 10.1:

Steps:
  1. If the SOE was previously registered on your machine, unregister it using a command such as regasm <path to DLL> /codebase /u.
  2. Open Visual Studio 2010 and click File > New > Project.
  3. In the Installed Templates tree, expand Visual C# > ArcGIS > Server Object Extensions.
  4. At the top of the New Project dialog box, choose .NET Framework 3.5 from the drop-down menu.
  5. Choose between the REST or SOAP templates, type a name and location for your SOE, then click OK.
  6. Add any references and directives your project requires that are not already included in the template.
  7. In the template code, modify the .NET attribute ServerObjectExtension to contain the capabilities, description, display name, properties, and supported web service architectures for your SOE. These are the kinds of values that you set in your SOE registration code prior to 10.1. A C# example might look like this:
    [ServerObjectExtension("MapServer",
            AllCapabilities = "GetCommonInfo;GetSecretInfo",
            DefaultCapabilities = "GetCommonInfo",
            Description = "An example SOE for the help system",
            DisplayName = "My Sample SOE",
            Properties = "PropertyA=500;PropertyB=Cities",
            SupportsREST = true,
            SupportsSOAP = false)]
    

    The above SOE has two available capabilities: GetCommonInfo and GetSecretInfo. However, only GetCommonInfo is enabled by default.

    Likewise, there are two properties on this SOE: Property A, which defaults to a value of 500, and PropertyB, which defaults to a value of Cities. All properties are initially treated as strings.

  8. Copy the entire class code (but not the class declaration) from your pre-10.1 SOE and replace the corresponding code in the template. The boilerplate class code at 10.1 is identical to the 10.0 code except that 10.1 SOEs do not derive from ServicedComponent nor do they require a reference to System.EnterpriseServices. You should remove these items if you do a complete copy and paste. You can use the 10.1 template and samples as a guide.

    The example below shows what you should remove and replace with your 10.0 code when migrating a REST SOE:

    public class MySampleSOE : IServerObjectExtension, IObjectConstruct, IRESTRequestHandler
        {
           // Delete 10.1 template code and paste your 
           //   corresponding 10.0 code here.
        }
    

    If your 10.1 SOE has a different name than your 10.0 SOE, you will need to update the SOE name in the constructor:

    public MySampleSOE()
            {
                soe_name = this.GetType().Name;
                logger = new ServerLogger();
                reqHandler = new SoeRestImpl(soe_name, CreateRestSchema()) as IRESTRequestHandler;
            }
    
  9. Save your solution and build your project. A successful build creates an .soe file under your project's bin directory.
  10. Deploy your SOE to ArcGIS Server using the instructions in Deploying a server object extension.
12/18/2014