Introduction to the Visual Basic Quick Start

Use the tutorial in Quick Start with Visual Modeler to become quickly acquainted with the tool. You will be introduced to some basic features in Visual Modeler, and learn how to:

•	Understand an application by browsing existing design diagrams and specifications.

•	Modify an application by modeling the changes.

•	Implement changes to an application by generating and evolving the code and updating the design.

•	Understand how the design model is mapped to Visual Basic code.

It takes no more than an hour to complete the tutorial. It is a well-spent hour, since it will save you a lot of time later on.

Prerequisites

•	To use this tutorial effectively, you should be comfortable with basic Microsoft Windows techniques, including using a mouse and choosing from menus. You should also be familiar with the Microsoft Visual Basic programming environment.

•	The example used is a design model of an order system and the corresponding Visual Basic code.

•	To run the example, you need to have Microsoft Visual Basic installed on your system.

•	To browse the model in the example, you need Visual Modeler installed on your system.

Reading Instructions

It is best to complete the parts of the tutorial sequentially. If you choose to do only a part of the tutorial, you should start with the first topic in one of the chapters. For example, you can skip chapter Introduction to the Order System Example and start with Introduction to Browsing in chapter Browsing the Order System Design Model, but you cannot jump directly into the middle of a chapter.


Introduction to Model-Driven Software Development - VB

Visual Modeler makes it easy for you to create, enhance, and maintain Microsoft Visual Basic applications. It bridges the gap between object technology and relational databases by providing modeling tools for the analysis, design, and implementation of object-oriented applications.

By using Visual Modeler, you focus your effort on building business objects, cooperating with the user-interface objects and database schemas from the objects. Used in conjunction with Microsoft’s Visual Basic environment, Visual Modeler is a complete solution for creating powerful client/server applications.

Visual Modeler allows you to fulfill the promise of object-oriented programming by quickly and easily creating applications that are maintainable, that have a long lifetime, and that contain components that can be reused in other applications.

Furthermore, with round-trip engineering, Visual Modeler enhances your ability to develop scalable applications. Round-trip engineering mirrors the way you really work—making a quick model of an application under development, implementing it, and then refining it based on your ever-increasing understanding of the problem. You use both Visual Modeler and Microsoft Visual Basic in round-trip engineering, working back and forth between the two tools as you model and evolve your code.

You reiterate this process of modeling, implementing, and refining until you are satisfied with the completeness and correctness of your model. With Visual Modeler, you have a tool that supports your method of development, because Visual Modeler keeps your implementations and designs synchronized and propagates any changes you make without loosing information.

Because more often than not, your work involves enhancing and maintaining existing systems, Visual Modeler provides the ability to reverse engineer existing code into a design model, providing not only meaningful design diagrams, but also the ability to continue your work using round-trip engineering.


Overview of the Order System Example - VB

Imagine yourself as the newest member of the MIS department in a small fish and seafood distributing company. Your first assignment is to make changes to the company’s sales order support application. After meeting with your boss, you understand that:

•	An order has a purchaser

•	An order consists of one or more order rows, each of a given article in a given quantity

•	Orders are registered and handed to shipping

•	Customers, orders, and articles need to be persistently stored by the order system

Before making any decisions on how to change the order system, you wisely decide to run the current implementation and to use Visual Modeler for studying the current architecture.

The steps to run the example are:

1.	Starting the order system

2.	Entering a new order


Starting the Order System

1.	Start your Microsoft Visual Basic development environment by double-clicking on the ordersys.vbp project file, which you can find in the folder where the Order System sample is installed.

2.	Run the program by choosing Start With Full Compile from the Run menu. (Click here to view the displayed dialog box.)

If you have problems running the order system, make sure that:

•	The database files ordersys.mbd and ordersys.ldb are located in the same folder as the project file, and that the files are writable (not read only).

•	The correct DAO Object Library is loaded. Choose References on the Project menu and check the appropriate library.

•	None of the references in the References dialog box are marked as “MISSING:”.


Entering a New Order

