Agent Mode Programming with the Management APIs

For the latest version of Commerce Server 2007 Help, see the Microsoft Web site.

Commerce Server lets you access the management functionality of the following Commerce Server 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)

• Inventory System (InventoryContext)

• 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 systems, programming with the agent APIs provides a somewhat friendlier programming experience than programming directly with the Web services.

Important Note:
Whenever possible, use the agent mode management APIs instead of programming directly to the Commerce Server 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 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 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:

• Developing with the Catalog System

• Developing with the Inventory System

• Developing with the Marketing System

• Developing with the Orders System

• Developing with the Profiles System

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 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 Commerce Server 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 (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 Commerce Server 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 Commerce Server 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 Commerce Server 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.

See Also

Other Resources

Local Mode Programming with the Management APIs

Programming Directly to the Web Services

Agent Mode Programming Sample

Understanding the Different Types of Commerce Server APIs