Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 36 ยท Getting Started

Project Structure and Compilation

Understand a Visual Basic .NET solution: the .vbproj file, root namespace, Imports, assemblies, Option statements, build configurations and what the compiler really does.

A first program fits in one file. Real applications have dozens of files, several projects and many references. Knowing how VB.NET organizes code makes error messages less mysterious and helps you find things in an unfamiliar solution. This lesson covers solutions, projects, namespaces, Imports, assemblies and the build process. The files shown are real project files, displayed read-only, with a runnable C# stand-in at the end that demonstrates namespaces.

Solutions, projects and assemblies

  • A solution (.sln) groups one or more projects so you can open and build them together.
  • A project (.vbproj) lists the source files, references and settings that compile into one assembly.
  • An assembly is the compiled output: a .dll (library) or .exe (program) containing IL, metadata and resources. It is the unit of deployment and versioning in .NET.
flowchart TB
    S["Shop.sln"] --> P1["Shop.App<br/>(exe)"]
    S --> P2["Shop.Core<br/>(dll)"]
    S --> P3["Shop.Tests<br/>(dll)"]
    P1 -- references --> P2
    P3 -- references --> P2

Figure: a typical solution. The app and the tests both reference the core library.

The project file

Modern SDK-style .vbproj files are short because the SDK includes every .vb file in the folder automatically:

XML
<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <RootNamespace>HelloVb</RootNamespace>
    <TargetFramework>net8.0</TargetFramework>
    <OptionStrict>On</OptionStrict>
    <Nullable>enable</Nullable>
  </PropertyGroup>

</Project>

The important settings:

Element Meaning
OutputType Exe (console), WinExe (no console window, used by Windows Forms) or Library (a .dll)
TargetFramework Which .NET version the code compiles for, such as net8.0 or net48 (the old .NET Framework)
RootNamespace A prefix added to every namespace declared in the project
OptionStrict, OptionInfer, OptionExplicit Compiler checks (see the next section)

Packages come from NuGet. Add one with dotnet add package Newtonsoft.Json, which adds a <PackageReference> line to the project file. Another project is referenced with <ProjectReference Include="..\Shop.Core\Shop.Core.vbproj" />.

Namespaces and Imports

A namespace groups related types and prevents name clashes. System.IO.File and MyApp.File can coexist because their namespaces differ.

VB
Namespace Shop.Models
    Public Class Product
        Public Property Name As String
    End Class
End Namespace

Remember the root namespace: if the project's RootNamespace is Shop, then the declaration above actually creates Shop.Shop.Models. This surprises many people who move from C#. The usual practice is to declare only the sub-namespace in VB (Namespace Models) and let the root add the prefix.

To use a type from another namespace you either write its full name or add an Imports line at the top of the file:

VB
Imports System.Collections.Generic
Imports System.IO
Imports Shop.Models

Module Program
    Sub Main()
        Dim items As New List(Of Product)()
        Console.WriteLine(File.Exists("data.txt"))
    End Sub
End Module

You can also alias a name: Imports Json = System.Text.Json. Project-wide imports live in the project's Imports settings, and the SDK adds a set of implicit ones (for example System, System.Collections.Generic, System.Linq, System.IO) so simple programs need no Imports at all.

The Option statements

Three file-level or project-level switches change how strict the compiler is. They go at the very top of a file, before Imports:

VB
Option Explicit On
Option Strict On
Option Infer On
  • Option Explicit On (default): every variable must be declared with Dim. Off allows typos to create new variables silently.
  • Option Strict On: forbids implicit narrowing conversions and late binding. Turn it on in every project. Option Strict and Conversions shows what it catches.
  • Option Infer On (default): the compiler infers a local variable's type from its value, so Dim n = 5 is an Integer.
  • Option Compare Binary or Text: decides whether string comparison is case-sensitive.

What the build does

flowchart LR
    A["*.vb files"] --> C["vbc compiler"]
    B["References<br/>(NuGet, projects)"] --> C
    C --> D["obj/ intermediate files"]
    C --> E["bin/Debug/net8.0/<br/>App.dll + App.exe + deps.json"]

Figure: inputs and outputs of a build.

  1. NuGet packages are restored into a local cache.
  2. The compiler parses all source files together (file order does not matter) and reports errors and warnings.
  3. IL and metadata are written to obj/, then the final assembly lands in bin/<Configuration>/<TargetFramework>/.

A configuration is a named set of build options. Debug keeps symbols and turns optimization off so the debugger works well. Release optimizes and is what you ship: dotnet build -c Release.

Warnings are worth attention. You can raise important ones to errors with <TreatWarningsAsErrors>true</TreatWarningsAsErrors>.

A conventional layout

TEXT
Shop/
  Shop.sln
  Shop.App/
    Shop.App.vbproj
    Program.vb
    Forms/MainForm.vb
  Shop.Core/
    Shop.Core.vbproj
    Models/Product.vb
    Services/PriceCalculator.vb
  Shop.Tests/
    Shop.Tests.vbproj

Keep one public type per file and name the file after the type. Group by feature or layer, not by kind of keyword.

Namespaces in action (C# stand-in)

The site cannot compile .vbproj files, but the namespace idea is identical in C#. This runnable stand-in declares two types with the same name in different namespaces and shows how an alias disambiguates them, like Imports Alias = ... in VB.

C# Stand-in (C#): same name, different namespaces

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Two classes called Shape coexist because the full names (Geometry.TwoD.Shape, Geometry.ThreeD.Shape) differ. In VB.NET you would write Imports Shapes2D = Geometry.TwoD.

Assemblies at runtime (C# stand-in)

Every type belongs to an assembly, and you can ask the runtime about it. The same reflection API is available from VB.NET (GetType(String).Assembly.GetName()).

C# Stand-in (C#): which assembly is a type in?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is an assembly?

    A project compiles into one assembly, the deployable unit of .NET.
  2. 2. A project has RootNamespace Shop and a file declares Namespace Shop.Models. What is the full namespace?

    VB prefixes declared namespaces with the root namespace, which is why you usually declare only the sub-namespace.
  3. 3. Which setting forbids implicit narrowing conversions and late binding?

    Option Strict On makes the compiler reject risky implicit conversions. Turn it on in every project.
  4. 4. Which OutputType gives a Windows Forms app without a console window?

    WinExe builds a GUI executable. Exe opens a console window, Library builds a dll.

Summary

  • A solution groups projects; a project compiles into one assembly (.dll or .exe).
  • The .vbproj file sets output type, target framework, root namespace and compiler options; NuGet adds packages.
  • Namespaces prevent clashes; Imports brings names into scope, and the root namespace prefixes your own.
  • Use Option Strict On (and keep Option Explicit On) everywhere.
  • Builds run restore, compile and write to bin/<Configuration>/<Framework>; ship the Release build.

Next: VB.NET and C# Side by Side