Layer-ServiceAgent.md

Service Agent

The Service Agent is the proxy layer that encapsulates the invocation of the corresponding Service Interface layer.

This layer is code-generated and responsible for performing the HTTP request / response handling. it generates the following artefacts :

Capabilities

The WebApiServiceAgentBase provides the core Service Agent functionality for invoking an API endpoint:

• GetAsync - Sends an HTTP GET.
• PutAsync - Sends an HTTP PUT.
• PostAsync - Sends an HTTP POST.
• PatchAsync - Sends an HTTP PATCH.
• DeleteAsync - Sends an HTTP DELETE.

The following is generally performed for each:

Step	Description
Request	Create the HttpRequestMessage.
RequestUri	Set the HttpRequestMessage.RequestUri including the query string.
ETag	Where there is an WebApiRequestOptions.ETag this will result in an If-None-Match (GET) or alternatively If-Match header.
Serialize	Serializes the entity as JSON HttpRequestMessage.Content as applicable.
Send	Uses an HttpClient to send the HttpRequestMessage using the appropriate HTTP Method. This is passed using the WebApiAgentArgs, which also has a BeforeRequest action to allow an opportunity to update the HttpRequestMessage before being sent; e.g. add a security token.
Response	Accepts the corresponding HttpResponseMessage.
StatusCode	Where the HttpResponseMessage.IsSuccessStatusCode is true, will deserialize the JSON HttpResponseMessage.Content as the resulting entity; otherwise, will convert the HttpResponseMessage.StatusCode to the equivalent IBusinessException and throw.

Usage

The Operation element within the entity.xml configuration primarily drives the output. There is a generated class per Entity named {Entity}Agent.

There are currently no opportunities for a developer to extend on the generated code; beyond amending the underlying code generation templates. This is by design to limit the introduction of business or data logic into this layer.