Free!  FoxPro to WPF screen converter
   Almost free!  One day of FREE VFP to WPF evaluation of your FoxPro app ONSITE
   Free!  Read the foreword to Les' new book (available here)...
Skip Navigation Links

Building Your First StrataFrame Application

Ten minutes may change the way you build software


Les Pinter

Login or register to download source code

Coding time: 10 minutes.    See the video

Jump to:   Install StrataFrame   The Data   SF Windows App   The Menu   Maintenance Forms   Searching   Conclusion 

     


Introduction

In this article, you're going to see how incredibly simple it is to build high-quality, useful applications in C# or VB in a fraction of the time you might have thought it would take.

The secret is the StrataFrame framework - a collection of forms, controls, components and methodologies, bound together by Business Objects - classes generated by the StrataFrame Business Object Mapper - that contain the code necessary to retrieve and save their associated data from SQL Server, Oracle, FoxPro DBFs, and just about any other data store.


Installing StrataFrame
top

If you haven't already done so, you'll need to install StrataFrame. Go to StrataFrame.net and request a 60-day evaluation copy. When your registration email arrives, it will contain a key that you can use to register your copy. If you feel that two months isn't long enough to evaluate the software, take a look at the articles at LesPinter.com; each one comes with an estimate of how long it takes to go through the article and learn how to do various things, and at this moment(early December of 2009), the total time to go through every article on the website is less than two hours.

The installation process will add a StrataFrame menu pad to your Visual Studio 2008 IDE. The toolbar contains ten options, only one of which we'll use in this article. The Business Object Mapper is the first selection on the StrataFrame dropdown menu, and it's used to generate code that makes communicating with your data as easy as you hoped it would be before you saw .NET. More on that later.


The Data
top

StrataFrame works with just about every possible data source, but the easiest one to work with is SQL Server. If you installed Visual Studio 2008, a run-time version called SQLExpress was installed. It works, but it doesn't have a management console like other versions of SQL do. You can open it and perform many operations inside the IDE (create tables, add records), but it's sometimes easier to do things in a standalone environment. For that purpose, I recommend you go to Microsoft Download Center and download SQL Server 2008 Express. It's free, and it makes working with and learning SQL a lot easier. I'll wait right here.

Oh, good, you're back. Lets create the database and tables used for this example.

The database will be called FIRSTAPP. To create it, open SQL Management Studio, click on the New Query button, and then copy and paste the script shown below into the New Query window and click on the Execute button:


To verify that it worked, type

SELECT * FROM CONTACTS

Highlight this text and press F5 (or press Ctrl+E, or click on the ! Execute button.)

(If you highlight just one line or group of lines, only the selected statement(s) are executed.)

UID is an Integer IDENTITY column used as the Primary Key for the table. When you add a record to a table containing an IDENTITY column, SQL automatically assigns the next consecutive integer value to the column. And since UID is the PRIMARY KEY. you'll use it to identify the current record in update and delete operations. But you don't actually need to remember that; StrataFrame does it for you. We'll create a few more tables later on, but for now, this will allow me to demonstrate many of StrataFrame's cool features. Close SQL Management Studio and fire up Visual Studio.


Creating a StrataFrame Windows Application
top

From the IDE menu, select File, New, Project, then select either VB or C#, and from the StrataFrame templates group select StrataFrame Windows Application, supplying the project name FirstApp (Fig. 1):


After a few seconds you'll have a project that looks like Fig. 2 in the Solution Explorer (I clicked on the Show All Files button second from the left in the toolbar):


What's in a Main?

StrataFrame generates a startup program called program.cs if you're using C#, or AppMain.vb if you're using Visual Basic. They do a number of things that set up the application to operate properly, locate its data, set visual themes, and some other things. However, you rarely have to change this code and you certainly don't have to for this initial foray. Skip this section if you don't care about the details.