After having successfully started the order system application you are now ready to enter a new order. An Order Id has already been allocated in the Order dialog box.

1.	Start by assigning a customer to the new order. By default the first customer found has been chosen, which is “101”, “Baron's Inne”, at “499 N. Gulp Rd, King of Prussia”. Click the Name box to view all other customers and select one of them.

2.	Continue by adding new rows to the order: Click New to open the Order Row dialog box. (Click here to view the displayed dialog box.)

3.	Select an article from the Article Name box and see how the information in the dialog box changes.

4.	To populate the Article Name list with seafood articles with a higher article identifier, type “2*” in the Article Id box and press <CR>.

5.	Select any article, enter a number in the Quantity field, and click OK.

6.	The Order dialog box now presents the new order row and recalculates the total order sum after each new order row has been created.

7.	Click OK to accept and register the new order.

8.	Click OK to exit the order system.


Introduction to Browsing

In this exercise, you'll use Visual Modeler to get acquainted with the design model of the order system. Visual Modeler provides you with several mechanisms for browsing the model. The tutorial takes you through the following exercises:

1.	Opening the order system design model

2.	Browsing the model

3.	Browsing the class diagrams

4.	Browsing the business objects


Opening the Order System Design Model

1.	Start the Visual Modeler application.

2.	Click Open on the File menu.

3.	In the dialog box, open the folder where the order system sample has been installed.

4.	Double-click on the ordersys.mdl file. Visual Modeler now opens the sample model and displays a diagram called the Three-Tiered Service Model. (Click here to view the displayed diagram.)

This diagram shows the architecture of the order system application, that is, the classes of the design model and the relations between them. Defining and maintaining the architecture and relationships within the system is one of the most important aspects of large-scale iterative development.

The Three-Tiered Service Model diagram supports the three-tiered architectural approach used when building Microsoft Visual Basic applications. It separates the contents of the system into three conceptual tiers of services: user services (left pane), business services (middle pane), and data services (right pane). It is a special kind of class diagram, called a three-tiered diagram.

To the left in the application window, a browser window lists the contents of the order system design model in a hierarchical order. (If you cannot see the browser in your Visual Modeler application window, select Browser on the View menu.)

The diagram notation used in this tutorial is a subset of the Unified Modeling Language (UML). Please refer to the online help for descriptions of the different modeling constructs.


Browsing the Model

As you can see in the browser, a system can be described from three different views: a logical view, a component view, and a deployment view. The logical view is the actual design model of the system, which you will examine and change during this tutorial.

The component view describes the physical structure of the system and the mapping between the classes in the model and software components. The deployment view, which is empty in this example, is used to show the different processes of the running system and how they are related.

1.	To view the logical view in the browser, expand the Logical View package by clicking on the “+” sign.

2.	Then expand the three services in the same way. The different symbols in the browser mean:

 = Package (a set of closely related classes)

 = Class

 = Interface

 = Class diagram

Note that:

•	The “<<xxx>>” in front of the name of each model element indicates the stereotype of the element. Stereotypes can be used to further specify the type of a model element. Visual Modeler uses the stereotype of a model element during code generation to decide what kind of Visual Basic item to generate from it.

•	Below the browser there is a documentation field. This field contains a textual description of the currently selected model element or diagram. (If the documentation field is not displayed, select Documentation on the View menu.).

•	If you are not familiar with a three-tiered architecture yet, select each one of the service layers user services, business services, and data services, and take a look at their descriptions in the documentation field.

3.	Expand the Component View and take a look at its contents. The different symbols in the browser mean:

 = Component diagram

 = Component

•	The order system is implemented as one single component, an executable called OrderSystem, which corresponds to the ordersys.vbp project. All classes in the model are assigned to, and thereby implemented by, the OrderSystem component.

•	The other two components, VB and DAO, are existing DLLs that have been reverse engineered into the model because they are used by several of the classes in the model. Note that, in the Logical View, there is a package for each such component containing the interface classes provided by the component.

