An interop assembly is required in order to use Blackbaud's objects from .NET code. An interop assembly is a .NET DLL that exposes the type information and metadata from a COM component in a format that .NET managed code can understand. It can be thought of as a mapping layer between the .NET and COM code.
The following is an example that demonstrates building an interop assembly:
The Education Edge and The Financial Edge COM API is exposed in three type libraries:
- bbafnAPI7.tlb - This library contains the classes for General Ledger, Accounts Payable, Accounts Recievable, Cash Receipts, and Student Billing
- bbPYAPI7.tlb - This library contains the classes for Payroll 7
- bbEEAPI7.tlb - This library contains the classes for Registrar's Office and Admissions Office
To generate the interop, open the Visual Studio Command Prompt and change to the \TypeLib directory. The following command will generate the interop for the bbafnAPI7.tlb directory:
tlbimp bbafnAPI7.tlb /out: AFNDotNetAPI.dll
At this point, you have an assembly you may reference in your .NET code to gain full access to the main FE API library
You will now see AFNDotNetAPI.dll in the tlb directory for The Financial Edge. You will also notice that there are some additional .dll files in this directory now such as Scripting.dll, VBA.dll, and VBRUN.dll. These files are created any time that an interop is created for a Blackbaud API library. If you need to create interop assemblies for the remaining libraries, you will need to delete the existing Scripting.dll, VBA.dll, and VBRUN.dll files before creating the interop. After these files have been deleted, you can follow the above steps to generate the interop assemblies for the remaining libraries.
Building a simple VB.NET console-based application that exercises Blackbaud's API:
This application connects to The Financial Edge and lists the names of all projects in the database.
It is not important to be 100% familiar with the syntax of the program, rather, the sample is included to demonstrate how straightforward the process of using Blackbaud's API from a .NET Framework application is. A key point is the semantics of using Blackbaud's API under .NET are unchanged from using it in a traditional COM development tool like Visual Basic 6.
' Simple VB.NET FE:API Sample Application ' Author: Blackbaud, Inc Imports System Imports AFNDotNetAPI Module TestAFN 'Note: error handling is omitted for clarity Sub Main() Dim AFNAPI As New FE_API 'Initialize the API If AFNAPI.Init("WGLASA11111", "UserName", "Password", _ DatabaseNumber:=50, lAppMode:=AppMode.amServer) Then Console.WriteLine("API Initialized!") ' Create an instance of FE's Project Collection Class Dim oProjects As New CGLProjects oProjects.Init(AFNAPI.SessionContext) Dim oProject As CGLProject ' Iterate over all projects in the system For Each oProject In oProjects ' Print the description of each project to the console Console.WriteLine("Project: " & oProject.Fields(EGLPROJECTSFields.GLPROJECTS_fld_DESCRIPTION)) ' Free up any resources held by this object oProject.CloseDown() Next oProject ' Free up any resources held by this object oProjects.CloseDown() Else Console.WriteLine("Unable to initialize. " & _ "Error code = " & AFNAPI.SessionContext.ErrorObject.ErrorDescription()) Exit Sub End If End Sub End Module
Note: The most important line is the Imports AFNDotNetAPI statement. This instructs the compiler to expose Blackbaud's API functionality to the .NET code. Assuming the .NET framework is installed on your machine:
- Create a file named TestAFN.VB and enter the source code above
- To build the program, change to the same directory in which you created the AFNDotNetAPI.DLL interop assembly and issue the following command from the command line:
This invokes the VB.NET compiler and builds our application. Note the boldface type. This instructs the compiler to reference the COM interop DLL just built. The compiler uses the interop assembly to resolve the Blackbaud API types and creates the appropriate metadata required by the .NET Framework to work its COM Interop magic when the program is run.
The following is a sample session, demonstrating the compilation process.
The following is a sample run of our program against The Financial Edge sample database.
Disclaimer: We provide programming examples for illustration only, without warranty either expressed or implied, including, but not limited to, the implied warranties of merchantability and/or fitness for a particular purpose. This article assumes you are familiar with Microsoft Visual Basic and the tools used to create and debug procedures. Our Customer Support can help explain the functionality of a particular procedure, but we will not modify, or assist you with modifying, these examples to provide additional functionality. If you are interested in learning more about the VBA and API modules, contact your account manager.