Migrating a 10.0 .NET server object extension to later versions

.NET server object extensions (SOEs) that you develop with ArcGIS 10.1 are usable within version 10.2 and later. However, SOEs developed with version 10.0 take more effort to migrate. The remainder of this topic explains how to migrate version 10.0 SOEs to work with 10.1 and later versions.

Migrating a version 10.0 .NET server object extension (SOE) requires that you copy most of your existing SOE code into the Visual Studio templates for REST or SOAP SOEs. The reason you need to do this is because the templates contain the packaging logic to make a .soe file. This file was introduced 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 template is that the references are already pointing at primary interop assemblies shipped with the 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 in 10.1 and later versions. These SOEs should be refactored to act as REST or SOAP web services.

Below are the steps for migrating a 10.0 SOE:

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 in versions 10.0 and previous. 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 10.0 SOE and replace the corresponding code in the template. The boilerplate class code is identical to the 10.0 code except that 10.1 and later version 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 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 template code and paste your 
          //   corresponding 10.0 code here.
       }

   If your 10.1 and later version 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 an extension.