How to register the SOE

In this topic

• Registering the custom SOE
• Registering SpatialQuerySOE.dll
• Registering SpatialQuerySOE.Interfaces.dll
• Registering SpatialQuerySOE.ArcCatalog.dll
• Registering SpatialQuerySOE.Manager.dll
• Registering the SOE with ArcGIS Server
• Configuring the SOE on a map service
• Configuring the SOE in ArcCatalog
• Configuring the SOE in ArcGIS Server Manager

Registering the custom SOE

• Assemblies must be registered with .NET and Component Object Model (COM) types on the machine that will be used. 
• SOE must be registered with ArcGIS Server.

• SpatialQuerySOE.dll—Contains core SOE classes and business logic.
• SpatialQuerySOE.Interfaces.dll—Interfaces implemented by the SOE.
• SpatialQuerySOE.ArcCatalog.dll—ArcCatalog property page to configure the SOE as an ArcGIS Server administrator.
• SpatialQuerySOE.Manager.dll—ArcGIS Server Manager property page to configure the SOE as an ArcGIS Server administrator.
  

Registering SpatialQuerySOE.dll

1. Start a Visual Studio command prompt and navigate to SpatialQuerySOE.dll. Type the following command:
• regasm SpatialQuerySOE.dll /codebase
  
  The regasm tool reads the metadata within an assembly and adds the necessary entries to the registry. The /codebase option registers the explicit location of the assembly. The codebase option returns a warning indicating that the assembly should be signed. If you choose to sign the assembly, you can place it in the global assembly cache (GAC) and remove the /codebase option when using regasm. Do the following steps to sign the assembly and add it to the GAC:
1. Create a strongly named key to sign the assembly. In Visual Studio, open the properties for the project and select the Signing tab. Select the Sign the assembly check box and create a key using the drop-down list below the check box, or create a key on the command line and browse to the location. To create a key on the command line, use the following syntax:
• sn -k MyKeyPair.snk
2. Rebuild the SpatialQuerySOE_CSharp project.
3. Run the following command:
• regasm SpatialQuerySOE.dll
4. Add the following assembly to the GAC:
• gacutil -i SpatialQuerySOE.dll
2. Verify the ArcGIS SOC user account has read and execute access on the directory that contains the registered assembly.
3. Use the following command to unregister the assembly and type library:
• regasm /unregister SpatialQuerySOE.dll

Registering SpatialQuerySOE.Interfaces.dll

1. Start a Visual Studio command prompt and navigate to the location of the SpatialQuerySOE.Interfaces.dll. Use the following command:
• regasm SpatialQuerySOE.Interfaces.dll /tlb: SpatialQuerySOE.Interfaces.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.  
2. Verify the ArcGIS SOC user account has read and execute access on the registered type library. On the client application machine, verify the user account that application is running on has read and execute access to the registered type library. To work with the types, add a reference to the SpatialQuerySOE.Interfaces.dll in the client application. For more information, see How to create an SOE client.     
3. Use the following command to unregister the assembly and type library:
• regasm /unregister SpatialQuerySOE.Interfaces.dll /tlb: SpatialQuerySOE.Interfaces.tlb

Registering SpatialQuerySOE.ArcCatalog.dll

1. Start a Visual Studio command prompt and navigate to the location of the SpatialQuerySOE.ArcCatalog.dll. Use the ESRIRegAsm tool to register the SpatialQuerySOE.ArcCatalog.dll assembly on machines where ArcCatalog will be used to configure a service with the custom SOE.
1. Create a strongly named key to sign the assembly. In Visual Studio, open the properties for the project and select the Signing tab. 
2. Select the Sign the assembly check box and create a key using the drop-down list below the check box, or create a key on the command line and browse to the location. 
3. To create a key on the command line, use the following syntax:
• sn -k MyKeyPair.snk
2. Rebuild the SpatialQuerySOE.ArcCatalog_CSharp project.
3. Run the following command:
• ESRIRegAsm SpatialQuerySOE.ArcCatalog.dll /p:Desktop
  
  ArcGIS 10 has a new registration utility (ESRIRegAsm.exe) and an Extensible Markup Language (XML) database independent of the system registry. Therefore, the registration of component and category information for a developer’s assembly or dynamic-link library (DLL) is achieved using the new ESRI provided utility called ESRIRegAsm. The ESRIRegAsm utility is included the <Program Files>\Common Files\ArcGIS\bin folder.