4.	Open the Main diagram of the Component View. Note, for example, that the VB and DAO interfaces that the order system is dependent on are shown as interface classes in the diagram. (Click here to view the displayed diagram.)

5.	Close the Main component diagram.


Browsing the Class Diagrams

As you can see in the browser, the design model is illustrated in several diagrams, each one with its own purpose. The Three-Tiered Service Model diagram, located on the top level in the Logical View, is the main diagram of the order system design model. There are other diagrams that illustrate interesting details about parts of the model.

For example, look at details about the Order class:

1.	Double-click on the Order Details diagram in the Business Services package. This diagram shows details about the Order class, such as: its methods, its properties and its relations with other classes. (Click here to view the displayed diagram.)

2.	Note that the Orderrows relationship is marked with a “*” sign. This indicates that the Order class may reference a collection of OrderRow objects. Also, note that property procedures are assigned the stereotypes <<Get>>, <<Set>>, and <<Let>> in the model.

3.	Close the diagram.


Browsing the Business Objects

Each class is defined by a specification. To view the specification of one of the classes in the Business Services package:

1.	Double-click on the Order class to open its specification.

2.	Examine the information behind the different tabs. For example, on the Components tab, note that the class is assigned to the OrderSystem component, which means that the OrderSystem component implements this class. (Click here to view the Components tab.) Then close the specification dialog box.

3.	As important as understanding the detailed specification of a class is to know who uses the class. Therefore, select Order in the Three-Tiered Service Model diagram, and click Show Usage on the Report menu.

4.	Select one of the diagrams in which this class is used and click Browse. Look at the diagram and the relationships between the classes. (Move the Show Usage dialog box if it covers the opened diagram.)

5.	Close the diagram and the Show Usage dialog box.


Introduction to Stereotypes and Model Properties

The next step is to study how the model is prepared for code generation. Most of the implementation details of the Visual Basic code are specified in the class, relationship, and method dialogs, but some detailed implementation decisions, specific to the Visual Basic programming language, must be entered as stereotypes or model properties of the model elements.

Note: Other words for “model properties” are “code generation properties” or “code generation options”.

In the following exercises, you will view some of the settings of stereotypes and model properties in the order system example:

1.	Examining class stereotypes

2.	Examining naming conventions


Examining Class Stereotypes

The stereotype of a class is used to indicate a mapping to which type of Visual Basic project item the class corresponds. When generating code for a class, Visual Modeler creates a Visual Basic item of the specified type.

1.	In the browser, expand User Services, and double-click on the dlg_Order class. The specification for the class then opens with the General tab displayed. (Click here to view the displayed dialog box.)

2.	As you can see, the stereotype is set to “Form”. Thus, the dlg_Order class represents a form in the corresponding Visual Basic project. To get a list of other class stereotypes, click the arrow in the Stereotype field.

3.	Now, close the specification for dlg_Order.

Note: Visual Modeler can reverse engineer most types of Visual Basic items, but the application cannot generate code for all types. For example, Visual Modeler can reverse engineer forms but not generate them.


Examining Naming Conventions

1.	Open the specification of the Order class by double clicking on the class.

2.	Select the Relations tab.

3.	Double-click on pOrderrows to open the specification of that relationship. Note that relationships have two code generation tabs, Visual Basic A and Visual Basic B, one for each role.

4.	Select the Visual Basic A tab to view the model properties for role A. (Click here to view the displayed dialog box.)

5.	Take a look at the value of DataMemberName, which is “$relationship”. This value means that the generated Visual Basic property will get the same name as the relationship, that is Orderrows.

6.	Also, note that NameIfUnlabeled is set to “the$supplier”. This setting instructs the code generator to generate the variable name theOrderRow if the role is unnamed. In this particular case, role A is named Orderrows, so this option is not activated.

7.	To reuse specific model property settings between classes, Visual Modeler lets you define model property sets and attach a whole set to a class. In the Set field you can see that the “default” model property set is currently attached to this role. Also, in the Source field you can see that the values of all model properties, except NameIfUnlabeled, override the attached set, but the value of NameIfUnlabeled is the default value.

