Skip navigation FileNet logo
  Open Client Developer's Guide
  Search  |  Index  |  Glossary   |  
Close menu Overview
  About This Guide
  What's New in 4.0.1
  Open menu Introduction to the Toolkit
  Close menu Programming Considerations
    View State Management
    Open Client and ActiveX
    Section 508 Compliance
    COM Objects in the .NET Environment
Open menu Open Client Architecture
Open menu Developing for Process
Open menu Error and Exception Handling
Open menu Customizing the Framework
Globalization / Localization
Open menu General Information
   

Developing with IDM COM Objects in the .NET Environment

Open Client is built on top of FileNet IDM Web Services 4.0 and Microsoft ASP.NET. This configuration enables developers to leverage IDM COM objects when writing custom Web applications. Customers may implement IDM COM objects in ASP.NET applications that use the Single Threaded Apartment (STA) model, which is required by FileNet IDM Objects. Support for using IDM COM objects in other environments, such as .NET remoting, Microsoft Windows Services, Web services, or VB.NET, is not yet available. However, FileNet is working closely with Microsoft to determine future strategy to deliver data services in .NET.

The following sections describe points to consider while developing with IDM COM objects and .NET. For a list of the IDM COM objects currently used in Open Client, see COM Objects Implemented in Open Client.

Performance

Minimize COM Calls

COM calls from .NET require marshaling, which can negatively impact application performance. To avoid this condition, COM calls should be minimized by using data caching, ADO whenever possible.

Use of Marshal.ReleaseComObject in the Search page and few other places to force the release of IDM COM objects potentially earlier than the garbage collector doing the cleanup.

Perform Single Thread ADO Searches

When executing a search using ADO, set ASPCOMPAT="True" in each ASPX page.

Release COM Resources

Classes having IDM COM object should have a Dispose() method (Method of IDisposable interface). After using the instance of above specified class, the Dispose() method should be called to clean up resources held by IDM COM object. The Dispose() method should use the “Marshal.ReleaseCOMObject()” to clean up resources held by IDM COM objects. For cases where IDM COM objects are directly used in methods, the “Marshal.ReleaseCOMObject()” can be used to free resources held by IDM COM object.

Threading Model

FileNet IDM Objects are STA

FileNet IDM COM Objects run under the STA model. Therefore, in order to call FileNet IDM Objects, the ASP.NET Web application must utilize the STA threading model. To ensure that the STA model is in use, set ASPCOMPAT="True" in all ASPX pages that intend to call IDM Objects. Note that the ASPCOMPAT flag defaults to False when no other value is specified.

Note: When implementing ADO to query the database (such as when performing large-scale queries, in lieu of querying the queues via the Process API — for information, see Using ADO to Query the Process Database in the Help for Process Developers on the Process Documentation for FileNet Image Manager CD), the ASPCOMPAT flag must be set to True.

Unified Logon

The thread to execute the logon operation must run in the NT account security context. The following two options are available for impersonation:

Option 1

Perform the impersonate before the logon operation, and then undo the impersonation after the logon is achieved; set ASPCOMPAT=True.

To accomplish this option, the NT account security context must be assigned to the running thread, otherwise, the thread will run under the predefined ASPNET account. The disadvantage of using this option is the additional need to perform the impersonation before accessing any shared resources, such as the use of a temporary file when adding a document.

Option 2

Set <impersonate=“true”> in web.config.

The advantage to using option two is that it is possible to impersonate any thread. However, the disadvantage is that the ASPCOMPAT flag must be set to True in order to use impersonation, which does not work with JiGlue because it operates under the MTA threading model.

The recommendation is to not set <impersonate=“true”> in web.config. Instead, use dynamic impersonation during the logon operation, as well as other operations like adding a document or updating properties. Keep in mind that these options only apply to the unified logon scenario.

Known Issues

Do Not Type-Cast an IDM Generic Object

An IDM generic object cannot be type-cast into another IDM object, such as a document, folder or stored search object. This is a known .NET issue and Microsoft will supply a fix in a future.NET service release. To workaround this issue, use the hidden IFnxxxDual interface of the object in the typecast statement. For example:

oGeneric=oLib.GetObject(...)
oDoc=CType(oGeneric,IDMObjects.IFnDocumentDual)

Do Not Combine Multiple Calls to JiGlue in .NET

Multiple method calls to JiGlue cannot be combined in a single .NET statement, such as:

JiglueObj1.setXYZ(JiglueObj2.getABC())

While the above statement may only fail in some cases, but in case of a failure, the resulting symptoms may be very obscure and can cause performance issues.

Do Not Combine Multiple COM Calls in .NET

Multiple COM calls cannot be combined in a single .NET statement, such as:

ComObj1.GetProp(ComObj2.getName())

Note that failure may only occur in some cases.

Do Not Use IDM Objects with Web Services

ASP.NET Web Services does not allow you to set ASPCOMPAT to support STA IDM COM objects. The page directive ASPCOMPAT='True'can only be set for ASPX page. Setting ASPCOMPAT='True'causes the page to be executed on an STA thread-pool instead of the new MTA one. The use of ASPX pages has been recommended for Open Client application to handle IDM COM objects. Following files are no longer supported by Open Client 4.0.1 and have been replaced by new .aspx files.

Obsolete files...

New files...

FnAnnoService.asmx

FnAnnoService.aspx

FnSecurityService.asmx

FnSecurityInfo.aspx

fndoccontent.vb

FnDocContent.aspx
FnFolderContentService.asmx

No Replacement