Moving SBA SDK 1.0 Add-ins to SBA SDK 2.0 (Office Accounting 2007)

martha — Wed, 18 Oct 2006 21:25:00 GMT

The next version of SBA SDK is coming (under a different product name) and it's time to start looking at some of the changes in the Add-ins area.

Referencing SBAAPI.dll

First of all, we found out that our 1.0 SDK sample for UIAddIn, we were referencing SBAAPI (when we are always telling you not to do it). So now that 2.0 is coming I can show you why this is bad. The problem with this is that it references the v1 sbaapi.dll which is not going to be there for 2.0, so if you try to install this add-in in our 2.0 product you will get the following error when you try to click on the "Invoices" button.

If you don't want your add-in to work with Office Accounting 2007 then this is ok, but in case you do, here is what you need to do to remove the reference to SBAAPI.
1. In the UIAddIn project, remove the reference to SBAAPI.
2. You'll get the following build error:

CustomerInvoices.cs(63): The type or namespace name 'CustomerAccount' could not be found (are you missing a using directive or an assembly reference?)

The problem goes away if you use the ICustomerAccount instead of the CustomerAccount class that exists in SBAAPI. Here is the corrected line of code:

this.customerName = ((ICustomerAccount)smallBusinessInstance.CustomerAccounts.GetByPrimaryKey(customerID)).Name;

This problem has been fixed in our SBA SDK 2.0. You can find the SBA SDK 2.0 beta here.

Business Logic Add-ins

If you tried using my sample code from my ISdkAddInDriver Sample that I posted in C# or in VB.NET, there are changes that you need to make if you want to remove the reference to SBAAPI.dll. If you want to do validation, you need to throw an ApplicationException instead of a SmallBusinessException, for example the new code will be:

C# -> throw new ApplicationException("EMAIL MISSING");
VB.NET -> Throw New ApplicationException("EMAIL MISSING")

One of the improvements we've made for Office Accounting 2007 in validation is the error message that users will see when the business logic add-in throws an ApplicationException.

In Small Business Accounting 2006 you will see this:

In Office Accounting 2007 you will see this:

As you can see, the error message now is shorter and more helpful. First, we show the Add-in name and we show whatever Message the Add-in specifies in the ApplicationException. You can find Office Accounting 2007 beta here.

UI Add-ins

One of the improvements we made here is the ability to have cascading menus (up to 3 levels), so now you can organize your menus better. We have updated the UI Add-in sample in SBA SDK 2.0 to show cascading menus. You can find the SBA SDK 2.0 beta here.

SBA Business Logic Add-in Sample in VB.NET (ISdkAddInDriver)

martha — Mon, 02 Oct 2006 19:42:00 GMT

A couple months ago I posted a step by step process for doing a Business Logic Add-in Sample in C#, so finally here is the second part for doing this in VB.NET. The instructions are pretty much copied from the original post but I have translated the code to VB and verified it.

Let's start.

1. Open the UIAddIn project (from VB.NET Samples)
2. Add a new class that implements the ISdkAddInDriver interface. I got the basic code from the Concepts Manual of our SDK. I'm going to post the code here:

Imports Microsoft.BusinessSolutions.SmallBusinessAccounting

Public Class BusinessLogic
    Implements ISdkAddInDriver

    Private m_contextObject As IBaseMasterEntity

    Private instance As ISmallBusinessInstance

    Public Sub New(ByVal contextObject As IBaseMasterEntity)
        MyBase.New()
        Me.m_contextObject = contextObject
        Me.instance = contextObject.SmallBusinessInstance
    End Sub

    Public ReadOnly Property ContextObject() As IBaseMasterEntity
        Get
            Return Me.m_contextObject
        End Get
    End Property

    Public Sub RunPreSave() Implements ISdkAddInDriver.RunPreSave
        ' Do Pre-Save work here
    End Sub

    Public Sub RunPostSave() Implements ISdkAddInDriver.RunPostSave
        ' Do Post-Save work here
    End Sub

    Public Sub RunPreDelete() Implements ISdkAddInDriver.RunPreDelete
        ' Do Pre-Delete work here
    End Sub

    Public Sub RunPostDelete() Implements ISdkAddInDriver.RunPostDelete
        ' Do Post-Delete work here
    End Sub
End Class

3. Now we need to hook the business logic addin so it can be registered and instantiated by SBA. Here's what I have to do:

In DriverRegistration.vb we need to return a new myDriverInfo for the business logic addin. I added this code in line 37 (in the GetDriverInfos method)

myDriverInfo = New MyDriverInfo(New Guid("6EF926D5-79B8-476e-8847-3AE0BCCBF28F"), DriverType.SdkAddIn, False, "", "Validate Customer Email Business Logic Addin", "This is a test business logic to validate email on customers.", Guid.Empty, GetType(BusinessLogic).FullName)

driverInfo.Add(myDriverInfo)

I'm just creating a new guid because I will only have one business logic on this assembly. The last parameter uses BusinessLogic which is the name of my class implementing the ISdkAddInDriver.

In DriverRegistration.vb I need to instantiate my business logic addin. I change the LoadSdkAddInDriver to return a new instance of my BusinessLogic class. This is my new implementation:

Public Function LoadSdkAddInDriver(ByVal driverGuid As Guid, ByVal ownerEntity As IBaseMasterEntity) As ISdkAddInDriver Implements IDriverFactory.LoadSdkAddInDriver
Return New BusinessLogic(ownerEntity)
End Function

Finally, in MyDriverInfo.vb we need to support the AppliedTypes property. In this case, I'm simple going to change the property directly just to make this addin work.

Public ReadOnly Property AppliedTypes() As Type() Implements IDriverInfo.AppliedTypes
    Get
        Return New Type() {GetType(ICustomerAccount)}
    End Get
End Property

4. I'm going to put a simple validation for customers so we can test this business logic addin. If the addin wants to cancel the save event (from the PreSave handler), it needs to throw an exception. The message shown to the user will be an ugly technical message, so I would personally suggest to show a friendly message before that. Here is my code:

Public Sub RunPreSave() Implements ISdkAddInDriver.RunPreSave

    Dim customer As ICustomerAccount = CType(ContextObject, ICustomerAccount)
    Dim email As ICustomerVendorEmail = customer.CustomerVendorEmails.GetByType(CustomerVendorEmailType.Email1)
    If ((email.EmailAddress = Nothing) _
    OrElse (email.EmailAddress.Length = 0)) Then
        Throw New SmallBusinessException(ErrorCases.EmailTypeInvalid, "EMAIL MISSING")
    End If
End Sub

Gotchas
Each time you modify the code in the UIAddIn project, the assembly version will change so you would need to reinstall you addin again or change the AssemblyInfo.cs to have a fixed version number. This was the only issue I ran into. Then, I just have to copy the UIAddin.dll to the SBA location and install it. If you were to ship a business logic, I would suggest you add it to your GAC and install in a separate folder.

You can download my sample here.

Coding for Office Accounting : Business Logic Add-in

Moving SBA SDK 1.0 Add-ins to SBA SDK 2.0 (Office Accounting 2007)

SBA Business Logic Add-in Sample in VB.NET (ISdkAddInDriver)