HPE Content Manager SDK 9.0
Start here

Using the HPE Content Manager .NET SDK

Technical Prerequisites and Assumptions

As the name implies, the HPE Content Manager .NET SDK components are based on Microsoft's .NET Framework. This documentation assumes the reader is a programmer with an understanding of .NET programming principles, the structure of .NET object models (i.e. objects, interfaces, methods and properties) and some experience of using a .NET-compliant programming language such as C# or C++. The code examples in the documentation are in #, although any .NET-compliant language can be used. The examples are tested using Microsoft Visual Studio .NET 2013, requiring the .NET Framework Version 4.5.

Binary compatibility

HPE will endeavor to maintain binary compatibility of both of the .NET and COM API's into the future. This means that a program developed against the HPE Content Manager SDK will not need to be recompiled against future releases of HPE Content Manager in order to run. It does NOT mean that:

  1. Your applications will continue function in the same way. Testing your applications against new releases of HPE Content Manager is essential
  2. Your code will not get compile errors when recompiled against future releases of HPE Records Manager

The reason for any compile errors or changes in functionality will be found in the SDK release notes which document the history of API changes from version to version of HPE Content Manager.

HPE Content Manager .NET SDK

This document describes the .NET Software Development Kit (.NET SDK) for Hewlett Packard Enterprise (HPE) Content Manager. It provides an introduction to the design and content of the .NET SDK, it gives instructions and guidance for using the various tools and objects, and is the logical starting point for the .NET SDK documentation suite.

For those wanting to understand the capabilities of the .NET SDK, this document can be read on its own. For those intending to use the .NET SDK, it serves as an orientation and introduction. For a complete technical understanding, you can add a reference to the .NET SDK (HP.HPTRIM.SDK.DLL) into the object browser of your chosen Integrated Development Environment (IDE), where you will be able to access detailed helpstrings for each object, method and property within the .NET SDK.

Effective integration of HPE Content Manager with other applications using the .NET SDK requires a technical understanding of its' tools, as well as a user perspective of the HPE Content Manager application in general and (most importantly) a business understanding of the particular implementation of HPE Content Manager and any other application for which an integration is required.

This document is about using the HPE Content Manager .NET SDK; it will not discuss using the HPE Content Manager Service API.

Using the HPE Content Manager .NET SDK

Technical Prerequisites and Assumptions

As the name implies, the HPE Content Manager .NET SDK components are based on Microsoft's .NET Framework. This documentation assumes the reader is a programmer with an understanding of .NET programming principles, the structure of .NET object models (i.e. objects, interfaces, methods and properties) and some experience of using a .NET-compliant programming language such as C# or C++. The code examples in the documentation are in C#, although any .NET-compliant language can be used. The examples are tested using Microsoft Visual Studio .NET 2013, requiring the .NET Framework Version 4.5.

Binary compatibility

HP will endeavor to maintain binary compatibility of both of the .NET and COM API's into the future. This means that a program developed against the HPE Content Manager SDK will not need to be recompiled against future releases of HPE Content Manager in order to run. It does NOT mean that: l Your applications will continue function in the same way. Testing your applications against new releases of HPE Content Manager is essential l Your code will not get compile errors when recompiled against future releases of HPE Records Manager The reason for any compile errors or changes in functionality will be found in the SDK release notes which document the history of API changes from version to version of HPE Content Manager.

Getting started

Creating a reference to the .NET SDK

From your .NET IDE you need to find 'Add Reference' either under 'Project' on the menu or in the 'solution explorer' window and then select the 'HP TRIM SDK' component from the .NET tab. You might want to add 'using HP.HPTRIM.SDK;'(C#) or your language's equivalent to your code, so that you no longer need to reference it each time you use one of HPE Content Manager object's methods and properties.

Finding assemblies at runtime

.NET uses a process called "Fusion" to locate modules at run time. HPE Content Manager, however, loads all required assemblies and non-managed code libraries independently of Fusion when the method TrimApplication.Initialize() is called. This provides better error reporting when something is wrong. Currently this logic is implemented:

  • If the TrimApplication.TrimBinariesLoadPath property is set, then search for TSJAPI.DLL in that location (and don't try any other paths at all).
  • Search for TSJAPI.DLL in the same folder as HP.HPTRIM.SDK.DLL.
  • Search for TSJAPI.DLL in the folder specified by the TRIM MSI registry key: (HKEY_LOCAL_ MACHINE\SOFTWARE\Hewlett-Packard\HP TRIM\MSISettings\INSTALLDIR)
  • Search for TSJAPI.DLL in parent folders of HP.HPTRIM.SDK.DLL.
  • Search for TSJAPI.DLL in folders that are on the PATH environment variable.

It is recommended to call TrimApplication.Initialize() explicitly as the first HPE Content Manager related call in your code. This results in a simpler error message if something does go wrong.

Code Example (with Initialize)

try
{
TrimApplication.Initialize();
Database objDB = new Database();
}
catch (Exception e)
{
System.Diagnostics.Trace.WriteLine(e.Message);
}

If you omit TrimApplication.Initialize(), and there is a subsequent load error, the error will need to be 'dug out' through exceptions.

Code Example (without Initialize)

try
{
Database objDB = new Database();
}
catch (Exception e)
{
while (e != null)
{
System.Diagnostics.Trace.WriteLine(e.Message);
e = e.InnerException;
}
}

Memory Management

Any SDK object that implements System.IDisposable must be explicitly disposed to avoid memory leaks and potential corruption. The three objects that implement IDisposable in 9.0 are:

This means that any code that instantiates these objects must utilize either a using statement, or a try/finally block, to ensure that Dispose() is called before the object goes out of scope.

Examples

Using statement

1 using (Database database = new Database())
2 {
3  database.Id = "I1";
4  database.WorkgroupServerName = "local";
5  database.Connect();
6 
7 }

Try/Finally

1 Database database = null;
2 
3 try
4 {
5  database = new Database();
6  database.Id = "I1";
7  database.WorkgroupServerName = "local";
8  database.Connect();
9 
10 }
11 finally
12 {
13  if (database != null)
14  {
15  database.Dispose();
16  database = null;
17  }
18 }

Leak tracking

The SDK provides a leak tracking mechanism, for reporting and tracking down SDK objects that are not properly disposed. Leak tracking can be enabled and disabled using the TrimApplication.EnableSdkLeakTracking() method. Leak tracking is enabled by default.

When leak tracking is enabled, the first leak of an object will be reported to the Windows application event log, with a message containing the call stack location where the object was allocated. Subsequent leaks can be retrieved by calling TrimApplication.GetSdkLeakCount() and TrimApplication.GetSdkLeakStackTraces().