4. Verify the user account running ArcCatalog has read and execute access on the directory that contains the registered assembly.
5. To confirm the property page registered with ArcGIS component categories correctly, run the categories.exe file in <ArcGIS Install>\bin directory and open the AGS Extension Parameter Pages folder. The SpatialQuerySOE.ArcCatalog.PropertyPage property page is listed.
6. To unregister the assembly and type library, type the following command:
• ESRIRegAsm SpatialQuerySOE.ArcCatalog.dll /p:Desktop /u

Registering SpatialQuerySOE.Manager.dll

1. In Visual Studio, right-click the SpatialQuerySOE.Manager_CSharp project and select Properties.
2. On the Properties page, click the Signing tab.
3. Select the Sign the Assembly check box and select New from the drop-down list below the check box.
4. On the dialog box that appears, choose a name for the key file and if applicable, add a password to protect it.
5. Rebuild the project.
6. Start a Visual Studio command prompt and navigate to the location of  SpatialQuerySOE.Manager.dll.
7. Add the following command to install the assembly into the GAC:
• gacutil –i SpatialQuerySOE.Manager.dll
8. To update the Manager’s web.config file, you need the assembly's PublicKeyToken. Use the following command to retrieve the PublicKeyToken:
• sn –T SpatialQuerySOE.Manager.dll
9. In Visual Studio, open Manager’s web.config file. The following is the file's default location:
• <install drive letter>:\Inetpub\wwwroot\ArcGIS\Manager\web.config
10. In the Extensions section, add an Extension element to make Manager aware of the extension. The element appears as shown in the following code example; however, the PublicKeyToken differs: 

<Extension
  name="SpatialQuerySOE"
  DisplayName="Spatial Query"
  ConfiguratorType="SpatialQuerySOE.Manager.Configurator, SpatialQuerySOE.Manager, 
    Version=1.0.0.0, Culture=neutral, PublicKeyToken=a640acaea98a8392"/>

Registering the SOE with ArcGIS Server

1. Create the SOE registration project:
1. In Visual Studio, open the ArcGIS_Spatial_Query_SOE_CSharp2008 solution.
2. In the Solution Explorer, right-click the solution, click Add, then click New Solution Folder. Name the folder Registration.
3. In the Solution Explorer, right-click the Registration folder, click Add, then click New Project. The Add New Project dialog box appears.
4. Under the Project types pane, click the Visual C# project type. Under the Templates pane, click Console Application.
5. Type a path for the project's location. 
6. Type RegisterSOE_CSharp in the Name text box and click OK. 
2. Add a reference to the following assemblies:
• ESRI.ArcGIS.ADF.Connection
• ESRI.ArcGIS.Server
3. Open the Program.cs file. In the automatically generated Main method, add code to initiate a connection to the SOM:
1. Verify the SOE is registered, then register or unregister the SOE depending on the command line arguments. To verify the extension's registration status, use the ExtensionRegistered method (defined in Step 3, d). 
2. After the main action has executed, output a message to inform the user of the command's status. See the following code example:

// Must run as a user in the agsadmin group on the SOM.
ESRI.ArcGIS.ADF.Connection.AGS.AGSServerConnection agsServerConnection = new
    ESRI.ArcGIS.ADF.Connection.AGS.AGSServerConnection();
agsServerConnection.Host = "localhost";
agsServerConnection.Connect();
ESRI.ArcGIS.Server.IServerObjectAdmin2 serverObjectAdmin =
    agsServerConnection.ServerObjectAdmin as ESRI.ArcGIS.Server.IServerObjectAdmin2;