8.	Close the specifications.

9.	Close the Visual Modeler application by choosing Exit from the File menu


Introduction to Round-Trip Engineering

Round-trip engineering, or code-to-model and model-to-code generation, takes two forms in Visual Modeler:

•	If you have a Visual Basic project but not a design model of your system, you reverse engineer a new model from the project (which you are going to do in the next exercise).

•	Having a model that is synchronized with your existing Visual Basic code, you round-trip engineer your model. Information entered into the code is generated into the model using the Reverse Engineering Wizard. Information entered into the model is generated into the code using the Code Generation Wizard.

The folder where the order system is installed contains the source code. You use this code to practice both procedures in the following exercises:

1.	Reverse engineering a new design model where the source code for the order system is used to generate a completely new design model of the order system. (You also have the opportunity to practice reverse engineering on ActiveX components, because the order system source code uses data access objects (DAOs).)

2.	Examining the generated model

3.	Creating classes and associations in the model

4.	Updating the code from changes in the model

5.	Updating the model from changes in the code

6.	Browsing the code and the model


Reverse Engineering a New Design Model

You will now generate a new design model from the Visual Basic source code of the order system:

1.	Open the ordersys.vbp project in Microsoft Visual Basic (if it is not already open).

2.	In Microsoft Visual Basic, choose Visual Modeler from the Add-Ins menu, and then click Reverse Engineering Wizard.

3.	In the displayed Selection of Model dialog box, click New.

4.	Visual Modeler is then started with a new model opened. Also, a Welcome dialog box for the Reverse Engineering Wizard is displayed. Click Next> after you have finished reading the text.

5.	The Selection of Project Items dialog box is displayed.

6.	Deselect Save model and project before reverse engineering. (By selecting this option, you can use the Revert to Last Saved command on the Tools menu  to revert to the current version of the model and code after the reverse engineering process.)

7.	Open the project items by clicking on the “+” sign, and take a look at their contents. Select the project items you want to reverse engineer (click here to display a picture of the dialog box):

•	Class modules: all of them

•	Module: Db

•	Form: dlg_Order

•	ActiveX Reference: DAO

Note that some of the Visual Basic project items listed in the picture of the Selection of Project Items dialog box may not be available in your Visual Basic environment. The project in the picture is from Microsoft Visual Basic Enterprise Edition.

8.	Click Next >. A new dialog box is shown where you can assign the selected project items to packages in the new design model. (You can also create new packages in this dialog box, but that is not part of this exercise.)

9.	Assign dlg_Order to the User Services package by dragging and dropping it onto the User Services in the Logical packages list.

10.	Assign Article, Articles, Db, Persistence and DAO to the Data Services package and the rest of the project items to the Business Services package. Take a look at the Assigned To field to make sure that all project items are assigned. A project item that is not assigned will be assigned by default to a package named Unassigned. (Click here to display a picture of the dialog box.)

11. Click Next> to get a summary of what will be generated and estimation on how long it will take.

12. Click Finish to build the new model from the chosen code. When the generation is finished, take a look at the result on the Summary and Log tabs in the Summary dialog box. Then click Close. (You can access and save the log later, by selecting Log from the Window menu in Visual Modeler.)


Examining the Generated Model

Now you have reverse engineered the Visual Basic project for the order system, and you have a design model of the system. Activate Visual Modeler. The following things have happened:

1.	In the Component View, a component with the stereotype “EXE”, and with the same name as the corresponding project, has been created. On the Visual Basic tab of the component specification, you can see that the ProjectFile model property holds the name and location of the ordersys.vbp file. Also, the Realizes tab shows that all the reverse engineered classes have automatically been assigned to this component.

2.	In the Logical View, note that for each selected project item, the corresponding classes have been generated into the correct service package.

3.	Each generated class has been inserted into the Package Overview diagram of the package where it belongs, as well as into its service tier in the Three-Tiered Service Model diagram.

4.	All relationships between the class modules in Visual Basic have become relationships between the corresponding classes in the design model. To avoid crossed association lines in the Three-Tiered Service Model diagram, you may have to move the classes in the diagram. (Click here to view an example.)

