Directives and Assemblies

Directives are Visual Basic statementsbut then again, they're not. The two key directives#Const and #Ifprovide instructions to the compiler on how to handle a block of Visual Basic source code. (There is a third directive, #Region, that helps to visually present source code within Visual Studio, but it has no impact on the compiler or the final compiled application.) By using directives, you can tell the compiler to include or exclude specific chunks of source code from the final project. So, they aren't really Visual Basic source code statements, but they are only available in Visual Basic.

Why would you want to include or exclude code in an application? Well, I can think of several good reasons, some of which involve the CIA and former Federal Reserve chairman Alan Greenspan. But the most common use is when you want to produce two different versions of your application, based on some condition. For example, you may sell an "express" version and a "professional" version of a product. Much of the code is identical for the two versions, but the professional version would include features not available in the express version. Also, the express version may include a simplified presentation for a feature that has a more complex usage in the professional edition.

Some software products fulfill this need by using standard Visual Basic conditions.

If (professionalVersion = True) Then    ShowWhizBangFeatures() Else    ShowLaughableFeatures() End If 

This, of course, works just fine. But the express application still contains all of the enhanced features. But it can't access any of that code, so why even include it on the installation CD? If you use directives, you can mark down that problem as solved. Directives used conditional expressions, much like the professionalVersion = True condition in the previous block of code. But they are defined with the #Const statement, and are called compiler constants.

#Const fullVersion = True 

This statement defines a Boolean compiler constant. It can only be used with directives; if you try to use fullVersion in a standard Visual Basic statement, the compiler will complain. But it will work just fine in the #If directive.

#If (fullVersion = True) Then    ShowWhizBangFeatures() #Else    ShowLaughableFeatures() #End If 

This code looks a lot like the previous code block, but with the added "#" signs. It looks the same but it's not. With the plain If statement, the code that gets compiled into the final application is the following:

If (professionalVersion = True) Then    ShowWhizBangFeatures() Else    ShowLaughableFeatures() End If 

Yeah, the whole block of code. But with the directives, what gets included in the compiled application depends on the value of fullVersion. If fullVersion is True, then this gets compiled into the compiled application:

ShowWhizBangFeatures() 

The other four lines are gone; they've vanished . . . into thin air, as if they never existed. But in this case, it's a good thing. The goal was to have a version of the assembly completely devoid of the undesired code, and that's what happened.

To set the fullVersion compiler constant to generate the full version, you include this line at the top of each source code file that includes conditional #If code blocks:

#Const fullVersion = True 

When you're ready to generate the "express" version, just change each of these lines to their False counterpart:

#Const fullVersion = False 

Somehow, changing this line in every source code file that needs it seems like a lot of work, and it is. And what happens if I forget to set one of them to the right version? No good, I can tell you.

To keep Visual Basic developers from running down the halls screaming more than they normally would, Visual Studio provides a few different ways to set compiler constants once, and have them apply to every part of the application. The most common way to do this is through the project properties' Compile panel (see Figure 5-3). Click on the Advanced Compile Options button, and then add your global compiler constants to the Custom constants field.

Figure 5-3. This is a whole lot easier than all that typing

Now, by adding either fullVersion=True or fullVersion=False to this field, you can build different versions of the application. The Visual Basic compiler also provides features that let you set up different compile scripts for your project. I won't talk about it in this book, but you can read up on the MSBuild tool in the Visual Studio documentation if you need this level of control.

Besides Booleans, compiler constants can be numbers and strings. The Visual Studio environment also defines some compiler constants for you. The DEBUG and TRACE constants are True or False based on the Define DEBUG constant and Define TRACE constant checkboxes that appear in Figure 5-3. The VBC_VER constant identifies the version of the Visual Basic compiler being used; it is set to 8.0 in Visual Basic 2005.