Micro Focus Content Manager SDK 10.0
Start here

Table of Contents

Using the Content Manager .NET SDK

Technical Prerequisites and Assumptions

As the name implies, the 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.

Binary compatibility

Micro Focus will endeavor to maintain binary compatibility of the .NET SDK into the future. This means that a program developed against the Content Manager SDK will not need to be recompiled against future releases of 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 Content Manager is essential.
  2. Your code will not get compilation errors when recompiled against future releases of Content Manager

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

Content Manager .NET SDK

This document describes the .NET Software Development Kit (.NET SDK) for Micro Focus 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 (TRIM.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 Content Manager with other applications using the .NET SDK requires a technical understanding of its tools, as well as a user perspective of the Content Manager application in general and (most importantly) a business understanding of the particular implementation of Content Manager and any other application for which an integration is required.

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

Using the Content Manager .NET SDK

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 'TRIM.SDK' component from the .NET tab. You might want to add 'using TRIM.SDK;' (for C#), or your language's equivalent, to your code, so that you no longer need to reference it each time you use one of Content Manager objects methods and properties.

NOTE: In Content Manager 9.4 and earlier, the SDK assembly was named HP.HPTRIM.SDK.dll. Beginning with Content Manager 10.0, usage of HP.HPTRIM.SDK.dll is deprecated, and existing SDK applications should be migrated to using TRIM.SDK.dll instead. For more information, please see the relevant release note.

Downloading the .NET SDK from NuGet

The Content Manager .NET SDK is also available as a NuGet package which can be downloaded from the public NuGet repository. To access the SDK this way, use your NuGet browser to search the NuGet repository for MicroFocus.ContentManager.SDK, and select the SDK version that is relevant to you.

For example, in Visual Studio:

  1. In the Solution Explorer window, right-click on your solution.
  2. Select "Manage NuGet packages for Solution...".
  3. Press "Browse" and make sure "Package source" is set to nuget.org.
  4. Enter MicroFocus.ContentManager.SDK into the search bar.
  5. Select the relevant version of the SDK, and press Install.

Finding Content Manager libraries at runtime

.NET uses a process called "Fusion" to locate modules at run time. Content Manager, however, loads all required native code libraries independently of Fusion when the method TrimApplication.Initialize() is called. This provides better error reporting in case something goes wrong. Currently this logic is implemented as follows:

  • 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 TRIM.SDK.dll.
  • Search for tsjApi.dll in a sub-folder named x86 or x64, of the folder containing TRIM.SDK.dll.
  • Search for tsjApi.dll in the folder specified by the Content Manager MSI registry key: (HKEY_LOCAL_ MACHINE\\SOFTWARE\\Micro Focus\\Content Manager\\MSISettings\\INSTALLDIR)
  • Search for tsjApi.dll in folders that are on the PATH environment variable.

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

Code Example (with explicit initialization)

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 explicit initialization)

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

Loading TRIM.SDK.dll assembly dynamically

It is possible in .NET to load .NET assemblies dynamically, from paths that are not known until runtime. This is typically done by hooking into the AppDomain.CurrentDomain.AssemblyResolve event, and adjusting the load path of the relevant assembly.

This technique can be useful when deploying SDK applications to end user systems where the installed path of Content Manager may vary. In this case, you will need to use Content Manager-specific registry settings to locate the Content Manager installation, and then load TRIM.SDK.dll from that location.

A code sample demonstrating dynamic loading of TRIM.SDK.dll is available here.

Memory Management

Any SDK object that implements System.IDisposable must be explicitly disposed to avoid memory leaks and potential corruption. SDK objects implementing IDisposable include:

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

using (Database database = new Database())
{
database.Id = "I1";
database.WorkgroupServerName = "local";
database.Connect();
}

Try/Finally

Database database = null;
try
{
database = new Database();
database.Id = "I1";
database.WorkgroupServerName = "local";
database.Connect();
}
finally
{
if (database != null)
{
database.Dispose();
database = null;
}
}

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().