Integrating with Appraise-It Pro

Before writing an integration, make sure you've enabled the Development tab for access to the Field Details Pane.

---

Appraise-It Pro exposes useful functionality to other .NET applications through its .NET API.

Appraise-It Pro .NET Integration History

At initial release, Appraise-It Pro's .NET integration API targeted .NET Framework 4.6.2.

As of Appraise-It Pro v.2.8, the .NET integration API targets .NET Standard 2.0; integrations written for the old API must be updated to continue functioning.

For help updating existing integrations, please see the Integration Upgrades page.

Writing a .NET Integration

The Appraise-It Pro integration libraries are distributed as a NuGet package, available at https://www.nuget.org/packages/Sfrep.AppraiseIt.Client.Integration/.

To access Appraise-It Pro's functionalities via its .NET API, you first need to create an IntegrationClient instance.

Creating an IntegrationClient Instance

Your project will need to reference the Sfrep.AppraiseIt.Client.Integration.dll and Sfrep.AppraiseIt.Client.Integration.Contract.dll libraries in the Sfrep.AppraiseIt.Client.Integration NuGet package.

The integration object constructor accepts a client name string, a synchronization context instance, and an optional process ID.

• The client name is the name of your integration.
• The synchronization context is an instance of System.Threading.SynchronizationContext.
  • If you do not need to raise events on a specific thread, use null to raise them on background threads.
• The process ID is the ID of a specific instance of Appraise-It Pro.

There are three ways to create an integration object:

1. Construct the object and attach it to a specific, running instance of Appraise-It Pro.

IntegrationClient client = new IntegrationClient("Third-Party Application", SynchronizationContext.Current, 123456);

2. Construct the object and choose which specific, running instance of Appraise-It Pro to use.

IntegrationClient client = new IntegrationClient("Third-Party Application", SynchronizationContext.Current);

3. Construct the object and have it create a new instance of Appraise-It Pro.

IntegrationClient client = new IntegrationClient("Third-Party Application", SynchronizationContext.Current);

Note that the code for methods 2 and 3 is the same. The user will be prompted to select an existing instance of Appraise-It Pro or start a new instance:

Events

The integration supplies three basic events: ReportClosed, ReportLoaded, and ProcessExited.

Properties

The integration supplies many properties that expose various pieces of information about the report and Appraise-It Pro's status.

Note that some properties are only available via a transaction.

Non-transaction-based Properties

In general, properties relating directly to the application are available without a transaction.

For example, you can check to see if Appraise-It Pro is running:

Console.WriteLine(string.Format("\tIs Appraise-It Pro Running?: {0}", client.IsRunning));

And get its process ID:

Console.WriteLine(string.Format("\tAppraise-It Pro's Process ID: {0}", client.ProcessId));

Transaction-based Properties

When using properties that require transactions, it's important to note the nature of a transaction.

Transactions block the user and other applications from interacting with Appraise-It Pro, so it is very important to make sure that:

• If operations performed during a transaction cause an error, the transaction exits properly.
• They are grouped, wherever possible, to minimize blocking access to Appraise-It Pro.

Exception handling should be added to catch IntegrationClientExceptions.

To begin a transaction, call BeginTransaction(). To end it, call EndTransaction(). For example:

try {
  client.BeginTransaction();
  try {	
    Console.Write("Report Open: {0}", client.HasReport);
  }
  finally {
    client.EndTransaction();
  }
}
catch (IntegrationClientException e) {
  Console.WriteLine("Error: {0}", e.Message);
}

Resource Cleanup

It's important to remember to free up your resources when you've finished with an integration object. You can call the IntegrationClient's Dispose() method or wrap the instance in a using statement.

// Create integration object.
IntegrationClient client = new IntegrationClient("Third-Party Application");
try {
  client.BeginTransaction();
  try { 
    Console.Write("Report Open: {0}", client.HasReport);
  }
  finally {
    client.EndTransaction();
  }
}
catch (IntegrationClientException e) {
  Console.WriteLine("Error: {0}", e.Message);
}
finally {
  // Dispose of integration object.
  client.Dispose();
}