The Entry Point for this application is program.cs (If you're using Visual Basic, it's AppMain.vb.) It calls half a dozen methods that have been generated for you, and which you may (but probably won't) want to change at some point. Their names give a pretty good idea of what they do:

  1. EnableVisualStyles
  2. ShowGateway
  3. InitApplication
  4. SetDataSources
  5. UnhandledExceptionFoundEventHandler
  6. ShowLoginAndInitMainForm
  7. RunApplication

EnableVisualStyles turns on StrataFrame's theme management system, which lets you apply consistent color schemes across all of the components in the application. It's easy, and it's free. When you have a minute, you should try it out.

ShowGateway permits you to show an initial screen and optionally direct users to their destination, if there are several parts to your application. Listing 2 contains sample code that illustrates how it can be used. If you don't have a gateway form or a splash screen, ignore it.



InitApplication is used to load the application's forms collection (which, if you have only one startup form, consists of just that one form. At a minimum, then, you have to add that form here. (In case you wondered what that loDialog.SelectedFormIndex in the previous listing referred to, it's the index number of the startup form from the two forms added below. If there's just one, ignore it.) Initialization of the Localization (translation) subsystem, if it's to be used, also happens here (Listing 3):



SetDataSources is used to tell the application where to get the SQL ConnectionString or other mechanism needed to get to your data. The first time your users run the app, it will ask for a server and database name. It's then encrypted and stored locally. If you use StrataFrame's robust Security system, this is also where the program gets the information it needs to open and use the ten tables that deal with security. Listing 4 shows the typical settings.



When your application first runs, the user is prompted for the server and database names. Thereafter, it just looks it up using the string "MyApplication". If you want to force the application to look elsewhere, change the string. That's the only reason I ever had for changing it.

UnhandledExceptionFoundEventHandler is where you put your custom error handling, if you have any. If you don't need it, don't touch this routine.

ShowLoginAndInitMainForm shows the login form if you're using security, but since we're not in this simple demonstration, there's no generated code in your example. Good.

Finally, RunApplication runs the app.

It bears repeating that if you don't need anything special, you don't have to change a single line of the code in program.cs|AppMain.vb. I only described it to give you some idea of what else the framework provides for. It's there if you need it.


Adding a menu
top

Form1 is the first form that will be launched in your application. We'll use it as the canvas that displays the main menu and lets users navigate around the app.

In Fig. 3 I've added a MenuStrip with a File, Exit option that calls Application.Exit():


I'm also going to add a menuitem to expose my Contacts Table maintenance form, frmContacts (Fig. 4). We can't write the code yet, because we haven't yet created the form.



Adding a maintenance form
top

So let's create the form, shall we? In the Solution Explorer, right-click on the FirstApp project name directly below the Solution name and select Add, New Item, and from the available templates select SF Maintenance Form (Fig. 5), providing as the form name frmContacts:


There's no reason even to look at the new form, because before we can use it, we need to create a StrataFrame business object for the Contacts table.

Adding a business object

It's finally time to do something with our data. We created a Contacts table, but our application doesn't know anything about it. The way that .NET applications understand tables is by way of a class that has one public property for each column in the table. (If you're from the FoxPro world, you're probably rolling your eyes about now. Get used to it; data access in .NET has created many, many - er - job opportunities. We should be grateful.) And StrataFrame knows just what to do about it.

Right-click on the Project name in the Solution Explorer window and again select Add, New Item; then, from the list of available templates, select StrataFrame Business Object, and name it ContactsBO (Fig. 6):


The next screen will prompt you to switch to code view (Fig. 7):


Do so, and in the Data Retrieval Methods section add a single routine, consisting of one line of code (Listing 5):



Configuring the ContactsBO business object

All of the StrataFrame controls and containers contain events and methods that respond to the properties, events and methods of StrataFrame business objects. I can't begin to describe how many features are built into these components. Take a look at the properties and events of any StrataFrame control or component, and you'll begin to get the idea. If you've thought of it, and if you've wanted it, it's probably somewhere in a StrataFrame object. With that in mind, let's build a Business Object for the Contacts table and begin to explore what the framework can do with it.

Although you've created a business object called ContactsBO, it doesn't yet contain much of anything. You first have to open the BOM, select the business object, and 1 it, which generates a boatload of code. If you change the table, you open the BOM and generate the code again. You can also add custom properties (e.g. age derived from BirthDate) in a partial class associated with the business object, and they will be included again when you re-generate the business object.

From the StrataFrame pad of the IDE menu, select Business Object Mapper (Fig. 8)


First, select the Project node (FirstApp) and "configure" it (i.e. tell it what database to use). Note that you will probably use the Database Deployment Toolkit, not SQL Server, for your project repository. The little button at the lower right of Fig. 9 is where you build the SQL Server database connection string to be used by your application. Make sure you select FIRSTAPP as your database.


Next, select the ContactsBO node and click the Configure Business Object link in order to tell it which SQL database and table to use (Fig. 10)


Click on the Rebuild All button in the StrataFrame Object Mapper to generate the business object code, and then close the Business Object Mapper window. Be sure to rebuild your application. If you don't, your forms won't see the newly-generated business object.

Building the Contacts maintenance form

Now we're ready to build frmContacts: Open the form, and press Ctrl+Alt+X to open the toolbox. If you've select Tools, Options, Windows Forms Designer and ensured that AutoPopulate Toolbox is turned on, you'll see ContactsBO at the very top of the Toolbox. Drag it onto the form and drop it in the tray (Fig. 11), and press F6 to rebuild the project.


Drag and drop three labels and four textboxes from the StrataFrame Controls & Components toolbox and arrange them as shown on Fig. 12:


Press F4 to open the Properties Sheet, and then select the first TextBox. Notice that it already has its BusinessObject set to ContactsBO1. It was set when you dropped the SFTextBox on the form. The control detects the presence of a StrataFrame Business Object and sets the BusinessObject property accordingly. You do, however, have to tell it which BindingField to bind to. In the case of the first textbox, it's UID. And while you're at it, set the control's property to ReadOnly (Fig. 13). Then finish setting the BindingFields for the remaining textboxes.


We'll need to retrieve all records from the Contacts table when the form loads. In C#, open the code-behind for frmContacts and add this line, just after the InitializeComponent() call:

C#: contactsBO1.Fill();

In VB, double-click on the top of the form (not in the center - it's a panel control) and type in this single line of code in the resulting Load event handler:

VB: ContactsBO1.Fill()

We're now done with this form. All that's left to do is create a menu to launch the form.

The application menu

Close frmContacts and open Form1. Add a MenuStrip and, after the obligatory File, Exit menuitem, which calls Application.Exit(), add a Forms, Contacts menuitem with the event code shown in Listing 6, below:

Finally, go back to Form1, double-click on the Contacts menuitem, and add the two lines of code in Listing 6:



And press F5 to run. I'll bet the screen shown in Fig. 14 isn't what you expected. This screen is shown the first time a user runs the application. It collects and stores the ConnectionString information needed to connect to the data. The first screen just asks you for a friendly name to use when displaying available connections; your users will probably never see it.


The next screen prompts the user for the server and database names (Fig. 15):


Now, click on the Forms, Contacts menuitem and you'll see your Contacts form (Fig. 16):


Thereafter, the screens shown in Figs. 14 and 15 won't appear. However, if you change the server or database name, you'll need to have your users erase the encrypted files AppKeys.dat and Connections.dat containing this connection string information. On my Windows 7 computer it's in C:\ProgramData\MicroFour\ConnectionData. There's also a way to give your users a menu option in your application to do so. Search the StrataFrame forum for AppKeys.dat for details.


Adding a search capability
top

This is fine if we only have four contacts, but what if we have four thousand, or four hundred thousand? That's where the StrataFrame BrowseDialog comes in. It applies a filter to its associated business object.

Adding a Search form

To add a search capability, drag a BrowseDialog from the StrataFrame Controls & Components toolbox onto the form (Fig. 17):


There are four items that need to be configured before you can add your BrowseDialog to the form. They're highlighted in Fig. 18:


The first three are pretty easy to configure: The BusinessObject Type is ContactsBO; the Business Object to Populate is ContactsBO1; and the logical search field, given our Contacts table's structure, is LastName. So far, so good (Fig. 19):


The fourth item, SearchFieldsToDisplay, requires a little more work. Open the Properties Sheet for the BrowseDialog, find the BrowseResultsLayout property and and click on the button with the three little dots. You'll see the property editor shown in Fig. 20, below, where I've added three fields and begun to assign them to columns.

There are two steps in this process:

  • Pick the fields to display; they're assigned sequential item numbers starting with 0; and
  • Add these assigned item numbers to the columns list in the bottom of the dialog form.

You can combine fields in a column: {1}. {0} would display LastName, FirstName. In Fig. 21 I've added all of the columns except UID, which users don't really need to see, or even know about:


Now, all you have to do is select the ToolBar menu in the Maintenance form and assign your new BrowseDialog to the BrowseDialog property of the toolbar (Fig. 22):


Now when you run the form, you have a Browse button: (Fig. 23)


And when you click on Search, you have the ability to filter the Contacts table on, say, last names starting with "P":


Now I expect you're impressed at how much functionality you got for so little code. Really, most of what we did was fill in property values from dropdown combos. Welcome to StrataFrame!


Conclusion
top

I hope you had your stopwatch on, and I hope that you're pleasantly surprised. Compare this to the amount of code you'd write to do this by hand, then consider that you've only seen the tip of the iceberg. This is what .NET was supposed to be like.

On my website, I make an offer that I hope you'll take seriously. Download StrataFrame, and use it to build your next application. If you get stuck, email me at Les@Pinter.com, and I'll walk you through it. I fully expect to convince you that, if you're writing WinForms applications, you need StrataFrame. It's an offer you can't refuse.

See 'ya.

qqq


Copyright(C) Pinter Consulting, 2012Tel: +1 (650) 464-6924
Automated conversion between C# and VB by Visible C#/Visible VB from Tangible Software Solutions