The Visual Basic .NET Debugging Windows

Directives

17.1 Increment the version number each time you compile a program.

When you compile a project into a distributable component, a version number is included in the compiled file. This version number can be used by installation programs to ensure that files aren't overwritten with older versions. In addition, you can view the version number of a file by using Windows Explorer see Figure 17-3 which makes troubleshooting faulty installations quite a bit easier.

The version number of a compiled program isn't arbitrary. The number is defined in the AssemblyInfo.vb file in a Visual Basic .NET project, as described earlier.

Figure 17-3. Right-clicking a file in Windows Explorer allows you to view the file's properties, which include the version number.

Even if you're only compiling a component for a quick internal test, increment the version number (in this case, the revision number). It's tempting to not "waste" a version number, but this is silly you can maintain thousands of build and revision numbers, and it's simply far too risky to have two different versions of a compiled program floating around with the same version number.

17.2 Display a program's version number in the About dialog box.

Version numbers greatly aid the customer support process. When a user calls about a problem and you believe the problem is fixed, you need to know which version of the program the user is running in order to compare it against your internal revision document. It's best to make things easy for the user. Asking a user to open Windows Explorer, find a file, right-click the file, and click the Version tab of the Properties dialog box so that you can determine the file's version isn't wise.

All professional programs should include an About dialog box. This dialog box usually contains licensing information such as the registered user of the software and a serial number. In addition, most About dialog boxes include the version number of the program. (See Figure 17-4.)

You should display version numbers in the same order in which they're defined: Major.Minor.Build.Revision.

When displaying version information, it's not necessary to show the right-most portions of the version if they are 0. For example, rather than showing 8.1.0.0, you could just show 8.1. Some vendors prefer not to keep track of a revision number, but rather always increment the build number instead. In this case, there's no point in displaying a 0 for the revision number (that is, 8.1.4233 instead of 8.1.4233.0).

Figure 17-4. Include the version of your program in its About dialog box.

The major, minor, build, and revision numbers of the program are available in code, but getting to them is not so obvious. However, when you receive the values in code, they are always accurate, so you should avoid hard-coding these version numbers in your application. The following statement can be used to display the version number of a program in a label control:

' This code pulls the version information from the assembly. With System.Reflection.Assembly.GetExecutingAssembly.GetName.Version    lblVersion.Text = "Version " & _                      .Major & "." & _                      .Minor & "." & _                      .Revision End With 

17.3 Install a component in the same folder as the client using the component.

One of the benefits of the new versioning scheme provided by the common language runtime is the ability for components to run "side by side." This doesn't necessarily mean components run in the same folder, but rather multiple versions of a component can exist in different locations, and each version is accessible to a different client. In the past, COM components had to be registered, and only one version of a component could be registered at a time. This means that you could have a dozen copies of a component file on a computer (which often happened), but clients would always use the same version of the component the component file most recently registered. Now that multiple versions can co-exist on a single machine, the best approach to component installation is to install a copy of a component in the same folder as the client using that version of the component. If you have a component used by multiple clients, the end result would be that you would have multiple copies of the same version of the component on the hard drive, but disk space is cheap.

To install a component (such as a DLL) in this manner, you simply place the component file in the same folder as the client that will use it. In practical terms, this means adding the component file to your setup project and choosing to install it in the Application Folder. That's it there are no registry changes or any other action required. When the client attempts to instantiate an instance of the component, the common language runtime will look in the Application Folder, find the component file, and load it into memory. To distribute an update to the component, simply build a new version and copy it over the old file. One of the benefits of installing a separate copy of a component in the Application Folder of each client that uses the component is that you can install an updated version for one of the clients while leaving the others alone reducing the risk of inadvertently breaking one of the other clients. The downside is, of course, that if you want the updated component used by all clients, you have to install the new file in all applicable folders.

Note

When you want to distribute a component as a shared component, rather than distribute the component to the folder of each client, you need to create a merge module. Using merge modules is beyond the scope of this book.

 

17.4 Preserve compatibility when rolling out a new version of a component.

Distributing updates to components requires that you give careful consideration to code changes prior to distribution. You don't have the "luxury" of worrying only about breaking sections of your component; you must also make sure not to break the program that uses the component.

Simply providing unique version numbers in each build of an update does not in itself ensure that applications using the component won't have any problems. The relationship between the new version of a component and an older one, and the extent to which they are interchangeable, is called version compatibility. When you distribute an update to a component, make sure that the new component is backward-compatible with previous versions of the component so that a client application making use of the component won't be broken.

You might distribute an updated component for many reasons. Perhaps you've fixed bugs or added new features. Sometimes the changes to a component are minor and occur only within existing functions. Programs that use the updated component are blind to the changes and are able to use the component without any problems. When a new version of a component is created so that it doesn't break applications that use a previous version, it's said to have backward compatibility.

Suppose that you've created the following procedure in a distributed DLL. (This function takes two numbers, multiplies them, and returns the result. Of course, you would never use such a cumbersome technique to multiply two numbers, but it serves well to illustrate a point.)

