Agent Mode Programming
Commerce Server Core Systems lets you access the management functionality of the following Commerce Server Core Systems systems through what are known as the agent APIs. These use the corresponding Web services to provide the access over a network:
Catalog System (CatalogContext)
Marketing System (MarketingContext)
Orders System (OrderManagementContext)
Profiles System (ProfileManagementContext)
Unlike using the Web services directly, the agent APIs provide the same object model as is available locally using the in-process APIs. When you must have remote access to the management functionality of one or more of these Commerce Server Core Systems systems, programming with the agent APIs provides a somewhat friendlier programming experience than programming directly with the Web services.
.gif "Important note") Important Note: |
|---|
Whenever possible, use the agent mode management APIs instead of programming directly to the Commerce Server Core Systems Web services. Programming directly to the Web services is not considered best practice for .NET programming environments. |
The difference between accessing one of these Commerce Server Core Systems systems using the agent APIs versus using the local APIs is in how objects of the corresponding context class (shown parenthetically earlier) are created. After you create the context class for a particular Commerce Server Core Systems system, you can use it to access the full object model for that system. For more information about how to develop with the individual systems, see the following topics:
The rest of this topic summarizes how to create the various context objects so that successive operations are performed in agent mode, through the Commerce Server Core Systems Web services, over the network.
Using the Catalog and Inventory Systems API in Agent Mode
In order to use the agent APIs that access both the runtime and management functionality of the Catalog and Inventory Systems, use the correct version of the Create factory method of the CatalogContext class. The correct version takes an instance of the CatalogServiceAgent class as its only parameter: CatalogContext.Create(CatalogServiceAgent).
Note
An obsolete version of the agent API Create factory method takes instances of the CatalogServiceAgent class and the DebugContext class as parameters: CatalogContext.Create(CatalogServiceAgent, DebugContext). You should avoid using this version.
After you have created an Agent-mode instance of the CatalogContext class, and assuming that you have an Inventory System enabled for your implementation of Commerce Server Core Systems (the InventorySystemExists property is set to True), you can retrieve an Agent-mode instance of the InventoryContext class using the InventoryContext property.
Using the Marketing System Management API in Agent Mode
In order to use the agent API that accesses the management functionality of the Marketing System, use one of the two correct versions of the Create factory method of the MarketingContext class. The correct versions take single parameters, an instance of the MarketingServiceAgent class in one case and a String in the other case: MarketingContext.Create(MarketingServiceAgent) or MarketingContext.Create(String).
In the former case, you first create an instance of the MarketingServiceAgent class by specifying the URL of the Marketing Web service, and possibly also setting other properties. In the latter case, you specify the URL of the Marketing Web service and an instance of the MarketingServiceAgent class is created on your behalf using default property settings. Which method that you choose depends on whether you must have direct access to your MarketingServiceAgent object before creating your MarketingContext object.
For an example of using the management functionality of the Marketing System in Agent mode, see Agent Mode Programming Sample.
Using the Orders System Management API in Agent Mode
In order to use the agent API that accesses the management functionality of the Orders System, use the correct version of the Create factory method of the OrderManagementContext class. The correct version takes an instance of the OrderServiceAgent class as its only parameter: OrderManagementContext.Create(OrderServiceAgent).
Using the Profiles System Management API in Agent Mode
In order to use the agent API that accesses the management functionality of the Profiles System, use one of the three correct versions of the Create factory method of the ProfileManagementContext class. The correct versions take single parameters, an instance of the ProfilesServiceAgent class in the first case, a String in the second case, and an instance of the System.Uri class in the third case: ProfileManagementContext.Create(ProfilesServiceAgent),ProfileManagementContext.Create(String), or ProfileManagementContext.Create(Uri).
In the first case, you first create an instance of the ProfilesServiceAgent class by specifying the URL of the Profiles Web service, and possibly also setting other properties. In the second two cases, you specify the URL of the Profiles Web service (as either a String or a Uri object) and an instance of the ProfilesServiceAgent class is created on your behalf using default property settings. Which method that you choose depends on whether you must have direct access to your ProfilesServiceAgent object before creating your ProfileManagementContext object.