This document is archived and information here might be outdated.  Recommended version.


Server

Server


Supported with:
  • Engine
  • ArcGIS for Desktop Basic
  • ArcGIS for Desktop Standard
  • ArcGIS for Desktop Advanced
  • Server
Library dependencies: Version, System, SystemUI, Geometry, GraphicsCore, Display

Additional library information: Contents, Object Model Diagram

The Server library contains objects that allow you to connect to and work with ArcGIS for Server. You gain access to ArcGIS for Server using the GISServerConnection object. The GISServerConnection object gives you access to user and administrative connections to the Server Object Manager (SOM). Using these connections, you can work with ServerContext objects to manipulate ArcObjects running on the server.
The Server library is not extended by developers. Developers can also use the GISClient library when interacting with ArcGIS for Server.

See the following sections for more information about this namespace:

Server connection objects

Role-based security
ArcGIS for Server can be used to build Web geographic information systems (GIS) that include both GIS Web services as well as Web applications. The Web GIS supports role-based security. Administrators can use the ArcGIS Server Manager application to define Web GIS users and roles and can grant these roles permissions on the GIS services.
The GIS Server (SOM and Server Object Containers [SOC]) is the key back end server in the Web GIS and hosts the GIS services that make up the core of the system. The permissions of roles on GIS services are maintained in the back end GIS Server.
ArcGIS for Server implements a layered security architecture. To understand the role of the SOM in implementing the Web GIS security model, it is helpful to keep the following key concepts in mind:
  • The goal of the security architecture is to implement security for systems with a Web (Hypertext Transfer Protocol [HTTP]) front end.
  • Web users connect to and use GIS services via Web service endpoints using Simple Object Access Protocol (SOAP), Representational State Transfer (REST), Open Geospatial Consortium (OGC), or Keyhole Markup Language (KML) specifications.
  • The security system being set up applies to these external Web users.
  • An ArcGIS Server system has the following two user or identity spaces:
  • External Web GIS users who connect to the Web service endpoints
  • Local users who connect directly to the SOM
  • Web service endpoint implementations connect locally to the GIS server (the SOM) and perform work on behalf of the external (Web GIS) user.
  • Security is implemented in the Web tier such that Web users are allowed to access only those resources for which they are authorized.
  • The permissions stored within the SOM apply to external users and roles.
  • A local connection to the SOM can be used to determine if a specified external user has permission on a specified resource.
  • Local connections to the SOM are made as a local user (using an operating system login that must be in the agsusers or agsadmin group).
  • All local users, whether in the agsadmin or the agsusers group, are internal trusted users and by definition are able to see all information.
The following terms apply to the security model for Web GIS users. The term "user" refers to an external (Web GIS) user as previously defined.
  • User—An individual identified by a unique user name who wants to consume resources provided by ArcGIS Server. Users are stored in a user store, which can be a database or the active directory on a Windows server or a Lightweight Directory Access Protocol (LDAP) sever. All user authentication takes place in the Web tier.
  • Role—A collection of users based on functional, departmental, or classification groupings (for example, planners, editors, classified, unclassified, and so on). A role can be assigned a permission to use or invoke operations on a resource. Roles are stored in a Role Store, which can be a database or the active directory on a Windows server or an LDAP server.
  • Principal—A general term that denotes a iser or role.
  • Resource—An item or object that is to be secured. In ArcGIS for Server, resources are Web applications and GIS services and server folders containing GIS services.
  • Operation—An action or method that can be invoked on a secured resource. In ArcGIS for Server, no distinction is made between operations, and the only valid value, "*", is used to denote all actions.
  • Permission—The ability of a role to use or invoke operations on a specific resource. Permissions are assigned in a Continuous Inheritance model. A child resource inherits permissions from its parent resource and the child can be changed to differ from the parent. Changing the permission on the parent for a specific user/role restores inheritance to match the parent recursively; all children will be changed to match the parent.
Local GIS server connections and role-based Web GIS security
Local clients (Web service endpoints, desktop applications running behind the firewall) connect to the GIS server using the GISServerConnection object. The operating system identity of the calling thread must be that of a local user in either the agsadmin or the agsusers group. The GISServerConnection object supports the IGISServerConnection and IGISServerConnection2 interfaces. IGISServerConnection has a Connect method that connects the application to the GIS server. You call the Connect method and provide the name or IP address of the machine on which the SOM is running.
Once connected to the GIS server, IGISServerConnection and IGISServerConnection2 have properties that hand out references to ServerObjectManager and ServerObjectAdmin for browsing and using server objects and for administering server objects, respectively.
IGISServerConnection2 allows the caller to specify the identity of an external (Web GIS) user on behalf of whom this local connection is being made. If role-based security is enabled, only those folders and services that are accessible by the specified external user will be visible through the SOM obtained from this connection. This is a convenient way to determine a specified external user's view of the resources in the server.
The IGISServerConnection.Connect method requires that the operating system identity of the calling thread be that of a local user in either the agsadmin or the agsusers group. If the account running the application is not a member either of these groups, the Connect method on IGISServerConnection returns an error.
The following illustration shows this connection:
The following code example shows how to use GISServerConnection to connect to a GIS server running on a machine called myServer and print out the names and types of the server object configurations on the server:
[VB.NET]
Dim gisServerConnection As IGISServerConnection=New GISServerConnection()
gisServerConnection.Connect("myServer")

Dim serverObjectManager As IServerObjectManager=gisServerConnection.ServerObjectManager
Dim enumConfigInfo As IEnumServerObjectConfigurationInfo=serverObjectManager.GetConfigurationInfos

Dim configInfo As IServerObjectConfigurationInfo=enumConfigInfo.Next

Do Until configInfo Is Nothing
    Debug.Print (configInfo.Name & ": " & configInfo.TypeName)
    configInfo=enumConfigInfo.Next()
