Chapter One: A Sample Program and Inversion of Control

My name is Bill, and I am an integration newbie.

The purpose of my blog is to chronicle my experiences as I work to integrate Visual Studio Tools for Applications into my own program. Hopefully, this will help other programmers get started with VSTA integration.

The purpose of the sample in this particular blog post is to introduce the application I will be integrating with VSTA, and to introduce the concept of Inversion of Control and its benefits to software development. 

Here is a brief and very basic explanation of Inversion of Control:

 Imagine a class named ClassA. ClassA is the main class for an application and has dependencies on two other classes, Class 1 and Class 2:

Class ClassA

    Private x, y, a, b, c As Integer

    Private str As String

    Sub Main()

        MyClass1 As New Class1

  MyClass1.DoSomething(x, y)

  MyClass2 As New Class2

        MyClass2.DoSomethingElse(a, b, c)

        str = MyClass2.DoEvenMore()

        Console.WriteLine(str)

    End Sub

End Class

If the programmer wants to make any significant changes to either of these dependencies, they must also change the main class’s code. For example, if the programmer changed Class1, he would also have to change the code in ClassA for his program to compile, let alone run! The programmer wants to be able to change the code in Class1 or Class2 without altering ClassA. Right now, this is not possible because of ClassA’s dependencies on Class1 and Class2. The way to make this possible is to by use Inversion of Control.  Inversion of Control, at its most basic level, is, instead of having Class A run methods in Classes 1 and 2, Classes 1 and 2 would actually run (call into) methods in Class A, the main class.

Class A is the main application, so the programmer will not want to change that, just some of its dependencies (Classes 1 and 2).  All ClassA has to do is start both of them, and then allow them to control ClassA. Instead of ClassA controlling them, as is normal, Classes 1 and 2 are controlling Class A.

To start the process of implementing Inversion of Control with VSTA, I made a relatively simple application called “Contact Manager,” which does precisely what its title would imply. The user can control this application by either using the GUI or by letting the application run silently from a script. The script has the ability to add, delete and edit contacts based on user-generated data in text file in the program’s directory. It will also normalize all contacts in the database (capitalize the first and last names) and print out a sorted, formatted list of all contacts in the database.

The GUI has printing as well as adding, deleting and editing capabilities. When contacts are added or edited (in both script mode and interface mode), they are automatically normalized (the first and last names are capitalized).  Another feature of the interface is its searching ability. The user can search for all or part of the first or last name of a contact, and the app will display all the results to the user.

The MainForm.vb file has three main classes: ContactClass, ContactApp and ContactObj. Let’s walk through their important parts:

1.      ContactClass: the class that handles most of the behind the scenes work. It updates and alters the data in the database based on either script commands or interface commands. This class also contains a sub-class, ContactEventArgs, which defines the arguments for all the events in ContactClass.  Here are the methods for ContactClass:

    ContactApp class's ContactApp_Load method calls this method. It asks if the user wants to run the app in script mode if yes, the Connect method on ContactAutoClass is called and passed ContactClass.

    Public Sub AppLoad()

        UpdateDataset()

        Dim MBResult = MsgBox("Would you like to run this program from Script?" + Environment.NewLine + "(If Yes, the Interface will be hidden.)", MsgBoxStyle.YesNo)

        Select Case MBResult

            Case MsgBoxResult.Yes

                ScriptBool = True

                MyContactAuto.Connect(Me)

                ContactApp.Close()

            Case MsgBoxResult.No

                ScriptBool = False

        End Select

    End Sub

2.      ContactApp is the main class for the User Interface. Updates but does not edit content.  All other interface forms in the application behave in a way similar to this.

If the user runs the program in Script mode, the only methods in this class that are used are ContactApp_Load and PrintDocument1.Print.

The other important file is ContactAuto.vb, which contains ContactAuto. The methods in ContactAuto only run when the app is in Script mode. This file has only one class, ContactAuto. Let me direct your attention to the methods Connect and Run.  ContactApp calls both these methods. Look at ContactApp in MainForm.vb for a moment. Notice first how ContactApp_Load calls a method called AppLoad in ContactClass. AppLoad gets user input on whether or not to run the app in script mode. If the user decides to run the app in script mode, AppLoad calls Connect in ContactAuto and passes in ContactClass. Connect stores ContactClass, and gets the contact array from its instance of ContactClass and stores it separately. It then calls the Run method. The Run method controls all of the automation of ContactClass.  Other than connect and the various event handlers, Run calls all of the methods in ContactAuto. ContactAuto as a whole has four main automation abilities: It can add, delete and edit contacts based on text files, and will create those text files if they do not exist in the Contact Manager directory. AddFromFile, DeleteFromFile, and EditFromFile define the procedures for reading the text files, but methods in ContactClass carry out any changes to the actual database. The second automation ability is the normalization (capitalization of the contact’s first and last name) of all contacts in the ContactArray and the Database. Whenever ContactClass adds or edits a contact it automatically normalizes that contact, but if the user decides to alter the code to connect to a different database, whoever or whatever originally inputted that data might not have normalized the data. The NormalizeAllContacts method ensures that no matter what database is used, the app will have normalized all its contacts.

The third automation ability is printing a list of all contacts in the database. The actual page setup is defined in ContactClass, and this setup is used both by User Interface printing and script printing. The script differs from the interface by printing the list automatically instead of showing the user a preview. This, along with the other methods in Run, allows the user to start the program, and then have the program run without user intervention once the user selects yes in this message box:

Reason for the Design:

The reason for this design is greater extensibility of the application through Inversion of Control, as discussed in the introduction.

Try

            Dim str As New StreamReader("Add.txt")

            Dim line

            Do

                Dim Contact As New ContactObj

                line = str.ReadLine()

                Contact.FirstName = line

                line = str.ReadLine()

                Contact.LastName = line

                line = str.ReadLine()

                Contact.HomePhone = line

                line = str.ReadLine()

                Contact.CellPhone = line

                line = str.ReadLine()

                Contact.WorkPhone = line

                line = str.ReadLine()

                Contact.Email = line

                If (Contact.FirstName <> Nothing) And (Contact.LastName <> Nothing) Then

                    ReplaceNullValues(Contact)

                    MyContact.AddContact(Contact)

                End If

                line = str.ReadLine()

            Loop Until line = Nothing

            str.Close()

        Catch ex As FileNotFoundException

        End Try

        Dim stwa As New StreamWriter("Add.txt")

        stwa.Flush()

The programmer could change this to do whatever the programmer wants, because it uses the Inversion of Control Principle. All the ContactClass AddContact method needs to know is that if anything passes in a contact object it should add it to the database. The ContactAuto class can get a contact however it wants, and the ContactClass will add it the same way. The ContactAuto class is calling a method in ContactClass, and thereby controlling it-An external class is controlling the main class!

Now let’s look at the main class’s dependency diagram:

The ContractObj is the main data type used in this sample.  The ContactClass functions independently of the GUI. In addition, no outside forms (Such as the AddContactForm) connect directly to ContactClass. If these forms need to call something in ContactClass, they do it through ContactApp’s instance of ContactClass.

            Inversion of control works well with this program, as the programmer can change ContactAuto, ContactApp, and all the other forms without needing to change much of anything in ContactClass. This makes the application very extensible, as the programmer can tailor the script and forms to match each customer’s specifications without the programmer having to build a new application every time. This ability is one of the fundamental advantages of VSTA, and one of the ways VSTA is a great time- and money-saver.