Appendix A: The Visual Basic Compiler | Professional VB 2005 with .NET 3.0 (Programmer to Programmer)

When the .NET Framework was first introduced, one nice addition for the Visual Basic developer was the inclusion of a standalone language compiler. This meant you weren’t required to have the Visual Studio .NET 2002 IDE in order to build Visual Basic applications. In fact, you could take the .NET Framework from the Microsoft website (for free), and build Web applications, classes, modules, and more simply using a text editor such as Notepad. You could then take the completed files and compile them using the Visual Basic compiler.

The Visual Basic compiler is included along with the default .NET Framework install. The name of the compiler is vbc.exe and it can be found at

  C:\WINDOWS\Microsoft.NET\Framework\v2.0.[version]\vbc.exe

The vbc.exe.config File

In addition to the vbc.exe file, there is a vbc.exe.config file in the directory as well. This XML file is used to specify the versions of the .NET Framework the compiler should build applications for. Now that there are three versions of the .NET Framework available for our applications to work with, it is important to understand how this configuration file actually works.

With the .NET Framework 2.0 installed, you will find the vbc.exe.config file with the following construction:

  <?xml version ="1.0"?> <configuration>     <startup>         <supportedRuntime version="v2.0.50727" safemode="true"/>         <requiredRuntime version="v2.0.50727" safemode="true"/>     </startup> </configuration>

This .config file is basically a typical .NET Framework configuration file with the default <configu ration> root element included. Nested within the <configuration> element, you need to place a <startup> element. This is the only child element that is possible in the vbc.exe’s configuration file.

Nested within the <startup> element, you can use two possible elements: <supportedRuntime> and <requiredRuntime>.

The <requiredRuntime> element really is only needed if your application is going to run on the .NET Framework 1.0 (the very first iteration of the .NET Framework). If your application is going to run from the .NET Framework 1.0, then you build the vbc.exe.config file as such:

  <?xml version ="1.0"?> <configuration>     <startup>         <requiredRuntime version="v1.0.3705" safemode="true"/>     </startup> </configuration>

Currently, working with three different versions of the .NET Framework, you may wish to compile your applications using the Visual Basic compiler so that they work with multiple versions of the framework. To do this, you could use the <supportedRuntime> element:

  <?xml version ="1.0"?> <configuration>     <startup>         <supportedRuntime version="v2.0.50727" safemode="true"/>         <supportedRuntime version="v1.1.4322" safemode="true"/>     </startup> </configuration>

This construction states that the application should first try to run on version 2.0.50727 of the .NET Framework, and if this version of the .NET Framework is not found, then the next preferred version of the framework that the compiled object should work with is version 1.1.4322. When working in this kind of construction, you need to order the framework versions in the XML file so that the most preferred version of the framework you want to utilize is the uppermost element, and the least preferred version of the framework is the last in the node list.

The <supportedRuntime> element is meant for .NET Framework versions 1.1 and later. If you are going to utilize the .NET Framework version 1.0, then you should use the <requiredRuntime> element.

The <supportedRuntime> element contains two possible attributes: version and safemode. Both attributes are optional. The attribute version enables you to specify the specific version you want your application to run against, while safemode specifies whether the registry should be searched for the particular framework version. The safemode attribute takes a Boolean value, and the default value is false, meaning the framework version will not be checked.

Simple Steps to Compilation

To show how the Visual Basic compiler works in the simplest manner, let’s begin by looking at how to compile a single-class file:

Create a module called MyModule.vb. We’ll keep the module simple, as this example is meant to show you how to compile the items using the vbc.exe compiler:
```
  Module Module1     Sub Main()         Console.WriteLine("Howdy there")         Console.ReadLine()     End Sub End Module 
```
Once your file is in place, it is then time to use the Visual Basic compiler. If you do have Visual Studio 2005 on the computer, you can open the Visual Studio Command Prompt (found at Start All Programs Microsoft Visual Studio 2005 Visual Studio Tools Visual Studio Command Prompt). Once open, just navigate to the location of the file and then run the compiler against the file (shown shortly).
In most cases, you are probably going to be using the Visual Basic compiler on computers that do not have Visual Studio on them. In those cases, copy and paste the vbc.exe, vbc.exe.con fig, and vbc.rsp files to the folder where the class file you wish to compile is located. Then you can open a command prompt by selecting Run from the Start menu and typing cmd in the text box.