Loop
[C#]
IGISServerConnection connection=new GISServerConnection();
connection.Connect("myServer");

IServerObjectManager serverObjectManager=connection.ServerObjectManager;
IEnumServerObjectConfigurationInfo enumConfigInfo =
    serverObjectManager.GetConfigurationInfos();

IServerObjectConfigurationInfo configInfo=enumConfigInfo.Next();

while (configInfo != null)
{
    Debug.Print(configInfo.Name + ": " + configInfo.TypeName);
    configInfo=enumConfigInfo.Next();
}
The IGISServerConnection2.Connect2 method requires that the operating system identity of the calling thread be that of a local user in the agsadmin group. If the account running the application is not a member of this group, the Connect2 method on IGISServerConnection2 returns an error.
If the user account making the call is a member of the agsadmin user group on the GIS server, the ServerObjectAdmin property on IGISServerConnection can be used to get a reference on ServerObjectAdmin. If the user account running the application is not in the agsadmin user group, the ServerObjectAdmin property returns an error.
The identity of the calling thread is the identity of the application making the call or an identity that is impersonated for the duration of the call. For example, the ArcGIS Server Web services handler impersonates the AGSWebServices user in the agsadmin group when creating connections to the GIS server (the SOM). This allows the Web services handler to pass in the user identity and role of the authenticated Web services caller to the SOM as the external user on whose behalf work is being done.
The UserInfo string, used as an argument to the IGISServerConnection2.Connect2 method, is of the form X;R1,R2,R3 where the following is true:
  • X is the user name
  • R1,R2,R3 are roles in which the user is a member
If the user name X is empty, the leading ";" character is not necessary. Any leading spaces will be stripped off of either the user name or any of the roles.
The following code shows how a local (and therefore trusted) application can use the IGISServerConnection2 interface to connect to the server on behalf of an external user named John in the Planner and Editor roles:
[C#]
string userName="John";
string roles="Planner,Editor";
string userInfo=userName + ";" + roles;
string serverName="myServer";

IGISServerConnection2 connection2=new GISServerConnection();
connection2.Connect2(userInfo, serverName);
IServerObjectManager som=connection2.ServerObjectManager;

// Note: Attempts to call CreateServerContext through the SOM on a server object 
// configuration (GIS service) for which the specified roles (Planner, Editor) do not 
// have access will result in an Access Denied error.
A local application can also create a GIS server connection without specifying an external user at connect time. The application can then use the IPermissionsManager interface to query the SOM for the permissions of specified roles on resources (configurations). At this time the only operation supported is "*".
The principal string, used as an argument to several methods that administer role-based security, is of the form R1,R2,R3 where R1,R2,R3 are roles.
Additionally, the following reserved roles have special meaning:
  • "?" Anonymous—A role that represents any anonymous user that has neither credentials recorded in the user store nor a supplied token.
  • "@" Authenticated—A super role that includes all users with explicit credentials recorded in the user store.
  • "*" Everyone—A super role that includes all authenticated users and all anonymous users.
The following code example illustrates how a local application can use the IGISServerConnection, IServerObjectManager, and IPermissionsManager interfaces to check whether the Planner and Editor roles have permission to perform an operation on the USA GIS Service in the Countries folder:
[C#]
string roles="Planner,Editor";
string serverName="myServer";
string resourceName="Countries/USA.MapServer";
string operation="*";

IGISServerConnection connection=new GISServerConnection();
connection.Connect(serverName);

IServerObjectManager som=connection.ServerObjectManager;
IPermissionsManager permissionsManager=(IPermissionsManager)som;

if (permissionsManager.CheckPermission(roles, resourceName, operation))
{
    Debug.Print("Access Allowed.");
}

else
{
    Debug.Print("Access Denied. The " + resourceName + 
        " resource does not allow the " + operation + " operation for the " + roles 
        + "  role(s).");
}
The IPermissionsAdmin interface allows a local application to change the permissions on a resource. To enable role-based security on the GIS server, use IServerObjectAdmin4. Permissions do not go into effect until security is enabled. The enabling of security is a one-way operation via the ArcGIS Server Manager interface.
If you disable security through the application programming interface (API) with a call to IPermissionsAdmin.IsSecurityEnabled=false, you will have exposed all of your Web services to the public Internet and security will be breached. Disable security at your own risk.
The following code demonstrates acquiring an IPermissionsAdmin interface to change permissions on a resource. Specifically, the Planners and Editors roles will be allowed access to perform all operations on the USA MapService in the Countries GIS Service folder of the ArcGIS Server machine myServer. Security is then enabled on the GIS server.
[C#]
string serverName="myServer";
string roles="Planners,Editors";
string resourceName="Countries/USA.MapServer";
string operation="*";

IGISServerConnection connection=new GISServerConnection();
connection.Connect(serverName);

IServerObjectAdmin4 soa=(IServerObjectAdmin4)connection.ServerObjectAdmin;
IPermissionsAdmin permissionsAdmin=(IPermissionsAdmin)soa;

// Allow roles all operations on resourceName.
permissionsAdmin.AllowPermission(roles, resourceName, operation);

// Enable role-based security on the serverName server.
permissionsAdmin.IsSecurityEnabled=true;

Server consumer objects

When developing applications that connect to a GIS server, you need to be able to access objects running in the server and create objects in the server for your application's use. If the user name your application runs as is a member of the agsusers user group on the GIS server, then that application is able to connect to the GIS server using the GISServerConnection object and can get a reference to the set of objects that provide the application the ability to make use of ArcObjects running in the server.
The following illustration shows the Server Consumer Objects object model diagram:
ServerObjectManager
The ServerObjectManager class provides access to information about the GIS server to non-administrators and creates ServerContexts for use by applications. Any application that runs as a user account in the agsusers user group on the GIS server can use the IGISServerConnection interface to connect to the GIS server and to get a reference to the ServerObjectManager.
Use the IServerObjectManager interface to create and use server objects when your application connects to the GIS server. The IServerObjectManager interface has the necessary methods for an application to get the collection of server object configurations, server object types, and server directories configured in the server as ServerObjectConfigurationInfo, ServerObjectTypeInfo, and ServerDirectoryInfo objects, respectively.
IServerObjectManager2 extends IServerObjectManager with a method to get the collection of server object extension (SOE) types registered with the GIS server for a particular server object type, such as ServerObjectExtensionTypeInfo objects and the SystemInfo property. The SystemInfo property returns a PropertySet containing properties indicating the operating system name and message version of the GIS server.
The following code example shows how you can connect to a GIS server and get its system info:
[VB.NET]
Dim connection As IGISServerConnection=New GISServerConnectionClass()
connection.Connect("server_name")

Dim som As IServerObjectManager2=TryCast(connection.ServerObjectManager, IServerObjectManager2)
Dim props As IPropertySet=som.SystemInfo

Dim objkeys As Object
Dim objvalues As Object
Dim Keys As String()
Dim vals As Object()
props.GetAllProperties(objkeys, objvalues)
Keys=CType(objkeys, String())
vals=CType(objvalues, Object())

For i As Integer=0 To props.Count - 1
    Console.WriteLine(Keys(i) & ": " & vals(i))
Next i
[C#]
IGISServerConnection connection=new GISServerConnectionClass();
connection.Connect("server_name");

IServerObjectManager2 som=connection.ServerObjectManager as IServerObjectManager2;
IPropertySet props=som.SystemInfo;

object objkeys=null;
object objvalues=null;
string[] keys=null;
object[] vals=null;
props.GetAllProperties(out objkeys, out objvalues);
keys=(string[])objkeys;
vals=(object[])objvalues;

for (int i=0; i < props.Count; i++)
{
    Console.WriteLine(keys[i] + ": " + vals[i]);
}
The CreateServerContext method on IServerObjectManager is used to get a reference to a context on the server. A context is a process managed by the server within which a server object runs. You can use CreateServerContext to create a context based on a server object configuration, or you can create empty contexts solely for the purpose of creating ArcObjects on the fly within the server.
When using CreateServerContext to create a context based on a server object configuration, if the server object configuration is pooled, you may get a reference to a context that already exists and is running in the server. When you have completed that context, it is important to release it explicitly by calling the ReleaseContext method on IServerContext to return it to the pool. When using CreateServerContext to create a context based on a nonpooled server object configuration or when creating an empty context, a new context is created on the server. You still need to call ReleaseContext when you are finished using it, and the context is destroyed on the server.
The following code example shows how to connect to the GIS server called myServer, create a server context based on the RedlandsMap server object configuration, get a reference to the RedlandsMap MapServer object running in the context, and print its DefaultMapName property. Note the call to ReleaseContext when the use of the context is complete.
[VB.NET]
Dim gisServerConnection As IGISServerConnection=New GISServerConnection()
gisServerConnection.Connect("myServer")

Dim serverObjectManager As IServerObjectManager=gisServerConnection.ServerObjectManager
Dim serverContext As IServerContext=serverObjectManager.CreateServerContext("RedlandsMap", "MapServer")
Dim serverObject As IServerObject=serverContext.ServerObject
Dim mapServer As IMapServer=TryCast(serverObject, IMapServer)

Debug.Print mapServer.DefaultMapName
serverContext.ReleaseContext()
[C#]
IGISServerConnection gisServerConnection=new GISServerConnection();
gisServerConnection.Connect("myServer");

IServerObjectManager serverObjectManager=gisServerConnection.ServerObjectManager;
IServerContext serverContext=serverObjectManager.CreateServerContext("RedlandsMap",
    "MapServer");
IServerObject serverObject=serverContext.ServerObject;
IMapServer mapServer=serverObject as IMapServer;

Debug.Print(mapServer.DefaultMapName);
serverContext.ReleaseContext();
The following code example shows how to create an empty server context and, within that context, create a new polygon and print its area. Note the call to ReleaseContext when use of the context is complete.
[VB.NET]
Dim gisServerConnection As IGISServerConnection=New GISServerConnection()
gisServerConnection.Connect("myServer")
Dim serverObjectManager As IServerObjectManager
serverObjectManager=gisServerConnection.ServerObjectManager
Dim serverContext As IServerContext=serverObjectManager.CreateServerContext(String.Empty, String.Empty)
' Create a new polygon in the server context.
Dim pointColl As IPointCollection=CType(serverContext.CreateObject("esriGeometry.Polygon"), IPointCollection)
' Create the points in the server context.
Dim point(4) As IPoint
Dim i As Integer
For i=0 To 3
    point(i)=CType(serverContext.CreateObject("esriGeometry.Point"), IPoint)
Next
point(0).PutCoords(0, 0)
point(1).PutCoords(10, 0)
point(2).PutCoords(10, 10)
point(3).PutCoords(0, 10)
'Add the points to the polygon.
pointColl.AddPoints(4, point(0))
Dim area As IArea=TryCast(pointColl, IArea)
Debug.Print(CStr(area.Area))
serverContext.ReleaseContext()
[C#]
IGISServerConnection gisServerConnection=new GISServerConnection();
gisServerConnection.Connect("myServer");

IServerObjectManager serverObjectManager=null;
serverObjectManager=gisServerConnection.ServerObjectManager;
IServerContext serverContext=serverObjectManager.CreateServerContext(string.Empty,
    string.Empty);

// Create a new polygon in the server context.
IPointCollection pointColl=(IPointCollection)(serverContext.CreateObject(
    "esriGeometry.Polygon"));

// Create the points in the server context.
IPoint[] point=new IPoint[5];
int i=0;
for (i=0; i <= 3; i++)
{
    point[i]=(IPoint)(serverContext.CreateObject("esriGeometry.Point"));
}

point[0].PutCoords(0, 0);
point[1].PutCoords(10, 0);
point[2].PutCoords(10, 10);
point[3].PutCoords(0, 10);

//Add the points to the polygon.
pointColl.AddPoints(4, ref point[0]);
IArea area=pointColl as IArea;
Debug.Print(System.Convert.ToString(area.Area));
serverContext.ReleaseContext();
Server contexts
A server context is a reserved space within the server dedicated to a set of running objects. GIS server objects also reside in a server context. When developing applications with ArcGIS for Server, all ArcObjects components that your application creates and uses reside within a server context. To obtain a server object, get a reference to its context, then get the server object from the context.
You get a server context by calling the CreateServerContext method on IServerObjectManager.
IServerContext contains methods for creating and managing objects running within ServerContext. You can get at the server object running within a server context using the ServerObject property on IServerContext.
The following code example shows how to create a server context and get a reference to the MapServer server object running in the server context:
[VB.NET]
Dim serverContext As IServerContext=serverObjectManager.CreateServerContext("RedlandsMap", "MapServer")
Dim mapServer As IMapServer=serverContext.ServerObject
[C#]
IServerContext serverContext=serverObjectManager.CreateServerContext("RedlandsMap",
    "MapServer");
IMapServer mapServer=serverContext.ServerObject;
You can also create empty server contexts. You can use an empty context to create ArcObjects components on the fly within the server to perform ad hoc GIS processing. The following code example shows how to create an empty server context:
[VB.NET]
Dim serverContext As IServerContext=serverObjectManager.CreateServerContext(String.Empty, String.Empty)
Dim workspaceFactory As IWorkspaceFactory=serverContext.CreateObject("esriDataSourcesGDB.SdeWorkspaceFactory")
[C#]
IServerContext serverContext=serverObjectManager.CreateServerContext(string.Empty,
    string.Empty);
IWorkspaceFactory workspaceFactory=serverContext.CreateObject(
    "esriDataSourcesGDB.SdeWorkspaceFactory");
All ArcObjects components that your application uses should be created within a server context using the CreateObject method on IServerContext. Also, objects that are used together should be in the same context. For example, if you create a Point object to use in a spatial selection to query features in a feature class, the point should be in the same context as the feature class.
ArcGIS for Server applications should not use New to create ArcObjects but should always create objects by calling CreateObject on ServerContext.
The following code example is incorrect:
[VB.NET]
Dim point As IPoint=New Point()
[C#]
IPoint point=new Point();
The following code example is correct:
[VB.NET]
Dim point As IPoint=serverContext.CreateObject("esriGeometry.Point")
[C#]
IPoint point=serverContext.CreateObject("esriGeometry.Point");
When your application is finished working with a server context, it must release it back to the server by calling the ReleaseContext method. If you allow the context to go out of scope without explicitly releasing it, it remains in use and is unavailable to other applications until it is garbage collected. Once a context is released, the application can no longer make use of any objects in that context. This includes both objects that you may have obtained from the context or objects that you created in the context. The following code example shows this:
[VB.NET]
Dim serverContext As IServerContext=serverObjectManager.CreateServerContext("RedlandsMap", "MapServer")
Dim mapServer As IMapServer=serverContext.ServerObject
' Do something with the object.
serverContext.ReleaseContext()
[C#]
IServerContext serverContext=serverObjectManager.CreateServerContext("RedlandsMap",
    "MapServer");
IMapServer mapServer=serverContext.ServerObject;
// Do something with the object.
serverContext.ReleaseContext();
The IServerContext interface has a number of methods to help you manage the objects you create within server contexts. The following code example is a description of how and when to use these methods. Use the CreateObject method when you need to create an object for use in your application.
[VB.NET]
Dim pointCollection As IPointCollection=serverContext.CreateObject("esriGeometry.Polygon")
[C#]
IPointCollection pointCollection=serverContext.CreateObject("esriGeometry.Polygon")
    ;
CreateObject returns a proxy to the object that's in the server context. Your application can use the proxy as if the object was created locally within its process. If you call a method on the proxy that hands back another object, that object is in the server context, and your application is handed back a proxy to that object. In the preceding example, if you get a point from the point collection using IPointCollection.Point(), the point returned is in the same context as the point collection.
If you add a point to the point collection using IPointCollection.AddPoint(), the point should be in the same context as the point collection as shown in the following code example:
[VB.NET]
Dim pointCollection As IPointCollection=serverContext.CreateObject("esriGeometry.Polygon")
Dim point As IPoint=serverContext.CreateObject("esriGeometry.Point")
point.X=1
point.Y=1
pointCollection.AddPoint (point)
[C#]
IPointCollection pointCollection=serverContext.CreateObject("esriGeometry.Polygon")
    ;
IPoint point=serverContext.CreateObject("esriGeometry.Point");
point.X=1;
point.Y=1;
pointCollection.AddPoint(point);
You should not directly use objects in a server context with local objects in your application and vice versa. You can indirectly use objects or make copies of them. For example, if you have a Point object in a server context, you can get its x,y properties and use them with local objects or to create a new local point. Do not directly use the point in the server context as, for example, the geometry of a local graphic element object.
Consider the following code examples. In each example, assume that objects with Remote in their names are objects in a server context as in the following:
[VB.NET]
Dim remotePoint As IPoint=serverContext.CreateObject("esriGeometry.Point")
[C#]
IPoint remotePoint=serverContext.CreateObject("esriGeometry.Point");
While objects with Local in their name are objects created locally as in the following code example:
[VB.NET]
Dim localPoint As IPoint=New Point()
[C#]
IPoint localPoint=New Point();
You cannot set a local object to a remote object. See the following code example:
[VB.NET]
' This is incorrect:
localPoint=remotePoint

' This is also incorrect:
localElement.Geometry=remotePoint
[C#]
//This is incorrect:
localPoint=remotePoint;

//This is also incorrect:
localElement.Geometry=remotePoint;
Do not set a local object or a property of a local object to be an object obtained from a remote object. See the following code example:
[VB.NET]
' This is incorrect:
localPoint=remotePointCollection.Point(0)
[C#]
// This is incorrect:
localPoint=remotePointCollection.Point(0);
When calling a method on a remote object, do not pass in local objects as parameters. See the following code example:
[VB.NET]
' This is incorrect:
remoteWorkspace=remoteWorkspaceFactory.Open(localPropertySet, 0)
[C#]
// This is incorrect:
remoteWorkspace=remoteWorkspaceFactory.Open(localPropertySet, 0);
You can get simple data types—double, long, string, and so on—that are passed by value from a remote object and use them as properties of a local object. See the following code example:
[VB.NET]
' This is acceptable:
localPoint.X=remotePoint.X
localPoint.Y=remotePoint.Y
[C#]
// This is acceptable:
localPoint.X=remotePoint.X localPoint.Y=remotePoint.Y
SetObject and GetObject allow you to store references to objects in the server context. A context contains a dictionary that you can use to store objects that you create within the context. This dictionary is valid only as long as you hold on to the server context, and it is emptied when you release the context. You can use this dictionary to share objects created within a context between different parts of your application that have access to the context. The following illustration shows this dictionary:
SetObject adds objects to the dictionary, and GetObject retrieves them. An object that is set in the context is available until it is removed (by calling Remove or RemoveAll) or until the context is released as shown in the following code example:
[VB.NET]
Dim pointCollection As IPointCollection=serverContext.CreateObject("esriGeometry.Polygon")
serverContext.SetObject ("myPoly", pointCollection)
Dim poly As IPolygon=serverContext.GetObject("myPoly")
[C#]
IPointCollection pointCollection=serverContext.CreateObject("esriGeometry.Polygon")
    ;
serverContext.SetObject("myPoly", pointCollection);
IPolygon poly=serverContext.GetObject("myPoly");
Use the Remove and RemoveAll methods to remove objects from a context that has been set using SetObject. Once an object is removed, a reference can no longer be made to it using GetObject. If you do not explicitly call Remove or RemoveAll, you cannot get references to objects set in the context after the context has been released as shown in the following code example:
[VB.NET]
serverContext.Remove ("myPoly")
[C#]
serverContext.Remove("myPoly");
The SaveObject and LoadObject methods allow you to serialize objects in the server context to strings, then deserialize them back into objects. Any object that supports IPersistStream can be saved and loaded using these methods. These methods allow you to copy objects between contexts. For example, if you use a GeocodeServer object to locate an address and you want to draw the point that GeocodeAddress returns on your map, you need to copy the point to your MapServer's context as shown in the following code example:
[VB.NET]
Dim serverContext As IServerContext=SOM.CreateServerContext("RedlandsMap", "MapServer")
Dim serverContext2 As IServerContext=SOM.CreateServerContext("RedlandsGeocode", "GeocodeServer")

Dim gcServer As IGeocodeServer=TryCast(serverContext2.ServerObject, IGeocodeServer)

Dim propertySet As IPropertySet=TryCast(serverContext2.CreateObject("esriSystem.PropertySet"), IPropertySet)

propertySet.SetProperty("Street", "380 New York St")
    Dim results As IPropertySet=gcServer.GeocodeAddress(propertySet, Nothing)
    Dim point As IPoint=TryCast(results.GetProperty("Shape"), IPoint)
    
    ' Copy the point to the MapServer's context.
    Dim stringPoint As String=serverContext2.SaveObject(point)
    Dim pointCopy As IPoint=TryCast(serverContext.LoadObject(stringPoint), IPoint)
[C#]
IServerContext serverContext=SOM.CreateServerContext("RedlandsMap", "MapServer");
IServerContext serverContext2=SOM.CreateServerContext("RedlandsGeocode", 
    "GeocodeServer");

IGeocodeServer gcServer=serverContext2.ServerObject as IGeocodeServer;

IPropertySet propertySet=serverContext2.CreateObject("esriSystem.PropertySet")as
    IPropertySet;
propertySet.SetProperty("Street", "380 New York St");
IPropertySet results=gcServer.GeocodeAddress(propertySet, null);
IPoint point=results.GetProperty("Shape")as IPoint;

// Copy the point to the MapServer's context.
string stringPoint=serverContext2.SaveObject(point);
IPoint pointCopy=serverContext.LoadObject(stringPoint)as IPoint;
The process for copying objects between server contexts using SaveObject and LoadObject is as follows:
  1. The client application gets or creates an object within a server context.
  2. The application uses the SaveObject method on the object's context to serialize the object as a string that is held in the application's session state.
  3. The client application gets a reference to another server context and calls the LoadObject method, passing in the string created by SaveObject. LoadObject creates a new instance of the object in the new server context.
This process is shown in the following illustration:
Another use of these methods is managing state in your application while making stateless use of a pooled server object. An example of this is in a mapping application. The initial session state for all users is the same and is equal to the map description for the map server object. Each user can then change map description properties, such as the extent and layer visibility, which need to be maintained in the user's session state. The application does this by saving a serialized map description as part of each user's session state. Using the serialized string representation allows the application to take advantage of the standard session state management facilities of the Web server. The application uses the LoadObject and SaveObject methods to reconstitute the session's map description whenever it needs to make edits to it in response to user changes or whenever it needs to pass the map descriptor to the map server object for drawing the map according to the user's specifications. This process is shown in the following illustration:
Server objects
ServerObject is a coarse-grained ArcObjects component and a high-level object that simplifies the programming model for certain operations and hides the fine-grained ArcObjects components that do the work. Server objects support coarse-grained interfaces that support methods that do large units of work, such as draw a map or geocode a set of addresses. ServerObjects also have Simple Object Access Protocol (SOAP) interfaces, which makes it possible to expose server objects as Web services that can be consumed by clients across the Internet.
ArcGIS Server has the following ServerObjects:
  • MapServer is a coarse-grained server object that provides access to the contents of a map document and methods for querying and drawing the map.
  • GeocodeServer is a coarse-grained server object that provides access to an address locator and methods for single address and batch geocoding.
  • GeoDataServer is a coarse-grained server object that provides access to a geodatabase and methods for data management.
  • GlobeServer is a coarse-grained server object that provides access to a globe document and methods for displaying the globe.
  • GPServer is a coarse-grained server object that provides access to one or more geoprocessing tools and methods for executing those tools in the GIS server.
  • ImageServer is a coarse-grained server object that provides access to a raster data source and methods for displaying and extracting the raster.
  • GeometryServer is a coarse-grained server object that provides access to methods that support geometric operations in the Web Application Developer Framework (ADF).
Server objects and their extensions can be used in ArcGIS for Server applications, in which case the server object manager creates and manages instances of the server object and its extensions in process running within the server. You get a reference to a server object running in the GIS server from its ServerContext.
Because server objects are Component Object Model (COM) objects, they and their extensions can be used in ArcGIS Engine or ArcGIS for Desktop applications. ServerObjectFactory allows you to create an instance of a server object and any enabled extensions for use in such applications.
Use the CreateServerObject method on IServerObjectFactory to create an instance of a server object.
The following code example shows the use of IServerObjectFactory to create a MapServer object and an associated SOE called MySOE outside the server environment:
[VB.NET]
Dim serverObjectFactory As ServerObjectFactory=New ServerObjectFactory()
Dim serverObject As IServerObject=serverObjectFactory.CreateServerObject("43E4F6B6-7B17-4536-B7CF-C0454EBB0F5A", "SomeMap", "MapServer")
Dim extensionMgr As IServerObjectExtensionManager=CType(serverObject, IServerObjectExtensionManager)
Dim serverObjectExtension As IServerObjectExtension=extensionMgr.FindExtensionByName("MySOE")

' Set a property called PropName to the Value for your server object extension called MySOE.
Dim mySOE As IMySOE=TryCast(soe, IMySOE)
Dim propSet As IPropertySet=New PropertySet()
propSet.SetProperty("PropName", "Value")

Dim objConstruct As IObjectConstruct=TryCast(mySOE, IObjectConstruct)
objConstruct.Construct(propSet)
[C#]
ServerObjectFactory serverObjectFactory=new ServerObjectFactory();
IServerObject serverObject=serverObjectFactory.CreateServerObject(
    "43E4F6B6-7B17-4536-B7CF-C0454EBB0F5A", "SomeMap", "MapServer");
IServerObjectExtensionManager extensionMgr=serverObject as
    IServerObjectExtensionManager;
IServerObjectExtension serverObjectExtension=extensionMgr.FindExtensionByTypeName(
    "MySOE");

// Set a property called PropName to the Value for your server object extension called MySOE.
IMySOE mySOE=(IMySOE)serverObjectExtension;
IPropertySet propSet=new PropertySet();
propSet.SetProperty("PropName", "Value");

IObjectConstruct objConstruct=mySOE as IObjectConstruct;
objConstruct.Construct(propSet);
IServerObject is an interface supported by all server objects. The IServerObject interface is returned as the ServerObject property on IServerContext. The IServerObject interface has properties to indicate the name and type of the server object configuration that created the server object. You can query this interface for interfaces supported by the server object type, such as IMapServer for a MapServer object or IGeocodeServer for a GeocodeServer object.
The following code example shows how to connect to a GIS server, create a server context based on a server object configuration, and use the ServerObject property to get the IServerObject interface on the server context's server object:
[VB.NET]
Dim gisServerConnection As IGISServerConnection=New GISServerConnection()
gisServerConnection.Connect ("padisha")

Dim SOM As IServerObjectManager=gisServerConnection.ServerObjectManager
Dim context As IServerContext=SOM.CreateServerContext("MyMapServer", "MapServer")
Dim serverObject As IServerObject=context.ServerObject
Dim mapServer As IMapServer=TryCast(serverObject, IMapServer)

' Do something with the MapServer.
context.ReleaseContext()
[C#]
IGISServerConnection gisServerConnection=new GISServerConnection();
gisServerConnection.Connect("padisha");

IServerObjectManager SOM=gisServerConnection.ServerObjectManager;
IServerContext context=SOM.CreateServerContext("MyMapServer", "MapServer");
IServerObject serverObject=context.ServerObject;
IMapServer mapServer=serverObject as IMapServer;

// Do something with the MapServer.
context.ReleaseContext();
Server object extensions
Some server objects have extensions that extend their base functionality for more specialized uses. Each type of server object can have a set of extensions that can be enabled or disabled based on its configuration. For example, the MapServer server object includes a network analysis SOE that can be enabled for map servers that include network analysis layers and are intended for use in applications that include routing, service area, or some other network analysis type of functionality. ArcGIS for Server includes a number of SOEs out of the box, and you can extend ArcGIS for Server by writing your own SOEs.
SOEs also have SOAP interfaces for handling SOAP requests to execute methods and returning results as SOAP responses. This support for SOAP request handling makes it possible to expose SOEs as Web services that can be consumed by clients across the Internet.
ArcGIS for Server includes the following SOEs to the MapServer:
  • NAServer—Extends the MapServer server object to include network analysis functions for operations such as routing and service area analysis
  • MobileServer—Extends the MapServer server object to allow mobile devices to extract data from a map on the server
  • WMSServer—Extends the MapServer server object to provide the capabilities required for publishing the MapServer as an Open Geospatial Consortium, Inc. (OGC), Web Map Service (WMS)
  • KmlServer—Extends the MapServer server object to return a stream of vector and raster layers to any client capable of reading compressed Keyhole Markup Language (KMZ) [KML] documents
IServerObjectExtensionManager is an interface supported by all server objects. Once you have a reference to a server object, you can use the methods on IServerObjectExtensionManager to find enabled extensions either by type name (FindExtensionByTypeName) or by class identifier (CLSID) (FindExtensionByCLSID). Once you have a reference to the SOE, you can cast to any of its interfaces.
The following code example shows how to get the NAServer extension to a MapServer and find the network analysis layers in the map:
[VB.NET]
Dim serverContext As IServerContext=SOM.CreateServerContext("usa", "MapServer")
Dim mapServer As IMapServer=CType(serverContext.ServerObject, IMapServer)Dim soExtManager As IServerObjectExtensionManager=TryCast(mapServer, IServerObjectExtensionManager)
Dim soExt As IServerObjectExtension=soExtManager.FindExtensionByTypeName("NAServer")
Dim naServer As INAServer=TryCast(soExt, INAServer)
Dim layers As String()=naServer.GetNALayerNames(esriNAServerLayerType.esriNAServerRouteLayer)
serverContext.ReleaseContext()
[C#]
IServerContext serverContext=SOM.CreateServerContext("usa", "MapServer");
IMapServer mapServer=(IMapServer)serverContext.ServerObject;
IServerObjectExtensionManager soExtManager=mapServer as
    IServerObjectExtensionManager;
IServerObjectExtension soExt=soExtManager.FindExtensionByTypeName("NAServer");
INAServer naServer=soExt as INAServer;
string[] layers=naServer.GetNALayerNames
    (esriNAServerLayerType.esriNAServerRouteLayer);
serverContext.ReleaseContext();
Info classes
The Server object library's Info classes provide read-only access to the properties of server directories, server types, and server object configurations to users and developers who are not administrators. These properties are necessary for developing applications using the GIS server.
Each Info class has a corresponding class that is only accessible to administrators (users in the agsadmin user group), which exposes the properties of the Info object with read/write access as well as additional properties as shown in the following list:
  • The ServerObjectConfigurationInfo class provides read-only access to some of the properties of a server object configuration.
  • The ServerObjectTypeInfo class provides read-only access to some of the properties of a server object type.
  • The ServerObjectExtensionTypeInfo class provides read-only access to some of the properties of an SOE type.
  • A ServerDirectoryInfo object is an Info object that describes the properties of a server directory.
The GIS server manages a set of server directories. A server directory is a location on a file system that the GIS server is configured to clean up files it writes. The ServerDirectoryInfo class gives users and developers who are not administrators access to the list of server directories and the set of their properties that are necessary for programming applications that use them as locations to write output. You can get information about server directories using the GetServerDirectoryInfos method on IServerObjectManager to get the IServerDirectoryInfo interface.
Files in a server directory can be cleaned up based on file age or when the file was last accessed. The maximum file age or time since last accessed is a property of a server directory. If the CleaningMode, which is a property of type esriServerDirectoryCleaningMode, is esriSDCAbsolute, then all files created by the GIS server that are older than the maximum age are automatically cleaned up by the GIS server. If the CleaningMode is esriSDCSliding, then all files created by the GIS server that have not been accessed for a duration defined by maximum age are automatically cleaned up by the GIS server.
When creating files in a server directory, they must be prefixed with _ags_ to be cleaned up by the GIS server. Any files in a server directory not prefixed with _ags_ will not be cleaned up. IServerDirectoryInfo provides read–only access to a subset of the server directory's properties. These properties include the following:
  • Path—Physical path of the directory on disk.
  • URL—Uniform resource locator (URL) of the virtual directory corresponding to the physical directory.
  • Description—Description of the server directory.
  • CleaningMode—Indicates whether the directory is cleaned by file age (esriSDCAbsolute), by last accessed (esriSDCSliding), or if its contents are not cleaned up (esriSDCNone).
  • MaxFileAge—Indicates the maximum age or the maximum time since last accessed that files can be in the server directory before they are cleaned up.
The preceding properties are those necessary for developers of server applications to make use of the various GIS servers' server directories.
The following code example shows how to list the server directories of a GIS server using the ServerDirectoryInfo class:
[VB.NET]
Dim serverConn As IGISServerConnection=New GISServerConnection()
serverConn.Connect ("padisha")

Dim SOM As IServerObjectManager=serverConn.ServerObjectManager
Dim enumSDirInfo As IEnumServerDirectoryInfo=SOM.GetServerDirectoryInfos
Dim serverDirInfo As IServerDirectoryInfo=enumSDirInfo.Next()

Do Until serverDirInfo Is Nothing
    Debug.Print (serverDirInfo.Path)
    serverDirInfo=enumSDirInfo.Next()
Loop
[C#]
IGISServerConnection serverConn=new GISServerConnection();
serverConn.Connect("padisha");

IServerObjectManager SOM=serverConn.ServerObjectManager;
IEnumServerDirectoryInfo enumSDirInfo=SOM.GetServerDirectoryInfos();
IServerDirectoryInfo serverDirInfo=enumSDirInfo.Next();

while (serverDirInfo != null)
{
    Debug.Print(serverDirInfo.Path);
    serverDirInfo=enumSDirInfo.Next();
}
A ServerObjectConfigurationInfo object is an Info object that describes the properties of a server object configuration.
The GIS server manages a set of server objects running across one or more host (container) machines. How those server objects are configured and run is defined by a set of server object configurations. The ServerObjectConfigurationInfo class gives users and developers who are not administrators access to the list of server object configurations and the set of their properties that are necessary for programming applications with them. You can get information about server object configurations using the GetConfigurationInfos method on IServerObjectManager to get the IServerObjectConfigurationInfo interface. The GetConfigurationInfos method returns only server object configurations that are started.
IServerObjectConfigurationInfo provides read–only access to a subset of the server object configuration's properties. These properties include the following:
  • Name—Name of the server object configuration.
  • TypeName—Type of server object configuration (for example, MapServer or GeocodeServer).
  • Description—Description of the server object configuration.
  • IsPooled—Indicates whether the server objects described by this configuration are pooled or nonpooled.
The preceding properties are those necessary for developers of server applications to use the various server objects configured on the GIS server.
The following code example shows how to connect to a GIS server and use the IServerObjectConfigurationInfo interface to print out the name and type of all the server object configurations:
[VB.NET]
Dim gisServerConnection As IGISServerConnection=New GISServerConnection()
gisServerConnection.Connect ("myServer")

Dim SOM As IServerObjectManager=gisServerConnection.ServerObjectManager
Dim enumSOCInfo As IEnumServerObjectConfigurationInfo=SOM.GetConfigurationInfos
Dim socInfo As IServerObjectConfigurationInfo=enumSOCInfo.Next()

Do Until socInfo Is Nothing
    Debug.Print (socInfo.Name & ": " & socInfo.TypeName)
    socInfo=(enumSOCInfo.Next)
Loop
[C#]
IGISServerConnection gisServerConnection=new GISServerConnection();
gisServerConnection.Connect("myServer");

IServerObjectManager SOM=gisServerConnection.ServerObjectManager;
IEnumServerObjectConfigurationInfo enumSOCInfo=SOM.GetConfigurationInfos();
IServerObjectConfigurationInfo socInfo=enumSOCInfo.Next();

while (socInfo != null)
{
    Debug.Print(socInfo.Name + ": " + socInfo.TypeName);
    socInfo=(enumSOCInfo.Next());
}
IServerObjectConfigurationInfo2 extends this interface to provide the names of all enabled SOEs for a particular configuration. Only those SOEs that are enabled for this configuration are returned by the Extensions property. To get a complete list of all SOEs that are supported for a particular type of server object, use the GetExtensionTypeInfos method on IServerObjectManager2.
A ServerObjectTypeInfo object is an Info object that describes the properties of a server object type.
The ServerObjectTypeInfo class gives users and developers who are not administrators access to the list of server object types and the set of their properties that are necessary for programming applications. You can get information about server object types using the GetTypeInfos method on IServerObjectManager to get the IServerObjectTypeInfo interface.
IServerObjectTypeInfo provides read–only access to a subset of the server object type's properties. These properties include the following:
  • Name—Name of the server object type (for example, MapServer or GeocodeServer).
  • Description—Description of the server object type.
A ServerObjectExtensionTypeInfo object is an Info object that describes the properties of an SOE type.
The ServerObjectExtensionTypeInfo class gives users and developers who are not administrators access to the list of SOE types and the set of their properties that are necessary for programming applications. You can get information about SOE types using the GetExtensionTypeInfos method on IServerObjectManager2 to get the IServerObjectExtensionTypeInfo interface.
IServerObjectExtensionTypeInfo provides read–only access to a subset of the SOE type's properties. These properties include the following:
  • Name—Name of the SOE type (for example, NetworkAnalysis or OGCWebService).
  • Description—Description of the SOE type.

Server administration objects

When developing applications that connect to a GIS server for the purposes of administering the GIS server and its server objects, you need to have access to the objects for administering these aspects of the GIS server. If your application runs as a user account in the agsadmin user group on the GIS server, then that application will be able to connect to the GIS server using the GISServerConnection object and can get a reference to the set of objects that provides the ability for the application to administrate the GIS server and its server objects.
The following illustration shows the server administration objects object model diagram:
Applications that use ArcObjects running in the server do not require access to the administration objects.
The ServerObjectAdmin class administrates a GIS server. Any application that runs as a user account in the agsadmin user group on the GIS server can use the IGISServerConnection interface to connect to the GIS server and to get a reference to ServerObjectAdmin. If the user account is not part of the agsadmin user group, the ServerObjectAdmin property on IGISServerConnection returns an error. Applications that are running as accounts that can connect to the server but are not part of the agsadmin user group can use the ServerObjectManager property on IGISServerConnection to get a reference on ServerObjectManager.
Use ServerObjectAdmin to administrate the set of server object configurations and types associated with the server as well as to administer aspects of the server itself. The following administration functionality of the GIS server is provided by ServerObjectAdmin.
Administer server object configurations. For example: 
  • Add and delete server object configurations.
  • Update a server object configuration's properties.
  • Start, stop, and pause server object configurations.
  • Report the status of a server object configuration.
  • Get all server object configurations and their properties.
  • Get all server object types and their properties.
  • Enable and disable SOEs for a server object.
  • Add and remove SOE types.
Administer the following aspects of the server itself:
  • Enable and disable the server to suspend access from client applications.
  • Start and stop the server.
  • Add and remove server container machines.
  • Get all server container machines.
  • Add and remove server directories.
  • Get all server directories.
  • Get all SOE types.
  • Add and remove SOE types.
  • Configure the server's logging properties.
  • Get a reference to the server's log.
  • Get statistics about events in the server.
  • Get information about the system on which the server is running.
  • Enable and disable role-based security.
  • Allow and deny roles access to operations on resources (folders and services).
You can use IServerObjectAdmin to administrate either the server's set of server object configurations and server object types or the aspects of the server itself, such as the list of machines that can host server objects. If your application is connecting to the server to use objects in the server, use the IServerObjectManager interface.
Administer server object configurations
The AddConfiguration method adds a ServerObjectConfiguration to your GIS server. A ServerObjectConfiguration can be created using the CreateConfiguration method. Use the IServerObjectConfiguration interface to set the various properties of the configuration, then use the AddConfiguration method on IServerObjectAdmin to add the new configuration to the GIS server. Once a configuration is added to the server, you can use StartConfiguration to make it available for applications to use.
The following code example shows how to connect to the GIS server
myServer and use the CreateConfiguration, AddConfiguration, and StartConfiguration methods to create a new geocode server object configuration, add it to the server, and make it available for use:
[VB.NET]
Dim gisServerConnection As IGISServerConnection=New GISServerConnection()
gisServerConnection.Connect ("myServer")
Dim serverObjectAdmin As IServerObjectAdmin=gisServerConnection.ServerObjectAdmin

' Create the new configuration.
Dim configuration As IServerObjectConfiguration=serverObjectAdmin.CreateConfiguration()
configuration.Name="California"
configuration.TypeName="GeocodeServer"

Dim propSet As IPropertySet=configuration.Properties
propSet.SetProperty ("LocatorWorkspacePath", "\\myServer\Geocoding\California")
propSet.SetProperty ("Locator", "California")
propSet.SetProperty ("SuggestedBatchSize", "500")

configuration.IsPooled=True
configuration.MinInstances=1
configuration.MaxInstances=1
configuration.WaitTimeout=10
configuration.UsageTimeout=120

' Add the configuration to the server.
serverObjectAdmin.AddConfiguration(configuration)
[C#]
IGISServerConnection gisServerConnection=new GISServerConnection();
gisServerConnection.Connect("myServer");
IServerObjectAdmin serverObjectAdmin=gisServerConnection.ServerObjectAdmin;

// Create the new configuration.
IServerObjectConfiguration configuration=serverObjectAdmin.CreateConfiguration();
configuration.Name="California";
configuration.TypeName="GeocodeServer";

IPropertySet propSet=configuration.Properties;
propSet.SetProperty("LocatorWorkspacePath", "\\\\myServer\\Geocoding\\California");
propSet.SetProperty("Locator", "California");
propSet.SetProperty("SuggestedBatchSize", "500");

configuration.IsPooled=true;
configuration.MinInstances=1;
configuration.MaxInstances=1;
configuration.WaitTimeout=10;
configuration.UsageTimeout=120;

// Add the configuration to the server.
serverObjectAdmin.AddConfiguration(configuration);
The UpdateConfiguration method updates the ServerObjectConfiguration that is specified when the method is called. You can use the GetConfiguration or GetConfigurations method on IServerObjectAdmin to get a reference to the ServerObjectConfiguration you want to update.
The server object configuration must be stopped before you call UpdateConfiguration. You can use StopConfiguration to stop the server object configuration.
The following code example shows how to connect to the GIS server
myServer and use GetConfiguration to get ServerObjectConfiguration, change its MinInstances property, then update the configuration using the UpdateConfiguration method:
[VB.NET]
Dim gisServerConnection As IGISServerConnection=New GISServerConnection()
gisServerConnection.Connect("myServer")

Dim serverObjectAdmin As IServerObjectAdmin=gisServerConnection.ServerObjectAdmin
Dim serverConfig As IServerObjectConfiguration=serverObjectAdmin.GetConfiguration("RedlandsMap", "MapServer")
serverConfig.MinInstances=3
serverObjectAdmin.UpdateConfiguration(serverConfig)
[C#]
IGISServerConnection gisServerConnection=new GISServerConnection();
gisServerConnection.Connect("myServer");

IServerObjectAdmin serverObjectAdmin=gisServerConnection.ServerObjectAdmin;
IServerObjectConfiguration serverConfig=serverObjectAdmin.GetConfiguration(
    "RedlandsMap", "MapServer");
serverConfig.MinInstances=3;
serverObjectAdmin.UpdateConfiguration(serverConfig);
Use DeleteConfiguration to delete a server object configuration from your GIS server. To call DeleteConfiguration, the server object configuration must be stopped. If it is not stopped, DeleteConfiguration returns an error.
The following code example shows how to stop and delete a server object configuration called RedlandsMap:
[VB.NET]
Dim gisServerConnection As IGISServerConnection=New GISServerConnection()
gisServerConnection.Connect("myServer")

Dim serverObjectAdmin As IServerObjectAdmin=gisServerConnection.ServerObjectAdmin
serverObjectAdmin.StopConfiguration("RedlandsMap", "MapServer")
serverObjectAdmin.DeleteConfiguration("RedlandsMap", "MapServer")
[C#]
IGISServerConnection gisServerConnection=new GISServerConnection();
gisServerConnection.Connect("myServer");

IServerObjectAdmin serverObjectAdmin=gisServerConnection.ServerObjectAdmin;
serverObjectAdmin.StopConfiguration("RedlandsMap", "MapServer");
serverObjectAdmin.DeleteConfiguration("RedlandsMap", "MapServer");
The GetConfigurations method returns an enumeration of all the server object configurations that are configured in the GIS server. The following code example shows how to connect to the GIS server
myServer and print the name and type of all its server object configurations:
[VB.NET]
Dim gisServerConnection As IGISServerConnection=New GISServerConnection()
gisServerConnection.Connect ("myServer")

Dim serverObjectAdmin As IServerObjectAdmin=gisServerConnection.ServerObjectAdmin
Dim enumSOC As IEnumServerObjectConfiguration=serverObjectAdmin.GetConfigurations()
Dim SOC As IServerObjectConfiguration=enumSOC.Next()

Do Until SOC Is Nothing
    Debug.Print (SOC.Name & ": " & SOC.TypeName)
    SOC=enumSOC.Next()
Loop
[C#]
IGISServerConnection gisServerConnection=new GISServerConnection();
gisServerConnection.Connect("myServer");

IServerObjectAdmin serverObjectAdmin=gisServerConnection.ServerObjectAdmin;
IEnumServerObjectConfiguration enumSOC=serverObjectAdmin.GetConfigurations();
IServerObjectConfiguration SOC=enumSOC.Next();

while (SOC != null)
{
    Debug.Print(SOC.Name + ": " + SOC.TypeName);
    SOC=enumSOC.Next();
}
IServerObjectAdmin2 extends IServerObjectAdmin with additional server administration capabilities. Use the Enable and Disable methods to suspend and resume access to the server from client applications. Disabling the server does not affect pooled server objects.
GetExtensionTypes returns a collection of the installed SOEs for a particular server object type, while CreateExtensionType and AddExtensionType allow you to add your own custom SOEs to the server.
The IServerStatus interface provides methods and properties that return the status of server object configurations and server machines. The GetConfigurationStatus method returns a ConfigurationStatus object that reports the number of instances running and in use for the configuration.
The GetMachineStatus method returns a ServerMachineStatus object that supports the IServerMachineStatus interface with properties to get the number of server object instances running on the machine (InstanceCount) and the number currently in use (InstanceInUseCount).
The SOMController class allows you to start and stop the GIS server. Use the methods on ISOMController to check if the server is running and to stop and start the server.
The ServerObjectConfiguration class describes the configuration for a server object that is managed by the GIS server. ServerObjectConfigurations can be added, removed, and modified by users or developers who are members of the agsadmin users group and, therefore, have administrator privileges on the GIS server.
The administrator-level properties of ServerObjectConfiguration are as follows:
A read-only subset of properties of a ServerObjectConfiguration is available to non-administrators via the GISServerConnectionInfo object. These non-administrator-level properties are as follows:
The IServerObjectConfiguration interface is a read/write interface on a server object configuration that allows administrators to configure new server object configurations to add to the server, update existing server object configurations, and view the configuration properties of a server object configuration.
If you use IServerObjectConfiguration to modify any of a configuration's properties, you must call UpdateConfiguration on IServerObjectAdmin for those changes to be reflected in the server.
The following code example shows how to connect to the GIS server myServer and use the IServerObjectConfiguration interface to set the properties of a new server object configuration created and added to the server with the CreateConfiguration and AddConfiguration methods on IServerObjectAdmin to create a new geocode server object configuration and add it to the server:
[VB.NET]
Dim gisServerConnection As IGISServerConnection=New GISServerConnection()
gisServerConnection.Connect("myServer")
Dim serverObjectAdmin As IServerObjectAdmin=gisServerConnection.ServerObjectAdmin

' Create the new configuration.
Dim configuration As IServerObjectConfiguration=serverObjectAdmin.CreateConfiguration()
configuration.Name="California"
configuration.TypeName="GeocodeServer"

Dim propSet As IPropertySet=configuration.Properties
propSet.SetProperty("LocatorWorkspacePath", "\\myServer\Geocoding\California")
propSet.SetProperty("Locator", "California")
propSet.SetProperty("SuggestedBatchSize", "500")

configuration.IsPooled=True
configuration.MinInstances=1
configuration.MaxInstances=1
configuration.WaitTimeout=10
configuration.UsageTimeout=120

' Add the configuration to the server.
serverObjectAdmin.AddConfiguration(configuration)
[C#]
IGISServerConnection gisServerConnection=new GISServerConnection();
gisServerConnection.Connect("myServer");
IServerObjectAdmin serverObjectAdmin=gisServerConnection.ServerObjectAdmin;

// Create the new configuration.
IServerObjectConfiguration configuration=serverObjectAdmin.CreateConfiguration();
configuration.Name="California";
configuration.TypeName="GeocodeServer";

IPropertySet propSet=configuration.Properties;
propSet.SetProperty("LocatorWorkspacePath", "\\\\myServer\\Geocoding\\California");
propSet.SetProperty("Locator", "California");
propSet.SetProperty("SuggestedBatchSize", "500");

configuration.IsPooled=true;
configuration.MinInstances=1;
configuration.MaxInstances=1;
configuration.WaitTimeout=10;
configuration.UsageTimeout=120;

// Add the configuration to the server.
serverObjectAdmin.AddConfiguration(configuration);
Use the IsolationLevel property, with type esriServerIsolationLevel, to get the server object isolation or set it for a new configuration or to update an existing configuration.
Server objects can have either high isolation (esriServerIsolationLevelHigh) or low isolation (esriIsolationLevelLow). Each instance of a server object with high isolation runs in a dedicated process on the server that it does not share with other server objects. Instances of server objects with low isolation may share the same process with other server object instances of the same configuration. Use the IsPooled property to indicate if the server objects created by this server object configuration are pooled or nonpooled.
Pooled server objects can be shared across multiple sessions and applications and are held by an application for the duration of a single request. Pooled server objects are meant for applications that make stateless use of those objects.
Nonpooled server objects are dedicated to a single application session and are held for the duration of an application session. Nonpooled server objects are not shared between application sessions and are meant for applications that make stateful use of those objects.
When StartConfiguration is called on a server object configuration whose IsPooled property is true, a set of server objects is preloaded based on the MinInstances property of the server object configuration. When StartConfiguration is called on a server object configuration whose IsPooled property is false, no server objects are preloaded. Server objects are loaded and initialized when an application gets one from the server using CreateServerContext.
The MaxInstances property indicates the maximum number of server objects that can be running and handle requests at any one time. If the maximum number of server objects are running and busy, additional requests are queued until a server object becomes free.
For a pooled server object, MaxInstances represents the maximum simultaneous requests that can be processed by the server object configuration. For a nonpooled server object, MaxInstances represents the maximum number of simultaneous application users of that particular server object configuration. The MaxInstances property must be greater than 0 and greater than the MinInstances property. The MinInstances property applies to only pooled server object configurations. It represents the number of server object instances that are preloaded when the server object configuration is started. The GIS server ensures that the minimum number of instances are always running within the server for a given configuration. When there are more simultaneous requests than server object instances running, additional server object instances are started until MaxInstances is reached.
Nonpooled server object configurations always have a MinInstances property of 0. The MinInstances property must be less than the MaxInstances property. The Name property, in combination with the TypeName property, is used to identify a server object configuration in methods such as GetConfiguration, UpdateConfiguration, StartConfiguration, and so on.
Name is case sensitive and can have a maximum of 120 characters. Names can contain only the following characters:
  • A–Z
  • a–z
  • 0–9
  • _ (underscore)
  • – (minus)
The TypeName property indicates the type of server object that this configuration creates and runs. Examples are MapServer and GeocodeServer.
Server objects that are defined by server object configurations have a collection of initialization parameters and properties associated with them. An example of an initialization parameter is the map document associated with a MapServer object. An example of a property is the batch geocode size for a GeocodeServer object. You can get these properties and change them using the Properties property on the server object configuration. The Properties property returns IPropertySet. Use GetProperties and SetProperties on IPropertySet to get and set these properties. If you change these properties, you must call UpdateConfiguration to change them in the server object configuration.
You can also use the Properties property to get a reference on the PropertySet for a new server object configuration to set its properties before adding it to the server by calling AddConfiguration.
The following code example shows how to connect to the GIS server myServer and use the CreateConfiguration, AddConfiguration, and StartConfiguration methods to create a new geocode server object configuration, add it to the server, and make it available for use. Note how the Properties property is called to get a reference to the server object configuration's properties.
[VB.NET]
Dim gisServerConnection As IGISServerConnection=New GISServerConnection()
gisServerConnection.Connect("myServer")
Dim serverObjectAdmin As IServerObjectAdmin=gisServerConnection.ServerObjectAdmin

' Create the new configuration.
Dim configuration As IServerObjectConfiguration=serverObjectAdmin.CreateConfiguration()
configuration.Name="California"
configuration.TypeName="GeocodeServer"

Dim propSet As IPropertySet=configuration.Properties
propSet.SetProperty("LocatorWorkspacePath", "\\myServer\Geocoding\California")
propSet.SetProperty("Locator", "California")
propSet.SetProperty("SuggestedBatchSize", "500")

configuration.IsPooled=True
configuration.MinInstances=1
configuration.MaxInstances=1
Dim recProps As IPropertySet=configuration.RecycleProperties
recProps.SetProperty("StartTime", "00:00")
recProps.SetProperty("Interval", "3600")

' Add the configuration to the server.
serverObjectAdmin.AddConfiguration(configuration)

' Start the configuration.
serverObjectAdmin.StartConfiguration(configuration.Name, configuration.TypeName)
[C#]
IGISServerConnection gisServerConnection=new GISServerConnection();
gisServerConnection.Connect("myServer");
IServerObjectAdmin serverObjectAdmin=gisServerConnection.ServerObjectAdmin;

// Create the new configuration.
IServerObjectConfiguration configuration=serverObjectAdmin.CreateConfiguration();
configuration.Name="California";
configuration.TypeName="GeocodeServer";

IPropertySet propSet=configuration.Properties;
propSet.SetProperty("LocatorWorkspacePath", "\\myServer\\Geocoding\\California");
propSet.SetProperty("Locator", "California");
propSet.SetProperty("SuggestedBatchSize", "500");

configuration.IsPooled=true;
configuration.MinInstances=1;
configuration.MaxInstances=1;
IPropertySet recProps=configuration.RecycleProperties;
recProps.SetProperty("StartTime", "00:00");
recProps.SetProperty("Interval", "3600");

// Add the configuration to the server.
serverObjectAdmin.AddConfiguration(configuration);

// Start the configuration.
serverObjectAdmin.StartConfiguration(configuration.Name, configuration.TypeName);
Recycling allows server objects that have become unusable to be destroyed and replaced with fresh server objects and to reclaim resources taken up by stale server objects.
Pooled server objects are typically shared between multiple applications and users of those applications. Through reuse, a number of things can happen to a server object to make them unavailable for use by applications. For example, an application can incorrectly modify a server object's state, or an application can incorrectly hold a reference to a server object, making it unavailable to other applications or sessions. In some cases, a server object can become corrupted and unusable.
Recycling allows you to keep the pool of server objects fresh and cycle out stale or unusable server objects. You can get the recycling properties and change them using the RecycleProperties property on the server object configuration. The RecycleProperties property returns IPropertySet. Use GetProperty and SetProperty on IPropertySet to get and set these properties. If you change these properties, you must call UpdateConfiguration to change them in the server object configuration.
The properties associated with recycling are as follows:
  • StartTime—The time at which the recycling interval is initialized. The time specified is in 24-hour notation. For example, to set the start time at 2:00 p.m., the StartTime property is 14:00. This property is of type esriStartupType.
  • Interval—The time between recycling operations in seconds. For example, to recycle the configuration every hour, set this property to 3600.
The StartupType indicates if the configuration is automatically started (esriSTAutomatic) when the SOM windows service is started. Server object configurations that are not configured to start automatically (esriSTManual) must be started manually using ArcCatalog or by calling the StartConfiguration method on IServerObjectAdmin.
The amount of time it takes between a client requesting a server object (using the CreateServerContext method on IServerObjectManager) and getting a server object is the wait time. A server object can be configured to have a maximum wait time by specifying the WaitTimeout property on IServerObjectConfiguration. If a client's wait time exceeds the maximum wait time for a server object, the request times out. The WaitTimeout property is in seconds.
Once a client gets a reference to a server object, it can hold on to that server object as long as desired before releasing it. The amount of time between when a client gets a reference to a server object and when it is released is the usage time. To ensure that clients don't hold references to server objects for too long (for example, they don't correctly release server objects), a server object can be configured to have a maximum usage time by specifying the UsageTimeout property on IServerObjectConfiguration. If a client holds on to a server object longer than the maximum usage time, the server object is automatically released and the client loses the reference to the server object. The UsageTimeout property is in seconds.
IServerObjectConfiguration2 extends IServerObjectConfiguration with properties for managing the server object configuration's extensions. Set the ExtensionEnabled property to true for the SOEs you want to enable for this configuration. A list of the SOEs installed on the GIS server for each server object type is available via IServerObjectManager2.GetExtensionTypeInfos.
Use the ExtensionProperties property to specify the collection of properties for a SOE.
The Serialize and Deserialize methods allow you to save the server object configuration as a string and restore it from a string. This can be useful when copying server object configurations between two GIS servers.
IServerObjectConfiguration2 allows you to set the following additional time-out properties for a server object:
  • StartupTimeout—The maximum time (in seconds) the server allows for an instance of the server object to start.
  • CleanupTimeout—The maximum time (in seconds) the server allows for an instance of the server object to shut down.
Administer server machines
ArcGIS for Server is a distributed system. Server objects managed by the GIS server can run on one or more host machines. A machine that can host server objects must have the SOC installed, and the machine must be added to the list of host machines managed by the SOM.
Use the AddMachine method to add new host machines to your GIS server. Once a machine has been added to the GIS server, as new server object instances are created, the SOM uses the new machine. Use the CreateMachine method to create a server machine that you can pass as an argument to the AddMachine method to add new host machines to your GIS server.
The following code example shows how to use the CreateMachine and AddMachine methods to add a machine to your GIS server:
[VB.NET]
Dim gisServerConnection As IGISServerConnection=New GISServerConnection()
gisServerConnection.Connect ("myServer")

Dim serverObjectAdmin As IServerObjectAdmin=gisServerConnection.ServerObjectAdmin
Dim serverMachine As IServerMachine=serverObjectAdmin.CreateMachine()
serverMachine.Name="callum"

Dim serverMachine2 As IServerMachine2=TryCast(serverMachine, IServerMachine2)
serverMachine2.Capacity=20

serverObjectAdmin.AddMachine (serverMachine)
[C#]
IGISServerConnection gisServerConnection=new GISServerConnection();
gisServerConnection.Connect("myServer");

IServerObjectAdmin serverObjectAdmin=gisServerConnection.ServerObjectAdmin;
IServerMachine serverMachine=serverObjectAdmin.CreateMachine();
serverMachine.Name="callum";

IServerMachine2 serverMachine2=serverMachine as IServerMachine2;
serverMachine2.Capacity=20;

serverObjectAdmin.AddMachine(serverMachine);
Use the GetMachines method to get the names of the machines that have been added to the server to host server objects.
The DeleteMachine method removes a machine from the machines that can host server objects for the GIS server. When you delete a machine, any instances of server objects that are running on that machine will be shut down and replaced with instances running on the GIS server's other host machines.
The ServerMachine class is used to define a machine that can host server objects managed by the GIS server.
IServerMachine allows you to configure the properties of a machine to add it to the GIS server. You must set the Name property for the machine, which will be the name of the machine on the network. The description is optional.
Use the AddMachine method to add new machines to your GIS server. All server objects configured in the GIS server can run on any of the host machines, so all host machines must have access to the necessary data and output directories used by all the server objects.
IServerMachine2 extends IServerMachine to include a Capacity property. The Capacity property defines the number of configuration instances on an SOC machine that are allowed to run concurrently before the pool-shrinking algorithm engages. The pool-shrinking algorithm removes the least recently used configuration instances and replaces them with new instances. Capacity is dependent on system memory and central processing unit (CPU) resources and should be tuned for each machine in the GIS server.
Administer server directories
You can use IServerObjectAdmin to add and remove server directories from the GIS server. Server objects and server applications typically need to write either temporary data or result data to some location for it to be delivered or presented to the end user. For example, a map server object's ExportMapImage method can create an image file that is then displayed on a Web application. These files are typically transient and temporary by nature. For example, when a map server writes an image to satisfy a request from a Web application, that image is needed only for the time it takes to display on the Web application. An application that creates checkout personal geodatabases for download provides a finite amount of time during which that geodatabase is created and when it can be downloaded.
Because server applications support many user sessions, these output files can accumulate and need to be periodically cleaned up. The server provides the capability to automatically clean up these output files if they are written to one of the server's output directories.
Use the CreateServerDirectory method to create a server directory that you can pass as an argument to the AddServerDirectory method to add new server directories to your GIS server. Once you've added the server directory, you can configure your server objects and server applications to use the server directory.
Server directories must be accessible by all host machines configured in the GIS server.
The following code example shows how to use the CreateServerDirectory and AddServerDirectory methods to add a directory to your GIS server:
[VB.NET]
Dim gisServerConnection As IGISServerConnection=New GISServerConnection()
gisServerConnection.Connect ("myServer")

Dim serverObjectAdmin As IServerObjectAdmin=gisServerConnection.ServerObjectAdmin
Dim serverDir As IServerDirectory=serverObjectAdmin.CreateServerDirectory()

serverDir.CleaningMode=esriServerDirectoryCleaningMode.esriSDCAbsolute
serverDir.Description="Default output directory"
serverDir.Path="\\myServer\serveroutput"
serverDir.URL="http://myServer/serveroutput"
serverDir.MaxFileAge=100

serverObjectAdmin.AddServerDirectory (serverDir)
[C#]
IGISServerConnection gisServerConnection=new GISServerConnection();
gisServerConnection.Connect("myServer");

IServerObjectAdmin serverObjectAdmin=gisServerConnection.ServerObjectAdmin;
IServerDirectory serverDir=serverObjectAdmin.CreateServerDirectory();

serverDir.CleaningMode=esriServerDirectoryCleaningMode.esriSDCAbsolute;
serverDir.Description="Default output directory";
serverDir.Path="\\myServer\\serveroutput";
serverDir.URL="http://myServer/serveroutput";
serverDir.MaxFileAge=100;

serverObjectAdmin.AddServerDirectory(serverDir);
The UpdateServerDirectory method updates the ServerDirectory that is specified when the method is called. You can use the GetServerDirectory or GetServerDirectories method on IServerObjectAdmin to get a reference to the ServerDirectory you want to update.
UpdateServerDirectory is useful for modifying the cleanup mode (CleaningMode) and cleanup schedule.
The following code example shows how to connect to the GIS server myServer and use the GetServerDirectory method to get a ServerDirectory, change its MaxFileAge property, then update the directory using the UpdateServerDirectory method:
[VB.NET]
Dim gisServerConnection As IGISServerConnection=New GISServerConnection()
gisServerConnection.Connect ("padisha")

Dim serverObjectAdmin As IServerObjectAdmin=gisServerConnection.ServerObjectAdmin
Dim serverDir As IServerDirectory=serverObjectAdmin.GetServerDirectory("\\myServer\serveroutput")

serverDir.MaxFileAge=200
serverObjectAdmin.UpdateServerDirectory (serverDir)
[C#]
IGISServerConnection gisServerConnection=new GISServerConnection();
gisServerConnection.Connect("padisha");

IServerObjectAdmin serverObjectAdmin=gisServerConnection.ServerObjectAdmin;
IServerDirectory serverDir=serverObjectAdmin.GetServerDirectory(
    "\\myServer\\serveroutput");

serverDir.MaxFileAge=200;
serverObjectAdmin.UpdateServerDirectory(serverDir);
The DeleteServerDirectory method removes a directory from the set of directories managed by the GIS server. The DeleteServerDirectory method does not affect the physical directory. When a server directory is removed with this method, the GIS server no longer manages the cleanup of output files written to that directory. Applications or server objects that are configured to write their output to the physical directory that is referenced by the server directory continue to work, but the files they write are not cleaned up by the server.
The ServerDirectory class defines the properties of a server directory. A server directory is a location on a file system that the GIS server is configured to clean up files that it writes. By definition, a server directory can be written to by all container machines.
The GIS server hosts and manages server objects and other ArcObjects components for use in applications. In many cases, the use of those objects requires writing output to files. For example, when a map server object draws a map, it writes images to disk on the server machine. Other applications may write their own data; for example, an application that checks out data from a geodatabase may write the checkout personal geodatabase to disk on the server.
Typically, these files are transient and need only be available to the application for a short time; for example, the time for the application to draw the map or the time required to download the checkout database. As applications do their work and write data, these files can accumulate quickly. The GIS server automatically cleans up its output if that output is written to a server directory.
Files in a server directory can be cleaned up based on file age or when the file was last accessed. The maximum file age or time since last accessed is a property of a server directory. If CleaningMode is esriDCAbsolute, then all files created by the GIS server that are older than the maximum age are automatically cleaned up by the GIS server. If CleaningMode is esriDCSliding, then all files created by the GIS server that have not been accessed for a duration defined by maximum age are automatically cleaned up by the GIS server.
When creating files in a server directory, they must be prefixed with _ags_ to be cleaned up by the GIS server. Any files in a server directory not prefixed with _ags_ will not be cleaned up.
The IServerDirectory interface allows you to configure the properties of a server directory to add it to the GIS server. You must set the Path, CleaningMode, and MaxFileAge (if cleaning mode is absolute or sliding) properties for the server directory, which is the directories' path on disk. The Description and URL properties are optional.
The URL property is the virtual directory that corresponds to the physical directory specified by the Name property. Server objects, such as a map server object, can use the Name property to write their output files to a directory where they are cleaned up and can pass back to clients the URL for the location of the files they write. Clients (for example, Web applications) don't require direct access to the physical directory.
Use the AddServerDirectory method on IServerObjectAdmin to add the new server directory to your GIS server.
Administer server logging and time-out properties
The Properties property on IServerObjectAdmin returns the properties for the GIS server. The properties are for the GIS server's logging and for server object creation time-out.
The GIS server logs its activity, including server object configuration startup, shutdown, server context creation and shutdown, and errors generated through any failed operation or request in the GIS server.
You can control the logging properties through PropertySet returned by Properties. The following is a description of the logging properties:
  • LogPath—The path to the location on disk to which log files are written. By default, the LogPath is \log.
  • LogSize—The size to which a single log file can grow (in MB) before a new log file is created. By default, the LogSize is 10.
  • LogLevel—A number between 0 and 5 that indicates the level of detail that the server logs. By default, the LogLevel is 3. The following is a description of each log level:
    • 0 (None)—No logging
    • 1 (Error)—Serious problems that require immediate attention
    • 2 (Warning)—Problems that require attention
    • 3 (Normal)—Common administrative messages of the server
    • 4 (Detailed)—Common messages from user use of the server, including server objects
    • 5 (Debug)—Verbose messages to aid in troubleshooting
All aspects of logging can be changed when the GIS server is running. When they are changed, the server immediately uses the new logging settings.
The following code example shows how to use the Properties property on IServerObjectAdmin to modify the logging properties of the GIS server:
[VB.NET]
Dim gisServerConnection As IGISServerConnection=New GISServerConnection()
gisServerConnection.Connect ("myServer")

Dim serverObjectAdmin As IServerObjectAdmin=gisServerConnection.ServerObjectAdmin
Dim logProps As IPropertySet=serverObjectAdmin.Properties

logProps.SetProperty ("LogPath", "c:\ServerLogs")
logProps.SetProperty ("LogLevel", 5)

serverObjectAdmin.Properties=logProps
[C#]
IGISServerConnection gisServerConnection=new GISServerConnection();
gisServerConnection.Connect("myServer");

IServerObjectAdmin serverObjectAdmin=gisServerConnection.ServerObjectAdmin;
IPropertySet logProps=serverObjectAdmin.Properties;

logProps.SetProperty("LogPath", "c:\\ServerLogs");
logProps.SetProperty("LogLevel", 5);

serverObjectAdmin.Properties=logProps;
Server object creation can hang for a variety of reasons. To prevent this from adversely affecting the GIS server, it has a ConfigurationStartTimeout property that defines the maximum time, in seconds, that a server object instance has to initialize itself before its creation is cancelled.
Get statistics about events in the server
As the GIS server creates and deletes server objects, handles client requests, and so on, statistics about these events are logged in the GIS server's logs. In addition to the log, statistics are also kept in memory and can be queried using the IServerStatistics interface. The following screen shot shows the Statistics tab of the ArcGIS Server Properties dialog box:
You can query the GIS server for statistics on the following events described by esriServerStatEvent:
Value
Description
esriSSEContextCreated A client made a call to CreateServerContext on IServerObjectManager and got a reference to a server context.
esriSSEContextCreationFailed CreateServerContext failed due to an error. Errors are logged in the GIS server's log files.
esriSSEContextCreationTimeout CreateServerContext timed out because there were no available server objects for the requested configuration for a duration longer than the server object configuration's WaitTimeout.
esriSSEContextReleased A client released the server context by calling ReleaseServerContext. The time measured is the time the client held on to the context (the time between when they called CreateServerContext and received a reference to the server context and the time they released the server context).
esriSSEContextUsageTimeout A client did not release the server context by calling ReleaseServerContext before the context's server object configuration's UsageTimeout was reached.
esriSSEServerObjectCreated A server object was created. This can happen when a pooled configuration is started and the object pool is populated, when a server object is recycled, or in response to a call to CreateServerContext. The time measured is the time to create the server object.
esriSSEServerObjectCreationFailed The creation of a server object instance failed due to an error. Errors are logged in the GIS server's log files.
You can query these events using the following statistical functions described by esriServerStatFunction:
  • esriSSFCount
  • esriSSFMinimum
  • esriSSFMaximum
  • esriSSFSum
  • esriSSFSumSquares
  • esriSSFMean
  • esriSSFStandardDeviation
For esriSSEContextCreationFailed, esriSSEContextCreationTimeout, esriSSEContextUsageTimeout, and esriSSEServerObjectCreationFailed, the only relevant statistical function is esriSSFCount, as these events do not have time associated with them. The other functions reflect the statistics of the elapsed time associated with the event.
While the GIS server's logs maintain a record of all events in the server, the set of statistics that are in memory and can be queried are accumulated summaries of time slices since the GIS server was started. The granularity of these time slices is more coarse the farther back in time you go. These statistics can be queried for the following time intervals:
  • By second for the current minute
  • By minute for the current hour
  • By hour for the current day
  • By day for events that happened previous to the current day
Each time period is an accumulated total of the statistics for that time period. For example, if you query the total number of requests to create server contexts for the last 30 days, you get statistics from now to the beginning of the day 30 days ago (not to the current time on that day). This is because the in-memory statistics have been combined for that entire day.
This means that you can get statistics for a longer period than you specified in your query. When you query the GIS server for statistics, you can use the IServerTimeRange interface to get a report of the actual time period that your query results reflect.
The IServerStatistics interface has methods for querying a specific statistical function for an event or for querying all statistical functions for an event.
Use the GetSpecificStatisticForTimeIntervals method to query the GIS server for a specific statistic for an event at discrete time intervals. For example, you can use this method to get the count of all server contexts that were created for each minute of the last hour. Use the GetAllStatisticsForTimeInterval method to query the GIS server for all statistics for an event. For example, you can use this method to get the sum, mean, and so forth, of server contexts usage time for the last two days.
These methods can be used to query based on the events occurring in the server as a whole (that is, across all machines) or for those occurring on a specific machine. In addition, these methods can be used to query based on the events using all server objects or for events on a particular server object.
You specify the time interval for which you want to query using an index of time periods relative to the current time based on the time period described by esriServerTimePeriod. The index argument to the GetSpecificStatisticForTimeIntervals and GetAllStatisticsForTimeInterval methods describes the index of the time period from which to start, and the length argument describes the number of time periods to query. For example, to query for all statistics in the last two hours, specify a time period of esriSTPHour, an index of 0, and a length of 2. To query for all statistics since the server started, specify a time period of esriSTPNone, an index of 0, and a length of 1.
If you are unsure of the actual time period that the results of your query reflect, use the IServerTimeRange interface to get a report of the actual time period that your query results reflect.
Use the Reset method to clear the statistics in memory.
The following code example shows how to query the GIS server for statistics on the create context event for all host machines and all configurations since the GIS server was started. It also demonstrates how to use the IServerTimeRange interface to report the actual time the statistics represent.
[VB.NET]
Dim gisServerConnection As IGISServerConnection=New GISServerConnection()
gisServerConnection.Connect ("myServer")

Dim serverStats As IServerStatistics=TryCast(gisServerConnection.ServerObjectAdmin, IServerStatistics)
Dim statsRes As IStatisticsResults=serverStats.GetAllStatisticsForTimeInterval(esriServerStatEvent.esriSSEContextCreated, _
                                     esriServerTimePeriod.esriSTPNone, 0, 1, String.Empty, String.Empty, String.Empty)
Dim serverTR As IServerTimeRange=TryCast(statsRes, IServerTimeRange)

Debug.Print (statsRes.Count & ": " & serverTR.StartTime & " to " & serverTR.EndTime)
[C#]
IGISServerConnection gisServerConnection=new GISServerConnection();
gisServerConnection.Connect("myServer");

IServerStatistics serverStats=gisServerConnection.ServerObjectAdmin as
    IServerStatistics;
IStatisticsResults statsRes=serverStats.GetAllStatisticsForTimeInterval
    (esriServerStatEvent.esriSSEContextCreated, esriServerTimePeriod.esriSTPNone, 0,
    1, string.Empty, string.Empty, string.Empty);

IServerTimeRange serverTR=statsRes as IServerTimeRange;
Debug.Print(statsRes.Count + ": " + serverTR.StartTime + " to " + serverTR.EndTime);
The following code example shows the same query but for statistics for only the last two hours:
[VB.NET]
Dim gisServerConnection As IGISServerConnection=New GISServerConnection()
gisServerConnection.Connect ("myServer")

Dim serverStats As IServerStatistics=TryCast(gisServerConnection.ServerObjectAdmin, IServerStatistics)
Dim statsRes As IStatisticsResults=serverStats.GetAllStatisticsForTimeInterval(esriServerStatEvent.esriSSEContextCreated, _
                                     esriServerTimePeriod.esriSTPHour, 0, 2, String.Empty, String.Empty, String.Empty)
Dim serverTR As IServerTimeRange=TryCast(statsRes, IServerTimeRange)

Debug.Print (statsRes.Count & ": " & serverTR.StartTime & " to " & serverTR.EndTime)
[C#]
IGISServerConnection gisServerConnection=new GISServerConnection();
gisServerConnection.Connect("myServer");

IServerStatistics serverStats=gisServerConnection.ServerObjectAdmin as
    IServerStatistics;
IStatisticsResults statsRes=serverStats.GetAllStatisticsForTimeInterval
    (esriServerStatEvent.esriSSEContextCreated, esriServerTimePeriod.esriSTPHour, 0,
    2, string.Empty, string.Empty, string.Empty);
IServerTimeRange serverTR=statsRes as IServerTimeRange;

Debug.Print(statsRes.Count + ": " + serverTR.StartTime + " to " + serverTR.EndTime);
The following code example shows the query for statistics since the server started for only the Yellowstone map server object:
[VB.NET]
Dim gisServerConnection As IGISServerConnection=New GISServerConnection()
gisServerConnection.Connect ("myServer")

Dim serverStats As IServerStatistics=TryCast(gisServerConnection.ServerObjectAdmin, IServerStatistics)
Dim statsRes As IStatisticsResults=serverStats.GetAllStatisticsForTimeInterval(esriServerStatEvent.esriSSEContextCreated, esriServerTimePeriod.esriSTPNone, 0, 1, "Yellowstone", "MapServer", String.Empty)
Dim serverTR As IServerTimeRange=TryCast(statsRes, IServerTimeRange)

Debug.Print (statsRes.Count & ": " & serverTR.StartTime & " to " & serverTR.EndTime)
[C#]
IGISServerConnection gisServerConnection=new GISServerConnection();
gisServerConnection.Connect("myServer");

IServerStatistics serverStats=gisServerConnection.ServerObjectAdmin as
    IServerStatistics;
IStatisticsResults statsRes=serverStats.GetAllStatisticsForTimeInterval
    (esriServerStatEvent.esriSSEContextCreated, esriServerTimePeriod.esriSTPNone, 0,
    1, "Yellowstone", "MapServer", string.Empty);
IServerTimeRange serverTR=statsRes as IServerTimeRange;

Debug.Print(statsRes.Count + ": " + serverTR.StartTime + " to " + serverTR.EndTime);
The following code example shows the query for the count of server contexts created for each minute in the last 60 minutes for all host machines and all server objects:
[VB.NET]
Dim gisServerConnection As IGISServerConnection=New GISServerConnection()
gisServerConnection.Connect("myServer")
Dim serverStats As IServerStatistics=TryCast(gisServerConnection.ServerObjectAdmin, IServerStatistics)
Dim dr As IDoubleArray=serverStats.GetSpecificStatisticForTimeIntervals(esriServerStatEvent.esriSSEContextCreated, esriServerStatFunction.esriSSFCount, esriServerTimePeriod.esriSTPMinute, 0, 60, String.Empty, String.Empty, String.Empty)
Dim i As Integer
For i=0 To dr.Count - 1
    Debug.Print(dr.Element(i).ToString)
Next i
[C#]
IGISServerConnection gisServerConnection=new GISServerConnection();
gisServerConnection.Connect("myServer");
IServerStatistics serverStats=gisServerConnection.ServerObjectAdmin as
    IServerStatistics;
IDoubleArray dr=serverStats.GetSpecificStatisticForTimeIntervals
    (esriServerStatEvent.esriSSEContextCreated, esriServerStatFunction.esriSSFCount,
    esriServerTimePeriod.esriSTPMinute, 0, 60, string.Empty, string.Empty,
    string.Empty);
int i=0;
for (i=0; i < dr.Count; i++)
{
    Debug.Print(dr.get_Element(i).ToString());
}

Server object extension objects

You can create your own SOEs. The goal of creating an SOE is to provide coarse-grained methods that do a lot of work in the server rather than pay the cost of making a large number of calls to the server from the client.
Extending a server object rather than creating a generic COM object has the following advantages:
  • You don't need to explicitly create instances of an SOE in a context. The SOE is created by the GIS server when the server object instance itself is created.
  • If the functionality that is exposed by the extension requires resources that can be costly to acquire, the initialization cost of creating the object is paid once when the server object and its extensions are created.
  • If the functionality that is exposed by the extension can benefit from some caching logic, it's possible to implement such logic because the cache remains for as long as the server object instance itself remains in the pool.
  • The ArcGIS for Server administration applications can be extended to include custom properties dialog boxes for configuring custom extensions for specific server object configurations.
Unlike utility COM objects, SOEs are registered and configured with specific server objects and are not for ad hoc use or use with an empty server context.
The following is the process for creating an SOE:
  1. Create a COM object that implements IServerObjectExtension and includes any additional custom interfaces and methods. Optionally, implement IObjectConstruct, ILogSupport, and IObjectActivate.
  2. Optionally, create a COM object that implements IAGSSOEParameterPage and IComPropertyPage that includes a user form that encapsulates any initialization properties that must be configured for the extension.
  3. Register the server extension COM object created in Step 1 on each container machine, the SOM machine, and any client machine (that is, Web servers or ArcGIS for Desktop machines that administer the GIS server).
  4. Register the SOE with the GIS server (using the AddExtensionType method on IServerObjectAdmin2).
  5. Optionally, register the property page created in Step 2 in the AGS Extension Parameter Pages component category on each ArcGIS for Desktop client machine.
  6. Create a server object configuration that includes the SOE.
  7. Create your application that consumes the server object and its extension.
Creating the SOE
An SOE is a COM object developed in .NET or C++ that implements IServerObjectExtension and any additional interfaces that are necessary.
IServerObjectExtension is a mandatory interface that must be supported by all SOEs and includes two methods: Init and Shutdown. This interface is used by the server object to manage the lifetime of the SOE. The server object creates the SOE and calls the Init method, handing it a back reference to the server object via the server object helper argument. The server object helper implements a weak reference on the server object. The extension can keep a strong reference on the server object helper (for example, in a member variable) but should not keep a strong reference on the server object. Extensions should get the server object from the server object helper to make any method calls on the server object and release the reference after making the method calls. Init is called once when the instance of the SOE is created.
The Shutdown method informs the SOE that the server object's context is being shut down and is about to go away. In response, the SOE should release its reference on the server object helper as shown in the following code example:
[VB.NET]
Private m_SOH As IServerObjectHelper

Public Sub Init(ByVal SOH As IServerObjectHelper)
    m_SOH=SOH
End Sub

Public Sub Shutdown()
    m_SOH=Nothing
End Sub
[C#]
private IServerObjectHelper m_SOH;

public void Init(IServerObjectHelper SOH)
{
    m_SOH=SOH;
}

public void Shutdown()
{
    m_SOH=null;
}
In your custom methods, use the server object helper to get a reference to the server object as shown in the following code example:
[VB.NET]
Dim mapsrv As IMapServer=TryCast(m_SOH.ServerObject, IMapServer)
[C#]
IMapServer mapsrv=m_SOH.ServerObject as IMapServer;
If your SOE includes configuration properties or requires any additional initialization logic, you need to implement IObjectConstruct. IObjectConstruct is an optional interface for SOEs. The interface includes a single method called Construct. Construct is called once when the SOE is created after IServerObjectExtension.Init is called. Construct hands back the configuration properties for the SOE as a property set. You should include any expensive initialization logic within your implementation of Construct.
While IServerObjectExtension.Init and IObjectConstruct.Construct are called once when the instance of the SOE is created, if your SOE requires logic to run each time its server context is acquired and released (each time a client calls CreateServerContext and ReleaseContext), you need to implement IObjectActivate. IObjectActivate is an optional interface for SOEs that includes two methods: Activate and Deactivate. Activate is called each time a client calls CreateServerContext on the SOE's server object's context, and Deactivate is called each time a client releases the context (via ReleaseContext). Because Activate and Deactivate are called each time a client gets and releases the server object's context, any logic you implement in these methods should not be expensive.
Finally, if you want your SOE to log messages to the GIS server's log file, your SOE should implement ILogSupport. ILogSupport is an optional interface for SOEs that has a single InitLogging method. InitLogging is called when the SOE is created. InitLogging hands back a reference to the GIS server's log object via the log argument. The extension can keep a reference on the server log (for example, in a member variable) as shown in the following code example:
[VB.NET]
Private m_log As ILog

Public Sub InitLogging(ByVal Log As ILog)
    m_log=Log
End Sub
[C#]
private ILog m_log;
public void InitLogging(ILog log)
{
    m_log=log;
}
Since this method is called before IServerObjectExtension.Init and IObjectConstruct.Construct, you can use the log to log messages and errors in initialization, as well as your custom methods as shown in the following code example:
[VB.NET]
m_log.AddMessage(3, 8000, "This is a normal level log message.")
m_log.AddMessage(1, 8000, "This is an error level log message.")
[C#]
m_log.AddMessage(3, 8000, "This is a normal level log message.");
m_log.AddMessage(1, 8000, "This is an error level log message.");
The order in which the methods previously described are called is shown in the following illustration:

 

Creating the SOE properties dialog box

In some cases, your SOE may require that properties be set at the time the SOE is configured by the server administrator. To display a form in the Create Server Object wizard in ArcCatalog and the server object properties page, you can create a COM object that implements IAGSSOEParameterPage and IComPropertyPage and includes a user form that encapsulates any initialization properties that must be configured for the extension.

The IComPropertyPage interface must be implemented for any property page created for an ArcGIS for Desktop application. SOE property pages must also implement the IAGSSOEParameterPage interface. IAGSSOEParameterPage includes a property for getting and setting the properties for the SOE (ExtensionProperties) and a property for getting the properties of the server object that is being extended (ServerObjectProperties). The IComPropertyPage.Show method will display your form on the Add Server Object Wizard as shown in the following screen shot. The property page COM object must be registered in the AGS Extension Parameter Pages component category on the machine on which ArcCatalog is running.

Registering the SOE with ArcGIS for Server

Register the SOE with ArcGIS for Server by doing the following:

  1. Register the server extension COM object on each container machine, the SOM machine, and any client machines (that is, Web servers, ArcGIS for Desktop machines that administer the GIS server).
  2. Register the SOE with the GIS server (using the AddExtensionType method on IServerObjectAdmin2).
  3. Optionally, register the property page in the AGS Extension Parameter Pages component category on each ArcGIS for Desktop client machine.
The following code example shows how to register the SOE with ArcGIS for Server:
[VB.NET]
Dim conn As IGISServerConnection=New GISServerConnectionClass()
conn.Connect("your_server")

Dim SOA2 As IServerObjectAdmin2=TryCast(conn.ServerObjectAdmin, IServerObjectAdmin2)
Dim serverObjExtensionType As IServerObjectExtensionType=SOA2.CreateExtensionType()

serverObjExtensionType.CLSID="vegSOE.vegUtilSOE"
serverObjExtensionType.Description="test server obj extension"
serverObjExtensionType.Name="VegUtilitiesExtension"
SOA2.AddExtensionType("MapServer", serverObjExtensionType)
[C#]
IGISServerConnection conn=new GISServerConnectionClass();
conn.Connect("your_server");

IServerObjectAdmin2 SOA2=conn.ServerObjectAdmin as IServerObjectAdmin2;
IServerObjectExtensionType serverObjExtensionType=SOA2.CreateExtensionType();

serverObjExtensionType.CLSID="vegSOE.vegUtilSOE";
serverObjExtensionType.Description="test server obj extension";
serverObjExtensionType.Name="VegUtilitiesExtension";
SOA2.AddExtensionType("MapServer", serverObjExtensionType);
This should be included in a setup program for distributing your custom SOEs.
Creating a server object configuration that includes the SOE
Once you've registered the SOE with ArcGIS for Server, you can create server object configurations that include the extension using ArcCatalog via the SOE property page (see the previous example) or through code.
The following code example shows how you can create a server object configuration with your extension. When you create a server object configuration of a particular type (for example, MapServer), its configuration includes all extension types that are by default disabled. In this code example, the SOE previously described is enabled for the Yellowstone MapServer, and the name of the layer to query is veg.
[VB.NET]
Dim serverConn As IGISServerConnection=New GISServerConnectionClass()
serverConn.Connect("your_server")

Dim soa As IServerObjectAdmin=serverConn.ServerObjectAdmin
Dim soc As IServerObjectConfiguration2=TryCast(soa.GetConfiguration("Yellowstone", "MapServer"), IServerObjectConfiguration2)
soa.StopConfiguration("Yellowstone", "MapServer")
soc.ExtensionEnabled("AreaSumExtension")=True

Dim props As IPropertySet=soc.ExtensionProperties("AreaSumExtension")
props.SetProperty("LayerName", "Veg")

soa.UpdateConfiguration(soc)
soa.StartConfiguration("Yellowstone", "MapServer")
[C#]
IGISServerConnection serverConn=new GISServerConnectionClass();
serverConn.Connect("your_server");

IServerObjectAdmin soa=serverConn.ServerObjectAdmin;
IServerObjectConfiguration2 soc=soa.GetConfiguration("Yellowstone", "MapServer")as
    IServerObjectConfiguration2;
soa.StopConfiguration("Yellowstone", "MapServer");
soc.set_ExtensionEnabled("AreaSumExtension", true);

IPropertySet props=soc.get_ExtensionProperties("AreaSumExtension");
props.SetProperty("LayerName", "Veg");

soa.UpdateConfiguration(soc);
soa.StartConfiguration("Yellowstone", "MapServer");
Creating an application that consumes the SOE 
Once a server object is running in the server that includes the extension, you can write applications that use the extension's functionality. Refer to the previous section on consuming server objects and SOEs.
Using role-based security from a server object or SOE
A developer of a server object or SOE can discover the identity of a calling Web user using the ServerEnvironment object.
When a new ServerContext is created, the SOM pushes the UserInfo of the calling Web user to the SOC where it can be acquired from the server environment.
The following code example illustrates the process of accessing the UserInfo by co-creating an EnvironmentManager, acquiring the IServerEnvironment2 interface, and accessing the UserInfo property:
[C#]
string userName=null;
string roles=null;

// Set a reference to GUID for esriServer.IServerEnvironment2.
UID uid=new UIDClass();
uid.Value="32D4C328-E473-4615-922C-63C108F55E60";

// CoCreate an EnvironmentManager and retrieve the IServerEnvironment.
IEnvironmentManager environmentManager=new EnvironmentManager()as
    IEnvironmentManager;
IServerEnvironment2 serverEnvironment=environmentManager.getEnvironment(uid);

// Get UserInfo.
IServerUserInfo userInfo=serverEnvironment.UserInfo;
userName=userInfo.Name;
roles=userInfo.Roles;