Provides access to members for managing a server context, and the objects running within that server context.
Members
| Name | 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. |
IServerContext.CreateObject Method
Create an object in the server context whose type is specified by the CLSID.
Public Function CreateObject ( _
ByVal CLSID As String _
) As Object
public object CreateObject (
string CLSID
);
Remarks
Use this method when you need to create an object for use in your application.
Create object 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. For example, if you get a point from a point collection in the server context 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.
Consider the following examples. In each example, assume that objects with Remote in their names are objects in a server context as in:
while objects with Local in their name are objects are objects created locally as in:
You can’t set a local object to a remote object:
Do not set a local object, or a property of a local object, to be an object obtained from a remote object:
When calling a method on a remote object, don’t pass in local object as parameters:
You can get simple data types (double, long, string, etc) that are passed by value from a remote object and use them as properties of a local object as in:
Consider the following examples. In each example, assume that objects with Remote in their names are objects in a server context as in:
while objects with Local in their name are objects are objects created locally as in:
You can’t set a local object to a remote object:
Do not set a local object, or a property of a local object, to be an object obtained from a remote object:
When calling a method on a remote object, don’t pass in local object as parameters:
You can get simple data types (double, long, string, etc) that are passed by value from a remote object and use them as properties of a local object as in:
IServerContext.GetObject Method
Get a reference to an object in the server context's object dictionary by its Name.
Public Function GetObject ( _
ByVal Name As String _
) As Object
public object GetObject (
string Name
);
Remarks
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.
IServerContext.LoadObject Method
Create an object in the server context from a string that was created by saving an object using SaveObject.
Public Function LoadObject ( _
ByVal str As String _
) As Object
public object LoadObject (
string str
);
Remarks
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 statless use of pooled server object. 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, which need to be maintained in the users session state. The application does this by saving a serialized map descriptor as part of each users 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 sessions 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 users 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.ReleaseContext Method
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).
Public Sub ReleaseContext ( _
)
public void ReleaseContext (
);
Remarks
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.
IServerContext.Remove Method
Remove an object from the server context's object dictionary.
Public Sub Remove ( _
ByVal Name As String _
)
public void Remove (
string Name
);
Remarks
Remove and RemoveAll to remove object from a context that have been set using SetObject. Once an object it can no longer be retrieved 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.
IServerContext.RemoveAll Method
Remove all objects from the server context's object dictionary.
Public Sub RemoveAll ( _
)
public void RemoveAll (
);
Remarks
Remove and RemoveAll to remove object 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.
IServerContext.SaveObject Method
Save an object in the server context to a string.
Public Function SaveObject ( _
ByVal obj As Object _
) As String
public string SaveObject (
object obj
);
Remarks
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 statless use of pooled server object. 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, which need to be maintained in the users session state. The application does this by saving a serialized map descriptor as part of each users 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 sessions 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 users 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.ServerObject Property
The map or geocode server object running in the server context.
Public ReadOnly Property ServerObject As IServerObject
public IServerObject ServerObject {get;}
Remarks
The ServerObject property of a server context returns the server object that is running withing the server context. If you use the CreateServerContext method on IServerObjectManager to create a a server context based on a server object configuration, use the ServerObjectProperty to get a reference to the server object that is running within that context.
IServerContext.SetObject Method
Add an object running in the server context to the context's object dictionary.
Public Sub SetObject ( _
ByVal Name As String, _
ByVal obj As Object _
)
public void SetObject (
string Name,
object obj
);
Remarks
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.
Classes that implement IServerContext
| Classes | Description |
|---|
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.