Another option is to add the compiler to the path itself. This is done by typing the following at the command prompt:
```
  path %path%;C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727 
```
Now you can work with the compilation normally and the vbc.exe compiler will be found upon compilation.
Once the command prompt is open, navigate to the folder that contains both the Visual Basic compiler and the class file that needs compiling. From this location, type the following command at the command prompt:
```
  vbc.exe MyModule.vb 
```

Items can be compiled in many ways using the Visual Basic compiler, but this is the simplest way to compile this module. This command compiles the .vb file so that it can be utilized by your applications. Running the preceding command produces the following:

 C:\CoolStuff>vbc.exe MyModule.vb Microsoft (R) Visual Basic .NET Compiler version 8.0.50727.16 for Microsoft (R) .NET Framework version 2.0.50727.16 Copyright (C) Microsoft Corporation 1987-2003. All rights reserved.

What does this operation actually do? Well, in this case, it has created an .exe file for you in the same directory as the MyModule.vb file. Looking there, you will find MyModule.exe ready to run.

The Visual Basic compiler has a number of options that enable you to dictate what sorts of actions the compiler will take with the compilation process. These flags will be defined soon, but you can specify additional settings by using a forward slash followed by the name of the option and the setting assigned to the option. For instance, if you were going to add a reference to Microsoft.VisualBasic.dll along with the compilation, you would construct your compiler command as follows:

  vbc.exe MyModule.vb /reference:Microsoft.VisualBasic.dll

Compiler Output

This section takes a comprehensive look at all the options available for the Visual Basic compiler. To see the full list, type the following command:

  vbc.exe /?

/nologo

This option causes the compiler to perform its compilation without producing the compiler information set shown in previous examples. This is really only useful if you are invoking the compiler in your application, showing the results coming from the compiler to the end user of your application, and if you have no desire to show this information to the user in the result set.

/utf8output

By default, when you use the Visual Basic command-line compiler, it will not do the compilation using UTF-8 encoding. In fact, the Visual Studio 2005 IDE will not even allow this to occur, but using /utf8output in the command-line compiler overrides this behavior.

/verbose

Adding this command causes the compiler to output a complete list of what it is doing, including the assemblies that are being loaded and the errors that it receives in the compilation process. Use it as follows:

  vbc.exe MyModule.vb /reference:Microsoft.VisualBasic.dll /verbose

This would produce results such as the following (abbreviated to show small examples of the result output, as it is rather lengthy):

 Adding assembly reference 'C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\System. Data.dll'

In addition:

 Adding import 'System' Adding import 'Microsoft.VisualBasic' Adding file 'C:\MyModule.vb' Adding assembly reference 'C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\Microso ft.VisualBasic.dll' Compiling...

Then the compiler starts loading assemblies:

 Loading C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\mscorlib.dll. Loading C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\Microsoft.VisualBasic.dll.

Until it finishes:

 Building C:\MyModule.vb. Building 1.vb. Compilation successful

Optimization

The following sections discuss the optimization features available.

/filealign

Not typically used by most developers, the /filealign setting enables you to specify the alignment of sections, or blocks of contiguous memory, in your output file. It uses the following construction:

  vbc.exe MyModule.vb /filealign:2048

The number assigned is the byte size of the file produced, and valid values include 512, 1024, 2048, 4096, 8192, and 16384.

/optimize

If you go to your project’s property page (found by right-clicking on the project in the Visual Studio Solution Explorer), you will see a page for compilation settings. From this page, you can make all sorts of compilation optimizations. To keep your command-line compiler from ignoring these instructions, set the /optimize flag in your compilation instructions:

  vbc.exe MyModule.vb /optimize

By default, optimizations are turned off.

Output files

The following sections explain the output files.

/doc

By default, the compiler does not produce the XML documentation file upon compilation. This new feature of Visual Basic 2005 enables developers to put structured comments in their code that can then be turned into an XML document for easy viewing (along with a style sheet). Including the /doc option causes the compiler to create this documentation. Structure your command as follows if you want to produce this XML documentation file:

  vbc.exe MyModule.vb /doc

You can also specify the name of the XML file as follows:

  vbc.exe MyModule.vb /doc:MyModuleXmlFile.xml

/netcf

This option can’t be executed from Visual Studio 2005 itself, but you can use this flag from the Visual Basic command-line compiler. Using /netcf causes the compiler to build your application so that the result is targeted for the .NET Compact Framework, not to the full .NET Framework itself. To accomplish this, use the following construct:

  vbc.exe MyModule.vb /netcf

/out

Using the /out option enables you to change the name and extension of the file that was produced from the compilation. By default, it is the name of the file that contains the Main() procedure or the first source code file in a DLL. To modify this yourself instead of using the defaults, you could use something similar to the following:

  vbc.exe MyModule.vb /out:MyReallyCoolModule.exe

