Please contact the appropriate software vendor or IT professional for assistance with this process or issue, which is beyond Blackbaud's scope of support.

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:

  1. bbafnAPI7.tlb - This library contains the classes for General Ledger, Accounts Payable, Accounts Recievable, Cash Receipts, and Student Billing
  2. bbPYAPI7.tlb - This library contains the classes for Payroll 7
  3. bbEEAPI7.tlb - This library contains the classes for Registrar's Office and Admissions Office
The .NET Framework ships with a special utility named TLBIMP, which generates an interop assembly. A separate interop assembly will need to be generated for each of the above libraries that will be referenced. You can choose to create the interop for any combination of the libraries.

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

command

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:

  1. Create a file named TestAFN.VB and enter the source code above
  2. 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:
      VBC TestAFN.vb /target:exe /r:AFNDotNetAPI.dll

      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.

    sample session

    The following is a sample run of our program against The Financial Edge sample database.

    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.