5.	For the selected ActiveX component DAO, a package called DAO has been created. If you expand that package, you can see that interface classes have been generated for each of its interface elements. Note that the interfaces of a component belong to the logical view, but the actual component belongs to the component view. Thus, in the Component View, notice that a DAO component has been created.

Note: If the generated relationships are not displayed in the diagram, click Filter Relationships on the Query menu. Then select all relationship types (which should already be done by default) and click OK.


Creating Classes and Associations in the Model

Now, you can practice the round-trip possibilities by creating a new business service class and an association in Visual Modeler and then updating the code with those changes.

1.	On the Tools menu, click Class Wizard.

2.	Give the new class a name by typing “Invoice” in the Name field. Click Next >. The Documentation dialog box opens.

3.	Write a brief description of the new class. Click Next >. The Service Type dialog box opens.

4.	Assign the new business class the appropriate tier, by selecting Business Services. Click Next >. The Inheritance dialog box opens.

5.	Because no other class implements this class, make sure that No is selected. Click Next >. The Methods dialog box opens.

6.	In the Methods list, click the right mouse button and select Insert. A new method is added to the new class. Give the new method a name by writing “Calculate” in the Name field on the General tab.

7.	Make sure that Visual Basic is selected in the Fundamental Types Language field. If so, the methods, arguments, and properties of the class will get Visual Basic data types. Then define the method’s return type by selecting Integer from the Return type combo box. (Click here to display a picture of the dialog box.)

8.	Click Next >. The Properties dialog box opens. In the Properties list, click the right mouse button and select Insert. Give the new property a name by writing “Number” in the Name field on the General tab. Define the return type by selecting Integer in the Type field.

9.	Click Next >. A summary of the new class is displayed. Click Finish to create the class.

10.	Activate the Three-Tiered Service Model diagram. As you can see, the new class has automatically been inserted into the appropriate tier.

11.	Create a relationship between Invoice and Order by clicking the association symbol in the toolbox. The cursor turns into a plain arrow. Place the cursor on the Invoice class in the diagram. Press the mouse button and drag the association to Order. Release the button.

12.	Name the new role of the Order class by right clicking on the Order side of the association and selecting Role Name from the menu. By default, the name of the new role becomes “theOrder”. (You can also give the role a name in the specification dialog box for the relationship.)

Now you have created a new class with a property, a method, and a relationship. When you become familiar with the tool, you may choose to create classes, properties and methods directly in a diagram. To do that, place the cursor in the name field of the class and press the right mouse button. A pop-up menu appears, which contains the New Property and New Method commands. Here you can use inline editing to specify each new property and method, but you have to be familiar with the syntax.


Updating the Code from Changes in the Model

When you are satisfied with the changes in the model you are ready to generate code from the new Invoice class.

1.	First, you have to assign the new class to the component that implements this class. (Note that a class can be assigned to and implemented by several components.) Visual Modeler needs that information to know which Visual Basic project the class belongs to. To assign the new class to the OrderSystem component, drag OrderSystem from the component view in the browser and drop it on the Invoice class in the Three-Tiered Service Model diagram.

2.	Open the specification of the Invoice class. On the Components tab, the check mark next to the OrderSystem component means that the class is assigned to that component. Close the specification.

3.	In the Three-Tiered Service Model diagram, right-click on Invoice and choose Generate Code.  (Click Next> if the Welcome dialog box is shown.)

4.	The Select Classes dialog box is shown where you select the classes for which you want to generate code. Note that Invoice is already selected because you selected it before starting the Code Generation Wizard. Click Next>.

5.	The Preview Classes dialog box is shown. Here you can ask for a code preview of each selected class. Because Invoice is a new class, you probably have to change the code generator’s default mapping to Visual Basic code. Therefore, select Invoice and click Preview.