/target

This setting enables you to specify what exactly is output from the compilation process. There are four options: an EXE, a DLL, a module, or a Windows program:

/target:exe - Produces an executable console application. This is the default if no /target option is specified.
/target:library - Produces a dynamic link library (also known as a DLL)
/target:module - Produces a module
/target:winexe - Produces a Windows program

You can also use a short form of this by just using /t:exe, /t:library, /t:module, or /t:winexe.

.NET Assemblies

The following sections detail the .NET assemblies for use.

/addmodule

This option isn’t available to Visual Studio 2005, but is possible when using the Visual Basic compiler. Using /addmodule enables you to add a .netmodule file to the resulting output of the compiler. For this, you would use something similar to the following construction:

  vbc.exe MyModule.vb /addmodule:MyOtherModule.netmodule

/delaysign

This compiler option needs to be used in conjunction with the /key or /keycontainer option, which deals with the signing of your assembly. When used with the /delaysign option, the compiler will create a space for the digital signature that is later used to sign the assembly instead of actually signing the assembly at that point. You would use this option in the following manner:

  vbc.exe MyModule.vb /key:myKey1.sn /delaysign

/imports

A commonly used compiler option, the /imports option enables you to import namespaces into the compilation process:

  vbc.exe MyModule.vb /imports:System

Add multiple namespaces by separating them with a comma:

  vbc.exe MyModule.vb /imports:System, System.Data

/keycontainer

This command causes the compiler to create a sharable component and places a public key into the component’s assembly manifest while signing the assembly with a private key. Use this option as follows:

  vbc.exe MyModule.vb /keycontainer:myKey1

If your key container that contains the key has a name that includes a space, then you have to place quotes around the value as shown here:

  vbc.exe MyModule.vb /keycontainer:"my Key1"

/keyfile

Similar to the /keycontainer option, the /key option causes the compiler to place a public key into the component’s assembly manifest while signing the assembly with a private key. Use this as follows:

  vbc.exe MyModule.vb /key:myKey1.sn

If your key has a name that includes a space, then you must place quotes around the value as shown here:

  vbc.exe MyModule.vb /key:"my Key1.sn"

/libpath

When making references to other assemblies while using the /reference compiler option (mentioned next), you will not always have these referenced assemblies in the same location as the object being compiled. You can use the /libpath option to specify the location of the referenced assemblies, as illustrated here:

  vbc.exe MyModule.vb /reference:MyAssembly.dll /libpath:c:\Reuters\bin

If you want the compiler to search for the referenced DLLs in more than one location, then specify the multiple locations using the /libpath option by separating the locations with a comma:

  vbc.exe MyModule.vb /reference:MyAssembly.dll /libpath:c:\Reuters\bin, c:\

This command means that the compiler will look for the MyAssembly.dll in both the C:\Reuters\bin directory and the root directory found at C:\.

/reference

The /reference option enables you to make references to other assemblies in the compilation process. Use it as follows:

  vbc.exe MyModule.vb /reference:MyAssembly.dll

You can also shorten the command option by using just /r:

  vbc.exe MyModule.vb /r:MyAssembly.dll

You can make a reference to multiple assemblies by separating them with a comma:

  vbc.exe MyModule.vb /reference:MyAssembly.dll, MyOtherAssembly.dll

Debugging and Error-Checking

The following sections address the many features available for error-checking and debugging.

/bugreport

This option creates a file that is a full report of the compilation process. The /bugreport option creates this file, which contains your code and version information on the computer’s operating system, as well as the compiler itself. Use this option in the following manner:

  vbc.exe MyModule.vb /bugreport:bugsy.txt

/debug

By default, the Visual Basic compiler will not build objects with attached debugging information included in the generated object. Using the /debug option causes the compiler to place this information in the created output file. The use of this option is shown here:

  vbc.exe MyModule.vb /debug

/nowarn

The /nowarn option actually suppresses the compiler from throwing any warnings. There are a couple of ways to use this option. The first option is to simply use /nowarn without any associated values:

  vbc.exe MyModule.vb /nowarn

Instead of suppressing all the warnings that can come from the compiler, the other option at your disposal is to specify the exact warnings you wish the compiler to suppress, as shown here:

  vbc.exe MyModule.vb /nowarn:42016

In this case, you are telling the compiler not to throw any warnings when it encounters a 42016 error (an implicit conversion warning error). To interject more than one warning code, separate the warning codes with a comma as illustrated here:

  vbc.exe MyModule.vb /nowarn:42016, 42024