' Must run as a user in the agsadmin group on the SOM.
Dim agsServerConnection As New ESRI.ArcGIS.ADF.Connection.AGS.AGSServerConnection()
agsServerConnection.Host = "localhost"
agsServerConnection.Connect()
Dim serverObjectAdmin As ESRI.ArcGIS.Server.IServerObjectAdmin2 = TryCast(agsServerConnection.ServerObjectAdmin, ESRI.ArcGIS.Server.IServerObjectAdmin2)

string extensionName = "SpatialQuerySOE";

Dim extensionName As String = "SpatialQuerySOE_VBNet"

// Check command line arguments to verify if the SOE should be unregistered.
if (args.Length == 1 && args[0] == "/unregister")
{
    // Verify the SOE is registered.
    if (ExtensionRegistered(serverObjectAdmin, extensionName))
    {
        // Delete the SOE.
        serverObjectAdmin.DeleteExtensionType("MapServer", extensionName);
        Console.WriteLine(extensionName + " successfully unregistered");
    }
    else
        Console.WriteLine(extensionName + " is not registered with ArcGIS Server");
}

' Check command line arguments to see if the SOE should be unregistered.
If args.Length = 1 AndAlso args(0) = "/unregister" Then
    ' Verify the SOE is registered.
    If ExtensionRegistered(serverObjectAdmin, extensionName) Then
        ' Delete the SOE.
        serverObjectAdmin.DeleteExtensionType("MapServer", extensionName)
        Console.WriteLine(extensionName & " successfully unregistered")
    Else
        Console.WriteLine(extensionName & " is not registered with ArcGIS Server")
    End If
Else

else
{
    // Verify the SOE is registered.
    if (!ExtensionRegistered(serverObjectAdmin, extensionName))
    {
        ESRI.ArcGIS.Server.IServerObjectExtensionType2 serverObjectExtensionType =
            serverObjectAdmin.CreateExtensionType()as
            ESRI.ArcGIS.Server.IServerObjectExtensionType2;
        // Must match the namespace and class name of the class implementing IServerObjectExtension.
        serverObjectExtensionType.CLSID = "SpatialQuerySOE.Extension";
        serverObjectExtensionType.Description = 
            "Spatial Query Server Object Extension";
        serverObjectExtensionType.Name = extensionName;

        // Name that shows in the capabilities list on the property pages.
        serverObjectExtensionType.DisplayName = "Spatial Query";
        // Register the SOE with the server.
        serverObjectAdmin.AddExtensionType("MapServer", serverObjectExtensionType);
        Console.WriteLine(extensionName + 
            " successfully registered with ArcGIS Server");
    }
    else
        Console.WriteLine(extensionName + 
            " is already registered with ArcGIS Server");
}

If (Not ExtensionRegistered(serverObjectAdmin, extensionName)) Then
    Dim serverObjectExtensionType As ESRI.ArcGIS.Server.IServerObjectExtensionType2 = TryCast(serverObjectAdmin.CreateExtensionType(), ESRI.ArcGIS.Server.IServerObjectExtensionType2)
    ' Must match the namespace and class name of the class implementing IServerObjectExtension.
    serverObjectExtensionType.CLSID = "SpatialQuerySOE_VBNet.Extension"
    serverObjectExtensionType.Description = "Spatial Query Server Object Extension (VBNet)"
    serverObjectExtensionType.Name = extensionName
    ' Name that will be shown in the capabilities list on the property pages.
    serverObjectExtensionType.DisplayName = "Spatial Query VBNet"
    ' Register the SOE with the server.
    serverObjectAdmin.AddExtensionType("MapServer", serverObjectExtensionType)
    Console.WriteLine(extensionName & " successfully registered with ArcGIS Server")
Else
    Console.WriteLine(extensionName & " is already registered with ArcGIS Server")
End If