6.	Get acquainted with the different preview dialog boxes in the Code Generation Wizard by clicking Next> and <Back. The Wizard shows the current model property settings for the class. These are stored in the specification of each class and shown on the Visual Basic tab in the specification dialog box. (Remember that you examined model properties in a previous exercise.) You are now going to change one of these settings from the Code Generation Wizard.

7.	Go to the Role Options dialog box and select the association you previously created between Invoice and Order. In the text box at the bottom of the dialog box you can see the code that should be generated with the current setting.

8.	Change the setting by, for example, selecting Property Get, which generates a Property Get procedure for the association. Note how the name of the generated variable is changed according to the naming conventions defined by the default values of the DataMemberName and NameIfUnlabeled model properties. (Click here to display a picture of the dialog box.)

9.	When you are satisfied with your preview and settings, click Finish and then click Next>.

10.	The General Options dialog box is shown. Here you can instruct the code generator to insert debugging code and comments, among other things. Clear all options box and click Next>.

11.	The Finish dialog box is shown where you can see a summary of what will be generated. Now, click Finish to start the code generation.

12.	Because the code contains some project items that were not reverse engineered into the model, a Delete dialog box is shown. To keep the listed project items in the project, select << All, and click OK.

13.	When the code generation is completed a Summary dialog box is shown. Take a look at the result on the Summary and Log tabs, and then click Close.

14.	Select the Invoice class. Press the right mouse button and choose Browse Code from the menu. (Click here to display a picture of the code window.)

A Visual Basic class module called Invoice has now been created as you can see in the Microsoft Visual Basic window. Note how the property, method, and relationship were mapped to Visual Basic code.

Note: For each generated project item, member, and method, Visual Modeler adds an identifier as a code annotation (for example “ModelID=3237F8CE0053”), which identifies the corresponding class, property, role, or method in the model. Those are not displayed in the code examples here.


Updating the Model from Changes in the Code

In the previous exercise, you practiced code generation from changes in the design model. Now, suppose that you have just created a new code class called dlg_OrderRow, and want to update the design model with the new class.

1.	In Visual Modeler, start reverse engineering by clicking Visual Basic on the Tools menu, and then select Reverse Engineering Wizard. If a Selection of Project dialog box is displayed, select the ordersys.vbp project and click OK. (Click Next > if a Welcome dialog box is shown.)

2.	In the Selection of Project Items dialog box, select the dlg_OrderRow Visual Basic form. Deselect Save model and project before reverse engineering.

3.	Click Next > and assign dlg_OrderRow to the User Services package.

4.	Click Next > and take a look at the summary of what will be reverse engineered. Click Finish to update the new model with the new class.

5.	When the Wizard is finished, the result is shown in a Summary dialog box. The Summary tab shows the effects of the reverse engineering, and the Log tab lists any warnings or errors.

6.	Click Close and look for the new class in the browser and the Three-Tiered Service Model diagram. As you can see, a dlg_OrderRow class has been created and assigned to the OrderSystem component.


Browsing Code and Model
Browsing the Code and the Model

The Visual Modeler and Microsoft Visual Basic applications are tightly integrated—and not only with respect to code and class generation. You can also use each application to browse corresponding code or classes in the other tool.

To view the class module that corresponds to a selected design class:

1.	Select the Order class in the Three-Tiered Service Model diagram.

2.	Select Source Code on the Browse menu. Microsoft Visual Basic is then activated and a window with the Order class module source code is opened. (Click here to display a picture of the code window.)

To open a diagram where the design class that corresponds to the selected project item occurs:

1.	Select the dlg_OrderRow form in Microsoft Visual Basic.

2.	Click Visual Modeler on the Add-Ins menu, and then click Browse Class Diagram. If the project is related to none or several models, select one of the models in the displayed dialog box.

3.	A dialog box with a list of the diagrams where the corresponding design class occurs is displayed. The corresponding design class is currently part of two diagrams: the Package Overview class diagram in the User Services package and the Three-Tiered Service Model diagram. To open and activate one of them, simply double-click on its name.

You have now completed the basic steps in using Visual Modeler. For complete information about the tool and round-trip engineering, please refer to the Visual Modeler online help.