Transcript
HP TRIM Software Version: 7.31
.NET SDK
Document Release Date: December 2012 Software Release Date: December 2012
Legal Notices Warranty The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein. The information contained herein is subject to change without notice. Restricted Rights Legend Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license. Copyright Notices © Copyright 2008-2012 Hewlett-Packard Development Company, L.P. Trademark Notices Microsoft®, Windows®, Windows® XP and Windows Vista® are U.S. registered trademarks of Microsoft Corporation.
Documentation Updates The title page of this document contains the following identifying information: •
Software Version number, which indicates the software version.
•
Document Release Date, which changes each time the document is updated.
•
Software Release Date, which indicates the release date of this version of the software.
To check for recent updates or to verify that you are using the most recent edition of a document, go to: http://h20230.www2.hp.com/selfsolve/manuals This site requires that you register for an HP Passport and sign-in. To register for an HP Passport ID, go to: http://h20229.www2.hp.com/passport-registration.html Or click the New users - please register link on the HP Passport login page. You will also receive updated or new editions if you subscribe to the appropriate product support service. Contact your HP sales representative for details.
Support Visit the HP Software Support web site at: http://www.hp.com/go/hpsoftwaresupport This Web site provides contact information and details about the products, services, and support that HP Software offers. HP Software online support provides customer self-solve capabilities. It provides a fast and efficient way to access interactive technical support tools needed to manage your business. as a valued support customer, you can benefit by using the support web site to: •
Search for knowledge documents of interest
•
Submit and track support cases and enhancement requests
•
Download software patches
•
Manage support contracts
•
Look up HP support contacts
•
Review information about available services
•
Enter into discussions with other software customers
•
Research and register for software training
Most of the support areas require that you register as an HP Passport user and sign in. Many also require a support contract. To register for an HP Passport ID, go to: http://h20229.www2.hp.com/passport-registration.html To find more information about access levels, go to: http://h20230.www2.hp.com/new_access_levels.jsp
Contents
Introduction ........................................................................................................................................................ 6 Some provenance .......................................................................................................................................... 6 Binary compatibility .................................................................................................................................... 6 The object browser ....................................................................................................................................... 6 New functionality ......................................................................................................................................... 7 Getting started .................................................................................................................................................... 8 Creating a reference to the .NET SDK ....................................................................................................... 8 Not on the environment path ...................................................................................................................... 8 Architecture HP TRIM .NET SDK .................................................................................................................... 9 The main objects .......................................................................................................................................... 9 HP TRIM .NET SDK Abstract classes ................................................................................................. 9 The TrimApplication object................................................................................................................... 9 Programming into HP TRIM ........................................................................................................................... 10 Searching HP TRIM using the .NET SDK ............................................................................................... 10 Searching for TRIM objects................................................................................................................. 10 Retrieving the results of the search ................................................................................................... 12 Other search features .......................................................................................................................... 12
.NET SDK
Introduction This document aims to give an overview of programming against HP TRIM’s .NET SDK from version 7. It assumes that you are: 1.
Familiar with HP TRIM, its concepts and usage.
2.
Familiar with programming using .NET based languages.
3.
Familiar with programming using the COM based HP TRIM SDK.
This document concentrates on getting you started and emphasises the differences between the new HP TRIM .NET SDK and the older COM based API. It is purely about using HP TRIM’s .NET based API, it will not discuss the HP TRIM Web Service. This document is still under development The latest version be available on the HP SSO (Self Support online) website. *A note on terminology. The term SDK (Software Development Kit) refers to all programmable interfaces available for a product. For HP TRIM this now involves the COM based API, the .NET SDK, and the HP TRIM Web Service. Technically the .NET SDK is an API, but the usage of the terms SDK and API has blurred and are now commonly used interchangeable.
Some provenance To ensure binary compatibility any objects, methods or properties introduced with or since HP TRIM 5.0 have had to stay in the COM API even if their function may have been deprecated. This has lead to a bit of clutter and confusion. The .NET SDK is however a ‘clean slate’, and our past experiences have helped develop a cleaner, clearer interface not dissimilar to what you are used to with the COM API.
Binary compatibility HP endeavours to maintain binary compatibility of both of the .NET and COM APIs into the future. This means that a program developed against the HP TRIM 7.0 API does not need to be recompiled against future releases of HP TRIM to run. However, it does not mean that your applications will continue to function in the same way. Testing of your applications against new releases of HP TRIM is essential. It does not mean that your code will not produce compile errors when recompiled against future releases of HP TRIM. Reasons for compile errors or changes in functionality can be found in the SDK release notes which document the history of API changes from version to version of HP TRIM.
The object browser When developing a HP TRIM based application, you occasionally come to a point where you are not sure what objects, method or properties the .NET SDK has available to perform a specific function. This is where the object browser in your IDE comes in handy. HP has created help strings which provide a simple explanation of all objects, methods and properties available in the .NET SDK. These can be seen when using the object browser. Using the object browser to search for, for example, renditions will give you an idea of what methods or properties have the rendition in them. From that point, using the help strings, you can probably figure out how to do what you are trying to do.
Page 6 of 12
.NET SDK
New functionality The areas of major change and new functionality: •
Searching – now works for a wider scope of objects, generally more powerful
•
Object model – the API now has a true object model
•
Increased functionality - new objects, methods and properties enable you to do more using the API
Page 7 of 12
.NET SDK
Getting started Creating a reference to the .NET SDK There is no longer a need for an interop assembly. It was simply a wrapper that allowed COM components to work within a .NET environment. You now have a native .NET API. From your .NET IDE, you need to find add a reference, and then select the HP.HPTRIM.SDK reference. 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 for each HP TRIM method and property.
Not on the environment path HP HP TRIM is not on the Windows environment path, as was the case in some previous releases. This means that Windows will not be able to find some of the assemblies required and you will see this error: Load Exception file not found
Remember it, as you will see it from time to time. Here is one solution: Put HP TRIM on the path within the .NET application process before any other HP TRIM calls. This will not affect the path outside of the process. For example, in C#, you could do the following: using HP.HPTRIM.SDK; using System; namespace TestSDK { class Program { static void Main(string[] args) { string trimInstallDir = @"C:\Program Files\Hewlett Packard\HP TRIM"; string temp = Environment.GetEnvironmentVariable("PATH") + ";" + trimInstallDir; Environment.SetEnvironmentVariable("PATH", temp); DoTrimStuff(); } public static void DoTrimStuff() { using ( Database db = new Database() ) { db.Connect(); Console.WriteLine(db.Id); } Console.ReadKey(); } } } The lines to note are those placing the HP TRIM folder in the environment path.
Page 8 of 12
.NET SDK
Architecture HP TRIM .NET SDK Most HP TRIM .NET SDK objects now have constructors and can be created directly. There are no longer constructors in the database object.
The main objects The .NET SDK has a few abstract classes from which most of its objects descend. While it will be helpful to keep these in mind and understand the object hierarchy they will generally not be used for simple tasks.
HP TRIM .NET SDK Abstract classes TrimObject TrimMainObject TrimChildObject TrimChildObjectList TrimPropertySet TrimUserOptionSet TrimSearchStackItem The following are Objects that you will be using frequently in most situations. TrimApplication TrimMainObjectSearch As well as objects that you are already familiar with which include :Database Record Location
The TrimApplication object Many of the functions of the COM SDK’s Database object have been moved to the TrimApplication object.
Page 9 of 12
.NET SDK
Programming into HP TRIM Searching HP TRIM using the .NET SDK Searching for TRIM objects One of the most powerful features of TRIM is the wide range of search criteria that can be applied to select obects from the Database. .NET SDK provides the TrimMainObjectSearch class to provide this functionality. This class allows you to combine a number of search criteria together using boolean logic and then iterate through a resulting set of objects. Note that the rimMainObjectSearch class can only be used to search for objects of a specified type, for instance, you can create a TrimMainObjectSearch to retrieve records. As its name implies, this class can be used to search for any TRIM SDK object that inherits from TrimMainObject. Constructing a TrimMainObjectSearch C# Example // Construct a search object to search for records TrimMainObjectSearch records = new TrimMainObjectSearch(db, BaseObjectTypes.Record); Specifying the Search Criteria The TrimMainObjectSearch class provides a number of simple “canned” methods for searching that do not involve any boolean logic. These are simple to use if you have a straightforward query, they include: SelectByPrefix SelectFavorites SelectByUserLabel SelectNone SelectAll SelectByUris SelectTopLevels SelectThoseWithin
C# Example // Construct a search object to search for all records TrimMainObjectSearch records = new TrimMainObjectSearch(db, BaseObjectTypes.Record); records.SelectAll(); The second option is to used the string search syntax available in TRIM (refer to the TRIM Help file for examples of the syntax). There are three main components to a string search – the primary search string, a set of filters (these work as if they were combined with the primary search string using a boolean ‘and’) and the sort specification. To create a query in this way, you use the SetSearchString method to specify the primary search string, and then you can optionally specify any filters using SetFilterString and specify a sort using Page 10 of 12
.NET SDK SetSortString. This approach is useful if you want to provide the user with a simple edit control for specifying a search, and is also very useful for web-based applications. C# Example // Construct a search object to search for records TrimMainObjectSearch records = new TrimMainObjectSearch(db, BaseObjectTypes.Record); records.SetSearchString(“createdOn:this week and assignee:me”) records.SetFilterString(“type:document”); records.SetSortString(“createdOn”); A third option is to work with TrimSearchStackItem objects. The primary search criteria is represented internally as an array of TrimSearchStackItem objects, arranged as a reversepolish stack to indicate operator precedence. A TrimSearchStackItem can be an operator (TrimSearchOperator) or a search clause (TrimSearchClause). You can build up a query using the internal search stack of the TrimMainObjectSearch, by using such methods as AddSearchClause, And, Or and Not. A read of the Wikipedia article on Reverse Polish notation would be most beneficial for developers unfamiliar with this style of expression. Because filters are all automatically “and-ed” together, they are simply represented as an array of TrimSearchClause items. For sorting, there is a TrimSearchSortItem class and a corresponding array.
C# Example // Construct a search object to search for records TrimMainObjectSearch records = new TrimMainObjectSearch(db, BaseObjectTypes.Record); // set up the individual search clauses TrimSearchClause recordsCreated – new TrimSearchClause(BaseObjectTypes.Record, db, SearchClauseIds.CreatedOn); recordsCreated.SetCriteriaFromString(“this week”); TrimSearchClause recordsAssigned = new TrimSearchClause(BaseObjectTypes.Record, db, SearchClauseIds.Assignee); recordsCreated.SetCriteriaFromString(“me”); // apply the clauses to make a reverse polish stack. records.AddClause(recordsCreated); records.AddClause(recordsAssigned); records.And(); // set up the filter TrimSearchClause documents = new TrimSearchClause(BaseObjectTypes.Record, db, SearchClauseIds.Type); recordsCreated.SetCriteriaFromString(“document”); // add the filter clause Records.AddFilter(documents); // setup a sort item TrimSearchSortItem sortByDate = new TrimSearchSortItem(SearchClauseIds.CreatedOn); Page 11 of 12
.NET SDK // add the sort item Records.AddSort. AddSortItemAscending(sortByDate); These individual classes provide extra features that allow even more elaborate queries to be built.
Retrieving the results of the search The TrimMainObjectSearch derives from IEnumerable and so you can use a standard foreach loop to retrieve items that match the selection. In addition, there are two methods that will return the search result as an array of unique object identifiers ( corresponds to the Uri property of a TrimMainObject). C# Example // Construct a search object to search for records TrimMainObjectSearch records = new TrimMainObjectSearch(db, BaseObjectTypes.Record); records.SetSearchString(“createdOn:this week and assignee:me”) records.SetFilterString(“type:document”); records.SetSortString(“createdOn”); // iterate through the records mathcing the search foreach ( Record resultRecord in records ) { Console.WriteLine(resultRecord.Title); }
Other search features Purpose filtering You can specify that the items in the selection are eventually intended for a specific pupose. This may apply additional hidden filtering to the selection, although not always. As you are iterating through the results, you can use the IsValidForPurpose method to test if the item is suitable for the purpose specified. Each TrimMainObject has an purpose enumeration associated with it – use this enumeration to specify suitable purpose values for the object you are selecting. Persisting a search The TrimMainObjectSearch has a SearchAsXML property which will convert the search, filter and sort criteria to an XML string. This string is language-independent and is therefore useful if you wish to re-use the same search at some later stage, perhaps in a different locale. Item matching The TrimMainObjectSearch provides an ItemMatches method, which allows you to test whether an existing TrimMainObject matches the search criteria contained within the search.
Page 12 of 12