static private bool ExtensionRegistered(ESRI.ArcGIS.Server.IServerObjectAdmin2
    serverObjectAdmin, string extensionName)
{
    // Get the extensions that extend MapServer server objects.
    ESRI.ArcGIS.Server.IEnumServerObjectExtensionType extensionTypes =
        serverObjectAdmin.GetExtensionTypes("MapServer");
    extensionTypes.Reset();
    // If an extension with a name matching the name passed in is found, return true.
    ESRI.ArcGIS.Server.IServerObjectExtensionType extensionType =
        extensionTypes.Next();
    while (extensionType != null)
    {
        if (extensionType.Name == extensionName)
            return true;
        extensionType = extensionTypes.Next();
    }
    // No matching extension was found; therefore, return false.
    return false;
}

Private Shared Function ExtensionRegistered(ByVal serverObjectAdmin As ESRI.ArcGIS.Server.IServerObjectAdmin2, ByVal extensionName As String) As Boolean
' Get the extensions that extend MapServer server objects.
Dim extensionTypes As ESRI.ArcGIS.Server.IEnumServerObjectExtensionType = serverObjectAdmin.GetExtensionTypes("MapServer")
extensionTypes.Reset()
' If an extension with a name matching the name passed in is found, return true.
Dim extensionType As ESRI.ArcGIS.Server.IServerObjectExtensionType = extensionTypes.Next()
Do While extensionType IsNot Nothing
    If extensionType.Name = extensionName Then
        Return True
    End If
    extensionType = extensionTypes.Next()
Loop
' No matching extension was found; therefore, return false.
Return False
End Function

<types>
  <ServerObjectType>
    <Name>MapServer</Name>
    <ExtensionTypes>
      <ExtensionType>
        <Name>SpatialQuerySOE</Name>
        <DisplayName>SpatialQuery</DisplayName>
        <CLSID>SpatialQuerySOE.Extension</CLSID>
        <Description>Spatial Query Server Object Extension</Description>
      </ExtensionType>
    </ExtensionTypes>
  </ServerObjectType>
</types>

Configuring the SOE on a map service

• <ArcGIS Developer Kit Install\Samples\data\Yellowstone
  

• Polygon feature class—Stored in the veg.mdb personal geodatabase and contains polygons referencing the geographic areas of different vegetation types in Yellowstone National Park.
• Grid—Digital elevation model (DEM) in ArcInfo Grid format and provides a topographic reference for the area. 

1. Add the Yellowstone map document as an ArcGIS Server map service and enable the SpatialQuerySOE extension using a field in the vegetation layer.
2. Using ArcCatalog or ArcGIS Server Manager, publish the Yellowstone.mxd map document as a new map service.

Configuring the SOE in ArcCatalog

1. Start ArcCatalog and connect to ArcGIS Server as an administrator.
2. Right-click the Yellowstone service and click Service Properties. The Map Service Properties dialog box appears.
3. Click the Capabilities tab.
4. In the list of available capabilities, select the Spatial Query check box to enable the custom SOE.
5. In the Properties section on the Capabilities tab, you will see the form you implemented in the SpatialQuerySOE.ArcCatalog_CSharp project. Select Vegetation from the Layer drop-down list and select PRIMARY_ from the Field drop-down list. The PRIMARY_ field stores the vegetation type name and is used by the SpatialQuerySOE extension to aggregate the area totals for the selected region.
   
   See the following screen shot that shows the dialog box to configure the Yellowstone map document in ArcCatalog:
   
   
   
6. Click OK.

Configuring the SOE in ArcGIS Server Manager

1. Open a Web browser, navigate to the ArcGIS Server Manager login page, and log in as an administrator.
2. In the left-hand menu, click Services. 
3. From the list of services, select the service you created from the Yellowstone.mxd map document.
4. Click the Capabilities tab.
5. In the list of capabilities, select the Spatial Query check box to enable the custom SOE.
6. Under the Choose the layer and field area, you will see the form you implemented in the SpatialQuerySOE.Manager_CSharp project. Select Vegetation from the Layer drop-down list and select PRIMARY_ from the Fields drop-down list. The PRIMARY_ field stores the vegetation type name and is used by the SpatialQuerySOE extension to aggregate the area totals for the selected region.
   
   See the following screen shot that shows the dialog box to configure the Yellowstone map document in ArcGIS Server Manager:
   
   
7. Click Save.

See Also: