Programmer's Guide:
Using Custom Extensions

Note: This topic only considers limited scenarios encountered when migrating a single sample extension DBRowValidation.

Updates and Guidelines to Custom Extensions

Follow these guidelines to avoid leaks and/or deadlocks to eRoom Server application:

In eRoom sample extension DBRowValidation, read the comment VBNetComEffect that describes the Visual Basic .NET implementation.
Use Try-Catch-Finally block in Visual Basic .NET, for better exception and error handling.
Visual Basic 6.0 used the On Error Goto and/or On Error Resume Next syntax to handle exceptions at runtime. In this scenario, use Try-Catch-Finally block in Visual Basic .NET.
In eRoom sample extension DBRowValidation, the utility function ReleaseComObject internally calls Microsoft API Marshal.ReleaseComObject(). This utility function handles validation before calling Microsoft API and also manages exceptions from Microsoft API.
In eRoom sample extension DBRowValidation, the utility function FinalReleaseComObject internally calls Microsoft API Marshal.FinalReleaseComObject(). This Microsoft API releases all COM references recursively, until reference count becomes zero. This function is not used in the eRoom sample code.
Passing eRoom COM objects as Argument to function or sub routine. EMC has not found any impact or difference when eRoom COM objects are passed ByVal and/or ByRef as an argument to a function or sub for reference counting.
Do not Exit or Break from function, sub, or loop directly without releasing the objects. All eRoom objects that are used locally should be released in during a normal exit or in scenarios with error or exception.

Sample Codes in Visual Basic Code and Visual Basic .NET Code

'# Determine who caused the event by getting ::LoggedinMember property

Dim user As eRoomAPI.IERUUser

user = pEventInfo.LoggedInMember 'QueryInterface for IERUUser interface

Trace("LoggedInMember DisplayName: " & user.DisplayName)

'# Determine who caused the event by getting ::LoggedinMember property

Dim user As eRoomAPI.IERUUser

user = pEventInfo.LoggedInMember 'QueryInterface for IERUUser interface

Trace("LoggedInMember DisplayName: " & user.DisplayName)

'### Release COM Object once done with it...

’r; Either using MS API directly

Marshal.ReleaseComObject(user)

’r; OR using Utility Function which intern call MS API with proper validation

ReleaseComObject(user)

'# Get the database that contains the DBRow

Dim databaseitem As eRoomAPI.IERUItem

databaseitem = dbrowitem.Parent

’r;# To get URL of the item using PrincipalItem &ldots;

Trace("Item URL : " & databaseitem.PrincipalItem.URL)

'# Get the database that contains the DBRow

Dim databaseitem As eRoomAPI.IERUItem

databaseitem = dbrowitem.Parent

'# Create PrincipalItem Object (Child) first and then use it’s URL property.

’r; This way we can Release Child object’s Ref out of Parent Object...

Dim principalItem As eRoomAPI.IERUPrincipalItem

principalItem = databaseitem.PrincipalItem

Trace("Item URL : " & principalItem.URL)

'### Release Child Object first and then Parent once done with them...

ReleaseComObject(principalItem)

ReleaseComObject(databaseitem)

'# Determine who is logged in member/user

Dim member As eRoomAPI.IERUMember

member = pEventInfo.LoggedInMember

Trace("LoggedInMember Info: " member.User.DisplayName & " (" member.ID & ")")

'# Determine who is logged in member/user

Dim member As eRoomAPI.IERUMember

member = pEventInfo.LoggedInMember

user = member.User

Trace("LoggedInMember: " & user.DisplayName & " (" & member.ID & ")")

ReleaseComObject(user)

ReleaseComObject(member)

Loops are used to iterate through objects that are present in a collection. In this scenario, collection is an object that must be released, and every object added within the collection must be released as well.

Dim dbrow As eRoomAPI.IERUDBRow

'Assuming dbrow is Set appropirately

dbrow = xyzObject

Dim cell As eRoomAPI.IERUDBCell

For Each cell In dbrow.Cells

'Usage of how cell is created within loops

'Some statements to perform the task as per functionality

’r;Plus, child ”r;column” interface is directly accessed... cell.column.Name

Trace "My column Name: " & cell.column.Name

Next cell

Dim dbrow As eRoomAPI.IERUDBRow

'Assuming dbrow is Set appropirately

dbrow = xyzObject

Dim cell As eRoomAPI.IERUDBCell

Dim column As eRoomAPI.IERUDBColumn 'Declare/Create CHILD object first

Dim colCells As eRoomAPI.ERUCollection

colCells = dbrow.Cells

'Iterate through the collection using its count or size

For index = 1 To colCells.Count

'get current item from the collection with current index...

cell = colCells.Item(index)

'Some statements to perform the task as per functionality

' Do not use Parent.Child.Property style ...

’r; Get the Child object Column first

column = cell.Column

Trace ("My column Name: " & column.Name)

' Release call objects used inside loop ...

ReleaseComObject(column)

ReleaseComObject(cell)

Next index

' Releasing Collection Object itself

ReleaseComObject(colCells)

ReleaseComObject(dbrow)

Declare and instantiate COM objects just before usage.
Release COM objects soon after usage, by using ReleaseComObject().
Ensure that you call ReleaseComObject() in the reverse order of object creation.
Use Try-Catch-Finally block for better error handling.
Do not use collection object directly. Create the collection object individually, so that you can release it independently.
Change or modify the method to iterate through collections using loops.
Do not exit or break directly from within a loop. Release all object in use, in the reverse order of creation, before exiting the loop.
Release every object created or accessed within the loop, at the end of the loop.

Refer to Upgrading Visual Basic 6.0 Applications to Visual Basic .NET on the Microsoft website for more information on Marshal.ReleaseComObject and Garbage Collection.

Programmer's Guide: Using Custom Extensions

Sample Codes in Visual Basic Code and Visual Basic .NET Code

Programmer's Guide:
Using Custom Extensions