ArcObjects Library Reference (Server)

IServerContext Interface

Provides access to members for managing a server context, and the objects running within that server context.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Members

		Description
	CreateObject	Create an object in the server context whose type is specified by the CLSID.
	GetObject	Get a reference to an object in the server context's object dictionary by its Name.
	LoadObject	Create an object in the server context from a string that was created by saving an object using SaveObject.
	ReleaseContext	Release the server context back to the server so it can be used by another client (if pooled), or so it can be destroyed (if non-pooled).
	Remove	Remove an object from the server context's object dictionary.
	RemoveAll	Remove all objects from the server context's object dictionary.
	SaveObject	Save an object in the server context to a string.
	ServerObject	The map or geocode server object running in the server context.
	SetObject	Add an object running in the server context to the context's object dictionary.

CoClasses that implement IServerContext

CoClasses and Classes	Description
ServerContext	The ServerContext object used for working with ArcObjects in the GIS server.

Remarks

When developing applications with ArcGIS for Server, all ArcObjects that your application creates and uses live within a server context. A server context is a reserved space within the server dedicated to a set of running objects. GIS server objects also live in a server context. To get a server object, you actually get a reference to its context, then get the server object from the context. This server object acts as the entry point to all the other objects that belong to your map server or geocode server. To get a reference to the server object, you call GetServerObject, then cast or QI to the appropriate server type, such as IMapServer (or MapServer) or IGeocodeServer (or GeocodeServer).

You can also create empty server contexts. You can use an empty context to create ArcObjects on the fly within the server to do ad hoc GIS processing.

All ArcObjects 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 IServerContext.

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 will remain in use and 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 IServerContext interface has a number of methods for helping you manage the objects you create within server contexts. The following is a description of how and when you would use these methods:

CreateObject

Use this method when you need to create an object for use in your application.

CreateObject will return a proxy to the object that is in the server context. Your application can make use of 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 will actually be in the server context and you application will be handed back a proxy to that object. In the above example, if you get a point from the point collection using IPointCollection::Point(), the point returned will be 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.

Also, 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 use them to create a new local point. Don�t directly use the point in the server context as, for example, the geometry of a local graphic element object.

For language specific examples (C#, Java, VB6, and VB.NET) illustrating the usage this method, view the detailed component help for CreateObject.

SetObject, GetObject

A context contains a dictionary that you can use as a convenient place to store objects that you create within the context. Note that this dictionary is itself valid only as long as you hold on to the server context and 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.

SetObject adds objects to the dictionary and GetObject retrieves them. An object that is set in the context will be available until it is removed (by calling Remove or RemoveAll), or until the context is released.

Remove, RemoveAll

Use these methods to remove objects from a context that have been set using SetObject. Once an object is removed, a reference can no longer be made to it using GetObject. Note that if you do not explicitly call Remove or RemoveAll, you can still not get references to objects set in the context after the context has been released.

SaveObject, LoadObject

These 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, then you want to draw the point that GeocodeAddress returns on your map, you need to copy the point into your MapServer's context.

Another important use of these methods is to manage state in your application while making stateless use of pooled server objects. A good example of this is in a mapping application. The initial session state for all users is the same and is equal to the map descriptor for the map server object. Each user can then change map descriptor properties, such as the extent and layer visibility, that need to be maintained in the user's session state. The application does this by saving a serialized map descriptor 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 descriptor 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.

It's important to note that if you are building a web application using the Esri web controls, the controls take care of saving and loading the MapDescription for you.

IServerContext Interface

Product Availability

Members

CoClasses that implement IServerContext

Remarks

See Also