You can find a list of available warnings by searching for “Configuring Warnings in Visual Basic” in the MSDN documentation.

/quiet

Like some of the other compiler options, the /quiet option is only available to the command-line compiler and is not available when compiling your applications using Visual Studio. The /quiet option removes some of the error notifications from the error text output that is typically generated. Normally, when the compiler encounters an error that disallows further compilation, the error notification includes the line of code in the file where the error occurred. The line of code that is presented has a squiggly line underneath the exact bit of code where the error occurred. Using the /quiet option causes the compiler to show only the notification line, leaving the code line out of the output. This might be desirable in some situations.

/removeintchecks

By default, the Visual Basic compiler checks all your integer calculations for any possible errors. Possible errors include division by zero or overflow situations. Using the /removeintchecks causes the compiler to not look for these kinds of errors in the code of the files being compiled. You would use this option as follows:

  vbc.exe MyModule.vb /removeintchecks

/warnaserror

In addition to finding and reporting errors, the compiler can also encounter situations that are only considered warnings. Even though warnings are encountered, the compilation process will still continue. Using the /warnaserror option in the compilation process causes the compiler to treat all warnings as errors. Use this option as shown here:

  vbc.exe MyModule.vb /warnaserror

You might not want each warning to cause an error to be thrown, but instead only specific warnings. For these occasions, you can state the warning ID number that you want to look out for, as shown here:

  vbc.exe MyModule.vb /warnaserror:42016

You can also check for multiple warnings by separating the warning ID numbers with commas:

  vbc.exe MyModule.vb /warnaserror:42016, 42024

Help

The following sections address the compiler’s help features.

/?

When you don’t have this book for reference, you can use the Visual Basic compiler for a list of options by using the /? option, as shown here:

  vbc.exe /?

This causes the entire list of options and their definitions to be displayed in the command window.

/help

The /help option is the same as the /? option. Both of these options produce the same result. The /help option produces a list of options that can be used with the compiler.

Language

The following sections detail the language options.

/optionexplicit

Always a good idea, using /optionexplicit causes the compiler to check whether any variables in the code are used before they are even declared (yes, this is possible and very bad practice). When variables are found before they are even declared, the compiler throws an error. By default, the compiler does not check the code using the option explicit option. Using this option is shown in the following example:

  vbc.exe MyModule.vb /optionexplicit

/optionstrict

It’s also a good idea to use the /optionstrict option in the compilation process. Using this option causes the compiler to check whether you are making any improper type conversions in your code. Widening type conversions are allowed, but when you start performing narrowing type conversions, using this option will cause an error to be thrown by the compiler. By default, the compiler does not look for these types of errors with your type conversions. Use this as shown here:

  vbc.exe MyModule.vb /optionstrict

/optioncompare

By default, the Visual Basic compiler compares strings using a binary comparison. If you wish the string comparisons to use a text comparison, then use the following construction:

  vbc.exe MyModule.vb /optioncompare:text

Preprocessor: /define

The /define option enables you to define conditional compiler constants for the compilation process. This is quite similar to using the #Const directive in your code. Here is an example:

  vbc.exe MyModule.vb /define:Version="4.11"

You can also place definitions for multiple constants, as shown here:

  vbc.exe MyModule.vb /define:Version="4.11", DebugMode=False

For multiple constants, just separate the constants with commas.

Resources

The following sections elaborate on the resources in the compiler.

/linkresource

Instead of embedding resources directly in the generated output file (such as with the /resource option), the /linkresource enables you to create the connection between your resulted objects and the resources that they require. You would use this option in the following manner:

  vbc.exe MyModule.vb /linkresource=MyResourceFile.res

You can then specify if the resource file is supposed to be public or private in the assembly manifest. By default, the resource file is referenced as public. Here is an example of its use:

  vbc.exe MyModule.vb /linkresource=MyResourceFile.res, private

You can shorten the /linkresource option to just /linkres.

/resource

The /resource option enables you to reference managed resource objects. The referenced resource is then embedded in the assembly. You would do this in the following manner:

  vbc.exe MyModule.vb /resource=MyResourceFile.res

Like the /linkresource option, you can specify whether the reference to the resource should be made either public or private. This is done in the following way (the default is public):

  vbc.exe MyModule.vb /resource=MyResourceFile.res, private

You can shorten the /resource option to just /res.

/win32icon

Use this option to embed an .ico file (an image that is actually the application’s icon) in the produced file, as shown in the following example:

  vbc.exe MyModule.vb /win32icon:MyIcon.ico

/win32resource

