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 were not 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 (free of charge), 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. Each version of the framework has a new compiler. In fact, note that while the core of the .NET 3.5 release is still running on the .NET Framework 2.0, the .NET Framework 3.5 release includes new compilers for both the Visual Basic and C# languages. The compiler for the .NET Framework 2.0 is vbc.exe, and it can be found at
C:WINDOWSMicrosoft.NETFrameworkv2.0.50727vbc.exe
The compiler for the .NET Framework 3.5 is also called vbc.exe, and it can be found at
C:WINDOWSMicrosoft.NETFrameworkv3.5vbc.exe
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 for which the compiler should build applications. 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 3.5 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>Even though you are dealing with the .NET Framework 3.5, you can see that the compiler compiles the code to run off of the 2.0 version of the framework.
This .config file, vbc.exe.config, is basically a typical .NET Framework configuration file with the default <configuration> 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 this version, then you build the vbc.exe.config file as follows:
<?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 appears 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 is not checked.
To show how the Visual Basic compiler works in the simplest manner, we can begin by looking at how to compile a single-class file:
Create a module called
MyModule.vb. We will keep the module simple, as this example is meant to show you how to compile the items using thevbc.execompiler:Module Module1 Sub Main() Console.WriteLine("Howdy there") Console.ReadLine() End Sub End ModuleOnce your file is in place, it is time to use the Visual Basic compiler. If you have Visual Studio 2008 on the computer, then you can open the Visual Studio command prompt (found at Start
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.config, andvbc.rspfiles 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:WINDOWSMicrosoft.NETFrameworkv3.5
Now you can work with the compilation normally, and the
vbc.execompiler 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 Compiler version 9.0.20706.1 Copyright (c) Microsoft Corporation. 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
Some of the options listed in this appendix have a plus sign (+) or a minus sign (−) next to them. A plus sign signifies that the option should be enabled, whereas the minus sign signifies that the option should not be enabled. For instance, the following signifies that documentation should be enabled:
vbc.exe MyModule.vb /reference:Microsoft.VisualBasic.dll /doc+
The following, however, signifies that documentation should not be enabled:
vbc.exe MyModule.vb /reference:Microsoft.VisualBasic.dll /doc-
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 /?
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.
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 2008 IDE will not even allow this to occur, but using /utf8output in the command-line compiler overrides this behavior.
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 because the result output is rather lengthy):
Adding assembly reference 'C:WINDOWSMicrosoft.NETFrameworkv2.0.50727System. Data.dll'
In addition:
Adding import 'System' Adding import 'Microsoft.VisualBasic' Adding file 'C:MyModule.vb' Adding assembly reference 'C:WINDOWSMicrosoft.NETFrameworkv2.0.50727Microso ft.VisualBasic.dll' Compiling...
Then the compiler starts loading assemblies:
Loading C:WINDOWSMicrosoft.NETFrameworkv2.0.50727mscorlib.dll. Loading C:WINDOWSMicrosoft.NETFrameworkv2.0.50727Microsoft.VisualBasic.dll.
Until it finishes:
Building 17d14f5c-a337-4978-8281-53493378c1071.vb. Building C:CoolStuffMyModule.vb. Compilation successful
The following sections discuss the optimization features available.
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.
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.
The following sections explain the output files.
By default, the compiler does not produce the XML documentation file upon compilation. This feature of Visual Basic 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
This option cannot be executed from Visual Studio 2008 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 the full .NET Framework itself. To accomplish this, use the following construct:
vbc.exe MyModule.vb /netcf
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
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:
You can also use a short form of this by just using /t:exe, /t:library, /t:module, or /t:winexe.
The following sections detail the .NET assemblies available.
This option is not available to Visual Studio 2008, 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
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, rather than actually signing the assembly at that point. You would use this option in the following manner:
vbc.exe MyModule.vb /key:myKey1.sn /delaysign
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
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 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"
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"
When making references to other assemblies while using the /reference compiler option (described later), 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:Reutersin
If you want the compiler to search for the referenced DLLs in more than one location, then specify multiple locations using the /libpath option by separating the locations with a comma:
vbc.exe MyModule.vb /reference:MyAssembly.dll /libpath:c:Reutersin, c:
This command means that the compiler will look for the MyAssembly.dll in both the C:Reutersin directory and the root directory found at C:.
The /platform option enables you to specify the platform the compilation should be geared for. Possible options include the following:
/platform:x86— Compiles the program for an x86 system/platform:x64— Compiles the program for a 64-bit system/platform:Itanium— Compiles the program for an Itanium system/platform:anycpu— Compiles the program so that it can be run on any CPU system. This is the default setting.
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
The following sections address the many features available for error-checking and debugging.
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
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
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 the compiler can issue, 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.
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 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.
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 option 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
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 continues. 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
The following sections address the compiler's help features.
The following sections detail the language options.
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. Use this option as shown in the following example:
vbc.exe MyModule.vb /optionexplicit
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 option as follows:
vbc.exe MyModule.vb /optionstrict
By default, the Visual Basic compiler compares strings using a binary comparison. If you want the string comparisons to use a text comparison, then use the following construction:
vbc.exe MyModule.vb /optioncompare:text
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.
The following sections elaborate on the resources in the compiler.
Instead of embedding resources directly in the generated output file (such as with the /resource option), the /linkresource option 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 whether 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.
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 as follows (the default is public):
vbc.exe MyModule.vb /resource:MyResourceFile.res,private
You can shorten the /resource option to just /res.
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
The rest of this appendix 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
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.
By default, the compiler expects all 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
Using the /main option, you can point the compiler to the class or module that contains the SubMain procedure. Use it as follows:
vbc.exe MyClass.vb /main:MyClass.vb
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
By default, the Visual Basic compiler uses standard libraries (System.dll) and the vbc.rsp resource file in the compilation process. Using the /nostdlib option tells the compiler to avoid using this file in the compilation process, as shown here:
vbc.exe MyClass.vb /nostdlib
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:MyApplicationClasses*.vb
This command takes all of the .vb files from the MyApplication/Classes directory and creates a DLL called MyComponent.dll.
Use this option to specify the namespace to use for compilation:
vbc.exe MyClass.vb /rootnamespace:Reuters
This option enables you to specify the location of mscorlib.dll and Microsoft.VisualBasic.dll if they are located somewhere 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 FilesMicrosoft Visual Studio 8 CompactFrameworkSDKv1.0.5000Windows CE" MyModule.vb
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 reflect the references and imports that are done for each item that you compile using this command-line compiler. 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 become more familiar with using the Visual Basic command-line compiler, you will see a lot of power in using .rsp files — even the default Visual Basic one.