Using the Client Library (Asi.Soa.ClientServices)

📘

This content is not for iMIS cloud.

Access to iMIS SOA web services for most .NET programmers is going to come through a client library. The ClientLib assembly provides the complete API for accessing iMIS SOA, including service classes and methods, as well as the complete set of data, fault and message contract classes. Key elements of the library include:

• EntityManager, MembershipManager – The data-service class is the root key class used to access web services. The methods provided in the class generally correspond to the operations that are available from the web services.
• Data Contracts – The majority of the classes provided in the client library represent the business objects that are used to access and return data from the service. That would include classes to define persons and organizations, addresses, membership group lists, orders, invoices, and so forth.
• Fault Contracts – Fault contracts define web services equivalent of an exception message.

Do the following to use the web client:

1. Create an instance of the DataServiceClient.
2. Populate the instance with login credentials.
3. Create and populate objects that will be required by your requested operation.
4. Execute the operation you need using the corresponding method on your DataServiceClient instance, trapping for errors. For example:

string error = string.empty;
try
{
  string userName = "username";
  string password = "password";
  var entityManager = new EntityManager(userName, password);
  var query = new QueryData("Party")
  {
    Criteria = new CriteriaDataCollection {CriteriaData.Equal("PartyId", "101")}
  };
  var result = entityManager(query);
 
  foreach (PartyData party in result.Result)
    {
      Console.WriteLine("Party - Id: {0}, Name: {1}", party.PartyId, party.Name);
    }
}
catch (FaultException<ServiceNotAvailableFault> error)
{
  error = "Service not available.";
}
catch (MessageSecurityException)
{
  error = "Invalid Credentials";
}
catch (Exception error)
{
  error = String.Format("Other error: {0}.", error.Message);
}

ClientServices Caching

Caching data on the client improves the performance of iMIS application servers, particularly remote application servers. iMIS SOA includes calls to EntityManager to make caching easy to do, and many iParts make caching calls. However, only certain data should be cached, and then often only briefly.

To ensure that data is cached consistently and automatically for numerous entities, SOA uses policy-based caching, versus explicit WithCache calls (now deprecated and ignored). With policy-based caching, each data contract can carry a [CachingPolicy(cacheLifetime)] attribute.

In setting this attribute, keep in mind that caching data can create unexpected outcomes. These are the lifetime values you can set:

Caching tips

• All high-level, entity-type contracts that you can query have a policy applied: they are registered and carry an [Entity] attribute.
• Contracts that are not marked are handled as DoNotCache.
• EntityManager's Update and Delete calls automatically remove cache values for you.
• Find (by query) calls cache both the Find calls and the underlying elements.
• Find calls include an optional refreshCache argument so that you can force a refresh of cache data, as needed.

Metadata caching

iMIS SOA provides a BOD-like structure for describing entity property characteristics, including prompts. Though the actual metadata is still thin in many areas, it would be relatively inexpensive to provide XML files that describe field-level characteristics of important entities. With metadata for important entities, it would be practical to create an SOA version of a smart control that would operate efficiently over-the-wire. This would improve consistency of application development.

Other caching

As mentioned previously, EntityManager provides caching for metadata and simple caching for FindAll operations, which are common for many simple table look-ups, parameter settings, and so forth. In addition, the cache manager provided in Asi.Soa.ServiceModelEx is available for ad hoc client caching.

As we go forward on implementing UI over web services, we will look for other needs for caching and create systematic approaches to it.

.NET Manager Classes

The following .NET manager classes help a .NET developer easily perform common operations on the entities they manage. We recommend taking advantage of these when working in .NET code.

• EntityService – Provides unfiltered access to everything in SOA.
• EntityManager Class – A proxy for EntityService. Provides built-in operation methods, such as FindByIdentity or FindAll.
• CartManager Class – The CartManager class provides a wrapper for a cart, and a set of common operations to perform on the cart. The cart itself is a property of CartManager.
• ComboOrderManager Class – The ComboOrderManager class provides a wrapper for a combo order, and a set of common operations to perform on a combo order, for example, adding or removing order lines.
• CommerceManager Class – The CommerceManager class helps find commerce information, such as the price a given party will pay for an item.
• EventManager Class – The EventManager class provides a wrapper for an event, and a set of common operations to perform on the event. The event itself is a property of EventManager.
• MembershipManager Class – The MembershipManager class provides a set of common CRUD operations to perform for parties and users.

Entity Service

The service layer of iMIS SOA provides all of its functionality through the EntityService web service. Both EntityService and EntityManager implement IEntityService. EntityManager (the client-side proxy) implements IEntityService by passing calls to EntityService, and adds additional local methods. For help initializing the EntityManager, see General authentication strategies by endpoint.

📘

Not all operations are supported for all entity types. You will see an operation not supported error if the entity type does not support the operation.

Use the IEntityService to perform the following operations:

• Find – Find entities by query.
• FindByIdentity – Find an entity by its identity (primary key in many cases).
• Validate – Validate an entity instance.
• Add – Add a new instance of an entity.
• Update – Update an entity instance.
• Delete – Delete an instance of an entity, or mark the instance as deleted.
• Execute – Run an entity-specific extended operation.
• FindChangeLogByIdentity – Get a change log.
• FindMetadataForEntity – Get the entity metadata.

In addition, EntityManager adds:

• FindAll – Get all entities of a given type.

To enable your Visual Studio project to use iMIS SOA, for example, if you are developing an iPart, you must add client-side assemblies to your project, for example:

using System.ServiceModel;
using Asi.Soa.Commerce.DataContracts;
using Asi.Soa.Core.ServiceContracts;
using Asi.Soa.Core.DataContracts;
using Asi.Soa.Core.DataContracts.Faults;
using Asi.Soa.Fundraising.DataContracts;
using Asi.Soa.Events.DataContracts;
using Asi.Soa.Membership.DataContracts;