This option enables you to embed a Win32 resource file into the produced file. Use as shown in the following example:

  vbc.exe MyModule.vb /win32resource=MyResourceFile.res

Miscellaneous Features

The rest of this chapter covers some of the more random but very useful features in the compiler. For example, one great feature of the Visual Basic compiler is the use of response files. If you have a compilation that you frequently perform, or one that is rather lengthy, you can instead create an .rsp file (the response file), a simple text file containing all the compilation instructions needed for the compilation process. Here is an example .rsp file:

  # This is a comment /target:exe /out:MyCoolModule.exe /linkresource=MyResourceFile.res MyModule.vb SomeOtherClassFile.vb

If you save this as MyResponseFile.res, then you can use it as shown in the following example:

  vbc.exe @MyResponseFile.rsp

You can also specify multiple response files:

  vbc.exe @MyResponseFile.rsp @MyOtherResponseFile.rsp

/baseaddress

When creating a DLL using the /target:library option, you can assign the base address of the DLL. By default, this is done for you by the compiler, but if you wish to make this assignment yourself you can. To accomplish this, you would use something similar to the following:

  vbc.exe MyClass.vb /target:library /baseaddress:0x11110000

All base addresses are specified as hexadecimal numbers.

/codepage

By default, the compiler expects all the files to be using an ANSI, Unicode, or UTF-8 code page. Using the compiler’s /codepage option, you can specify the code page that the compiler should actually be using. Setting it to one of the defaults is shown here:

  vbc.exe MyClass.vb /codepage:1252

1252 is used for American English and most European languages, although setting it to Japanese Kanji would be just as simple:

  vbc.exe MyClass.vb /codepage:932

/main

Using the /main option, you can point the compiler to the class or module that contains the SubMain procedure. Use as follows:

  vbc.exe MyClass.vb /main:MyClass.vb

/noconfig

By default, the Visual Basic compiler uses the vbc.rsp resource file in the compilation process. Using the /noconfig option tells the compiler to avoid using this file in the compilation process, as shown here:

  vbc.exe MyClass.vb /noconfig

/recurse

The /recurse option tells the compiler to compile all the specified files within a specified directory. Also included will be all child directories of the directory specified. Here is one example of using /recurse:

  vbc.exe /target:library /out:MyComponent.dll /recurse:MyApplication\Classes\*.vb

This command takes all of the .vb files from the MyApplication/Classes directory and creates a DLL called MyComponent.dll.

/rootnamespace

Use this option to specify the namespace to use for compilation:

  vbc.exe MyClass.vb /rootnamespace:Reuters

/sdkpath

This option enables you to specify the location of mscorlib.dll and Microsoft.VisualBasic.dll if they are located someplace other than the default location. This setting is really meant to be used with the /netcf option, described earlier, and is used as follows:

  vbc.exe /sdkpath:"C:\Program Files\Microsoft Visual Studio 8    \CompactFrameworkSDK\v1.0.5000\Windows CE" MyModule.vb

Looking at the vbc.rsp File

As stated earlier, the vbc.rsp file is there for the compiler’s sake. When a compilation is being done, the Visual Basic compiler uses the vbc.rsp file for each compilation (unless you specify the /noconfig option). Inside this .rsp file is a list of compiler commands:

  # This file contains command-line options that the VB # command-line compiler (VBC) will process as part # of every compilation, unless the "/noconfig" option # is specified. # Reference the common Framework libraries /r:Accessibility.dll /r:Microsoft.Vsa.dll /r:System.Configuration.Install.dll /r:System.Data.dll /r:System.Design.dll /r:System.DirectoryServices.dll /r:System.dll /r:System.Drawing.Design.dll /r:System.Drawing.dll /r:System.EnterpriseServices.dll /r:System.Management.dll /r:System.Messaging.dll /r:System.Runtime.Remoting.dll /r:System.Runtime.Serialization.Formatters.Soap.dll /r:System.Security.dll /r:System.ServiceProcess.dll /r:System.Web.dll /r:System.Web.Mobile.dll /r:System.Web.RegularExpressions.dll /r:System.Web.Services.dll /r:System.Windows.Forms.Dll /r:System.XML.dll # Import System and Microsoft.VisualBasic /imports:System /imports:Microsoft.VisualBasic

These commands are the references and imports that are done for each item that you compile using this command-line compiler. You can feel free to play with this file as you choose. If you want to add your own references, then add them to the list and save the file. From then on, every compilation that you make will include the new reference(s). As you get into using the Visual Basic command-line compiler, you will see a lot of power in using .rsp files - even the default Visual Basic one.