Private Function Multiply(ByVal intNumber1 As Integer, _                           ByVal intNumber2 As Integer) As Long     ' Purpose   :  Multiply two numbers.    ' Accepts   :  intNumber1 and intNumber2 - the numbers     '              to multiply.    ' Returns   :  The result of multiplying the numbers.    Dim intCount As Integer    Dim lngResult As Long    Try       lngResult = 0       ' Add the second number to itself. Do this as many times as        ' specified by the first parameter.       For intCount = 1 To intNumber1          lngResult = lngResult + intNumber2       Next intCount       Return lngResult    Catch         ' Deal with any errors here.    End Try End Function 

Although this function works, it is by no means efficient. Now, assume you realize that you can perform this task by using the multiplication operator (*), so you change the procedure like so:

Private Function Multiply(ByVal intNumber1 As Integer, _                           ByVal intNumber2 As Integer) As Long     ' Purpose   :  Multiply two numbers.    ' Accepts   :  intNumber1 and intNumber2 - the numbers     '              to multiply.    ' Returns   :  The result of multiplying the numbers.    Try       Return intNumber1 * intNumber2    Catch        ' Deal with any errors here.    End Try End Function 

Because you changed only the internals of the function not the way the function is called or what it returns the programs using the existing version of the DLL can use the new version without modifications. The new component is backward-compatible with the previous version of the component.

Some changes to components aren't so benign. Say you developed a DLL that provides the following method:

Public Sub AddRecord(ByVal firstName As String, _                      ByVal lastName As String)     End Sub 

Now, because of users' requests, you decide that you want the function to also accept a phone number. You change the definition to:

Public Sub AddRecord(ByVal firstName As String, _                      ByVal lastName As String, _                      ByVal phoneNumber As String)     End Sub 

When you compile the new DLL and distribute it to users, existing clients can no longer call this method! When an attempt is made to call the broken method, a dialog box like the one shown in Figure 17-5 is displayed a very serious problem indeed. In order for an existing application to use the function in the new DLL, the existing application would need to be modified, recompiled, and redistributed. Changing the parameters, data types, or return types of a method will break the compatibility with previous versions of the component.

Figure 17-5. Clients will no longer be able to use a component if you break compatibility.

17.5 Document changes in a Readme file.

Product development often occurs at a rapid rate, yet it can span months or years. Because it's impractical to expect a person or a team to remember all the various changes that are made and in which versions those changes were made, it's important to maintain a journal of program changes. Usually, this journal is written as a Readme file.

Most users are familiar with Readme files. A Readme file is a document that accompanies a program during a new installation or an update. Users view the Readme file to learn about program changes that might or might not have made it into the product documentation. Use the Readme file as a vehicle to notify users of important changes and additions.

You might choose to maintain two versions of a Readme file: one for users and one for internal use. Generally, Readme file information for users is of a more general nature than that recorded in internal documents. Users don't need to know the specific technical implementation of a feature, just that the feature is available and how to access it. However, internal documents are used as a reference by developers, and therefore, they need to contain specific information. You can maintain two documents, or you might choose to maintain one document and remove the items intended only for internal use prior to distributing the file with the product.

You can put just about anything you want in a Readme file. Many companies choose to include a welcome letter, contact information, and marketing information. My advice is to keep the Readme file as focused as possible. If you want to distribute a lot of non-technical information, consider putting it into other document files and including a reference to those files in the Readme document. Regardless of what other types of information you do include in the Readme file, you should always provide revision information.

As you make changes or enhancements to your product, document them in the Readme file in a clear and concise manner. It's important to associate all items in the Readme file with a specific revision (version number) of the program. When distributing a Readme file, you can choose to lump all revision changes under one build number rather than show all the various revision numbers between releases, but do keep track of the changes in each revision for internal use. Sooner or later, you're going to need to know the exact version in which a change occurred.

17.6 Back up your files.

Too often I hear about a company or an individual that has lost data and has no current backup. (This happens more frequently than you'd think.) Before computers became mainstream, ignorance was the most common reason for this. However, even then, ignorance was a marginal excuse. Most software documentation includes information on the necessity of backing up files. Now, the need to back up files is well understood, and CD-ROM burners, tape units, and large hard drives are so common and inexpensive that it's inexcusable not to back up your files.

Of course, your particular situation should dictate the type of backup plan you employ. If few changes are made to a project, a weekly backup might be sufficient. For most development shops, nightly backups are the norm. Don't forget to rotate your media. At times, backup media can go bad, and backups can become corrupted. It's best if you keep at least five successive backups. In addition, you should archive backups of important milestones such as product releases.

Tip

Consider this: You have a problem, and you need to go to a backup. No big deal you always back up your files. Soon you find out that the file you need isn't there because the file or its folder wasn't specified in the backup plan. It's happened to me a few times and to other people I know, as well. You should periodically restore a backup just to make sure that everything you want backed up is being backed up. It's easy to forget to add a folder to your backup plan, and this mistake can be disastrous. The time to find out that you're not backing up a file is not when you need the file.

 

17.7 Use Microsoft Visual SourceSafe to maintain versions of source code.

Keeping backup files of all revisions of all project files is next to impossible. For complex projects, you should seriously consider using a program such as Visual SourceSafe to manage your projects. Visual SourceSafe keeps track of all the revisions of all files in a project, allowing you to easily revert to a specific revision when necessary. Chapter 18 explains the implementation of Visual Source Safe in detail.