Table of Contents



Introduction

The Builder design pattern is a creational design pattern and can be used to create complex objects step by step.

Supposing we have an object with many dependencies and need to acquire each one of these dependencies, certain actions must be issued. In such cases, we can use the Builder pattern in order to:

  • Encapsulate, create, and assemble the parts of a complex object in a separate Builder object.
  • Delegate the object creation to a Builder object instead of creating the objects directly.
To summarize, by using the Builder design pattern, we were able to create a complex object and its complex parts.

Another thing that is great about builder design pattern is they promote breaking about methods that may have more than three arguments as a best practice for methods for working with business operations is less than three arguments. Still, some objects might have more than 3 attributes or properties and you usually need some way to initialize them via the constructor. Some attribute might not be mandatory, therefore on some occasions, you can get by with a few overloads adding more parameters as needed.

Description

Before looking at writing a builder pattern here are advantages and disadvantages - as mentioned by [Rohid Ayd]:

Advantages of Builder Design Pattern

  • The parameters to the constructor are reduced and are provided in highly readable method calls.
  • Builder design pattern also helps in minimizing the number of parameters in the constructor and thus there is no need to pass in null for optional parameters to the constructor.
  • The object is always instantiated in a complete state
  • Immutable objects can be built without much complex logic in the object building process.

Moving through this article, all examples are shown in Windows desktop code but can also be used in web solutions also. 

Disadvantages of Builder Design Pattern

  • The number of lines of code increases at least to double in builder pattern, but the effort pays off in terms of design flexibility and much more readable code.
  • Requires creating a separate ConcreteBuilder for each different type of class item.

Examples


Simple fast food

Easy to understand example, ordering a burger at a fast food place. Imagine you have a choice to add or not have cheese, Pepperoni, Lettuce or Tomato.

A conventional method to create the burger is with a new constructor e.g.

public Burger(size, cheese = True, pepperoni = True, tomato = False, lettuce = True)

This is what's called a telescoping constructor anti-pattern, as stated above a method should when humanly possible not have many arguments as it makes things difficult to understand.

A cleaner solution is to use a builder e.g.

Imports BaseLibrary.BaseClasses
  
Namespace Builders
    Public Class BurgerBuilder
        Public ReadOnly Property Size() As Integer
  
        Private mCheese As Boolean
        Public Property Cheese() As Boolean
            Get
                Return mCheese
            End Get
            Private Set(ByVal value As Boolean)
                mCheese = value
            End Set
        End Property
        Private mPepperoni As Boolean
        Public Property Pepperoni() As Boolean
            Get
                Return mPepperoni
            End Get
            Private Set(ByVal value As Boolean)
                mPepperoni = value
            End Set
        End Property
        Private mLettuce As Boolean
        Public Property Lettuce() As Boolean
            Get
                Return mLettuce
            End Get
            Private Set(ByVal value As Boolean)
                mLettuce = value
            End Set
        End Property
        Private mTomato As Boolean
        Public Property Tomato() As Boolean
            Get
                Return mTomato
            End Get
            Private Set(ByVal value As Boolean)
                mTomato = value
            End Set
        End Property
  
        Public Sub New(ByVal size As Integer)
            Me.Size = size
        End Sub
  
        Public Function AddPepperoni() As BurgerBuilder
            Pepperoni = True
            Return Me
        End Function
  
        Public Function AddLettuce() As BurgerBuilder
            Lettuce = True
            Return Me
        End Function
  
        Public Function AddCheese() As BurgerBuilder
            Cheese = True
            Return Me
        End Function
  
        Public Function AddTomato() As BurgerBuilder
            Tomato = True
            Return Me
        End Function
  
        Public Function Build() As Burger
            Return New Burger(Me)
        End Function
    End Class
End Namespace

Then we have the burger class which uses the builder class above.

Namespace BaseClasses
    Public Class Burger
        Public ReadOnly Property Size() As Integer
        Public ReadOnly Property Cheese() As Boolean
        Public ReadOnly Property Pepperoni() As Boolean
        Public ReadOnly Property Lettuce() As Boolean
        Public ReadOnly Property Tomato() As Boolean
  
        Public Sub New(builder As BurgerBuilder)
            Size = builder.Size
            Cheese = builder.Cheese
            Pepperoni = builder.Pepperoni
            Lettuce = builder.Lettuce
            Tomato = builder.Tomato
        End Sub
    End Class
End Namespace

To construct the burger using the builder class. 

Module Module1
  
    Sub Main()
  
        Dim burger = (New BurgerBuilder(14)).
                AddPepperoni().
                AddLettuce().
                AddTomato().
                Build()
    End Sub
  
End Module

This is easier to understand and worth those extra lines of code than using a multi-argument constructor. 

Email example

A good example for working with a builder pattern is sending email messages where there are many parts to properly construct an email message and can become very complex and hard to maintain later on plus in today’s world more time than not a tester have eye’s on the code who may not fully understand code that is shown that follows.

Namespace Classes
    Module SimpleMailOperations
        Public Sub Demo1()
            Dim mail As New MailMessage()
            mail.From = New MailAddress("jane@comcast.net")
            mail.To.Add("bill@comcast.net")
            mail.Subject = "This is an email"
  
            Dim plainMessage As AlternateView =
                    AlternateView.CreateAlternateViewFromString(
                        "Hello, plain text", Nothing, "text/plain")
  
            Dim htmlMessage As AlternateView =
                    AlternateView.CreateAlternateViewFromString(
                        "This is an automated email, please do not respond<br><br>An exception " &
                        "ocurred in <br><span style=""font-weight: bold; padding-left: 20px;" &
                        "padding-right:5px"">Application name</span>MyApp<br>" &
                        "<span style=""font-weight: bold; " &
                        " padding-left: 5px;padding-right:5px"">Application Version</span>" &
                        "1.00<br><span style=""font-weight: bold; padding-left: " &
                        "70px;padding-right:5px"">", Nothing, "text/html")
  
            mail.AlternateViews.Add(plainMessage)
            mail.AlternateViews.Add(htmlMessage)
            Dim smtp As New SmtpClient("smtp.comcast.net")
            smtp.Send(mail)
        End Sub
  
    End Module
End Namespace

Considering that the code sample just presented there are various parts that can be improved upon even without a builder pattern which leads into an example of a builder pattern for sending email messages.

Dim mailer As New MailBuilder()
  
mailer.CreateMail(GmailConfiguration1).
    WithRecipient("karen@comcast.net").
    WithCarbonCopy("mary@gmail.com").
    WithSubject("Test").
    AsRichContent().
    WithHtmlView("<p>Hello <strong>Bob</strong></p>").
    WithPickupFolder().
    WithTimeout(2000).
    SendMessage()

The MailBuilder class provides spoken work methods easy to read and understand rather than, for some difficult to read the code. Each method in the MailBuilder class returns an instance of itself which is known as chaining. 


Going back to hiding complexity, the first part of the chain handles configuring the client which is the transport for sending an email message.

Public Function CreateMail(pConfiguration As String) As MailBuilder
  
    Configuration = New MailConfiguration(pConfiguration)
  
    ConfigurationSection = pConfiguration
  
    Client = New SmtpClient(Configuration.Host, Configuration.Port) With {
        .Credentials = New NetworkCredential(Configuration.UserName, Configuration.Password),
        .EnableSsl = True,
        .Timeout = Configuration.TimeOut
    }
  
    Message = New MailMessage() With
        {
            .From = New MailAddress(Configuration.FromAddress),
            .IsBodyHtml = False
        }
  
    Return Me
  
End Function

Which in turn creates an instance of MailConfiguration responsible for reading setting from an application's configuration file (see example). 
.
Back to the example above, WithRecipient and WithCarbonCopy, both add to MailMessage where both methods below permit multiple entries no different when sending email through an email application such as Microsoft Outlook.

Public Function WithRecipient(pSender As String) As MailBuilder
  
    Message.To.Add(pSender)
  
    Return Me
  
End Function
Public Function WithCarbonCopy(pSender As String) As MailBuilder
  
    Message.CC.Add(pSender)
  
    Return Me
  
End Function

Once all desired parts are set the method SendMessage is called which uses values presented to compose and send an email message. 

To run test see the following code sample. Note in this code sample email message are sent to a folder below the application folder which is done via a post-build event setup in project properties.



Working with databases


Reading

Another use for the builder pattern is any operation typically performed with database operations. In this section reading, data and updating will be explored using the builder pattern. What is not shown is adding and removal of records yet they can also use the builder pattern from first working with the code examples below. 

What the builder pattern will provide, the ability to read all data from joined tables returning all records, an example for filtering by country. Since when there is a chance for editing primary keys are needed but not to be displayed so there are chain methods to indicate to show or hide primary keys. Also is an ORDER BY is needed, which column and ASC DESC order. These can be expanded upon, the entire idea here is to open a developer's mind to possibilities.



To read all customer data, order by the last name in descending order not showing any primary keys and first setting the return data to a BindingSource component which becomes the data source of a DataGridView the following pattern handles this, the same chaining of methods as done with the prior section for sending email messages.

Public Class Form1
  
    Private Sub Form1_Shown(sender As Object, e As EventArgs) Handles Me.Shown
        Dim initialOrderByFieldName = "LastName"
  
        Dim customerReader = New CustomersBuilder
  
        bindingSourceCustomers.DataSource = customerReader.
            Begin().
            OrderBy("LastName").
            DescendingOrder.
            WithoutIdentifiers().
            ReadAllCustomersRecords()
  
        DataGridView1.DataSource = bindingSourceCustomers

Suppose customers want to control sorting and order of a sort, present them with controls such as ComboBox and CheckBox controls with a button to perform the sort.

Sample builder pattern, in this case done in sections rather than in a continuous chain.

Private Sub readCustomersButton_Click(sender As Object, e As EventArgs) 
  
    bindingSourceCustomers.DataSource = Nothing
  
    Dim customerReader = New CustomersBuilder
  
    customerReader.Begin()
    customerReader.OrderBy(columnNamesComboBox.Text)
  
    If decendingOrderCheckBox.Checked Then
        customerReader.DescendingOrder()
    Else
        customerReader.AscendingOrder()
    End If
  
    bindingSourceCustomers.DataSource = customerReader.ReadAllCustomersRecords()
    DataGridView1.DataSource = bindingSourceCustomers
  
    DataGridView1.ExpandAllColumns
    DataGridView1.NormalizeColumnHeaders()
  
End Sub

Another possibility is to only show records meeting a condition, in this case by country using a ComboBox to select from.

Private Sub readCustomersByCountryButton_Click(sender As Object, e As EventArgs) Handles readCustomersByCountryButton.Click 
    bindingSourceCustomers.DataSource = Nothing 
 
    Dim customerReader = New CustomersBuilder 
 
    bindingSourceCustomers.DataSource = customerReader. 
        Begin(). 
        NoOrderBy. 
        WhereCountryIdentifierIs(CType(countriesComboBox.SelectedItem, Country).Identifier). 
        ReadCustomerRecordsByCountry() 
 
 
    DataGridView1.DataSource = bindingSourceCustomers 
 
    DataGridView1.ExpandAllColumns 
    DataGridView1.NormalizeColumnHeaders() 
 
End Sub

Updating

Using the same builder class other operations can be performed. In the following section, the builder class will be used to update a contact phone information where there are several tables which are required to first percent data then to edit data. The importance of knowing back end data structure is that this adds to the complexity and by using a builder fluent pattern although there is a little more code then without chaining via the builder pattern later down the road the code is easier to read and maintain.  



First, the CustomersBuilder is created followed by specifying which contact to update, the phone type (Office, Cell, Home), the status and finally to perform the update operation.

Dim customerReader = New CustomersBuilder
  
Dim result = customerReader.
        Begin().
        UpdateContactPhone(contact.Id).
        SetContactPhoneTypeAs(contact.PhoneType).
        WithPhoneNumber(contact.PhoneNumber).
        PhoneStatusIsActive(contact.Active).
        UpdateContactPhoneDetails()
  
If Not result Then
    MessageBox.Show($"Failed to update contact for {companyName}")
End If

Once UpdateContactPhoneDetails is called the code path moves to a data class which takes one argument of type Contact. The method to update is shown below, a method which can also be called without using the CustomersBuilder class.

Public Function UpdatePhone(contact As Contact, Optional showCommand As Boolean = False) As Boolean
    Dim updateStatement As String =
            "UPDATE dbo.ContactContactDevices " &
            "SET " &
            "PhoneTypeIdenitfier = @PhoneTypeIdenitfier, " &
            "PhoneNumber = @PhoneNumber ," &
            "Active = @Active " &
            "WHERE ContactIdentifier = @ContactIdentifier"
  
    Using cn As New SqlConnection With {.ConnectionString = ConnectionString}
        Using cmd As New SqlCommand With {.Connection = cn, .CommandText = updateStatement}
  
            cmd.Parameters.AddWithValue("@PhoneTypeIdenitfier", contact.PhoneTypeIdenitfier)
            cmd.Parameters.AddWithValue("@PhoneNumber", contact.PhoneNumber)
            cmd.Parameters.AddWithValue("@Active", contact.Active)
            cmd.Parameters.AddWithValue("@ContactIdentifier", contact.Id)
  
            If showCommand Then
                Console.WriteLine(cmd.ActualCommandText())
            End If
  
            Try
                cn.Open()
                cmd.ExecuteNonQuery()
            Catch ex As Exception
                mHasException = True
                mLastException = ex
            End Try
        End Using
    End Using
  
    Return IsSuccessFul
  
End Function

By using a builder pattern coupled with a data class everything is segmented, allows a developer to use or forgo the builder class. If the update method existed prior to the builder class this means the developer did a good job of writing the update method, one argument and using a base class for exception handling. 

Misc/Reports

Another use for a builder is for creating reports that for printing or simply displaying in the user interface. To keep it simple the report will be on products.
The product class

Namespace ProductBuilderClasses
    Public Class Product
        Public Property Name() As String
        Public Property Price() As Double
    End Class
End Namespace

The first step is to define a class for the report. This is the object, we are going to build with the Builder design pattern.

Namespace ProductBuilderClasses
  
    Public Class ProductStockReport
        Public Property HeaderPart() As String
        Public Property BodyPart() As String
        Public Property FooterPart() As String
  
        Public Overrides Function ToString() As String
  
            Return New StringBuilder().
                AppendLine(HeaderPart).
                AppendLine(BodyPart).
                AppendLine(FooterPart).
                ToString()
  
        End Function
    End Class
End Namespace

Now we need a builder interface to organize the building process:

Namespace Interfaces
    Public Interface IProductStockReportBuilder
        Function BuildHeader() As IProductStockReportBuilder
        Function BuildBody() As IProductStockReportBuilder
        Function BuildFooter() As IProductStockReportBuilder
        Function GetReport() As ProductStockReport
    End Interface
End Namespace

Here is the concrete builder class which is going to implement this interface, needs to create all the parts for our stock report object and return that object as well. So, let’s implement our concrete builder class: 

Namespace ProductBuilderClasses
    Public Class ProductStockReportBuilder
        Implements IProductStockReportBuilder
  
        Private productStockReport As ProductStockReport
        Private products As IEnumerable(Of Product)
  
        Public Sub New(products As IEnumerable(Of Product))
            Me.products = products
            productStockReport = New ProductStockReport()
        End Sub
        Private Function BuildHeader() As IProductStockReportBuilder _
            Implements IProductStockReportBuilder.BuildHeader
  
            productStockReport.
                HeaderPart = $"REPORT FOR PRODUCTS ON DATE: {Date.Now}{Environment.NewLine}"
  
            Return Me
        End Function
  
        Private Function BuildBody() As IProductStockReportBuilder _
            Implements IProductStockReportBuilder.BuildBody
  
            productStockReport.BodyPart = String.Join(
                Environment.NewLine,
                products.Select(Function(p) $"Product name: {p.Name,8}, product price: {p.Price}"))
  
            Return Me
  
        End Function
  
        Private Function BuildFooter() As IProductStockReportBuilder _
            Implements IProductStockReportBuilder.BuildFooter
  
            productStockReport.FooterPart = vbLf & "Report provided by the ABC company."
  
            Return Me
  
        End Function
  
        Public Function GetReport() As ProductStockReport _
            Implements IProductStockReportBuilder.GetReport
  
            Dim productStockReport = Me.productStockReport
  
            Clear()
  
            Return productStockReport
  
        End Function
  
        Private Sub Clear()
            productStockReport = New ProductStockReport()
        End Sub
    End Class
End Namespace

Now it's time to build the object.

Namespace ProductBuilderClasses
  
    Public Class ProductBuilderDemo
        Public Sub New()
            Dim products = New List(Of Product) From
                    {
                        New Product With {.Name = "Monitor", .Price = 200.5},
                        New Product With {.Name = "Mouse", .Price = 20.41},
                        New Product With {.Name = "Keyboard", .Price = 30.15}
                    }
  
            Dim builder = New ProductStockReportBuilder(products)
            Dim director = New ProductStockReportDirector(builder)
            director.BuildStockReport()
  
            Dim report = builder.GetReport()
            '
            ' Display to the console
            '
            Console.WriteLine(report)
        End Sub
    End Class
End Namespace

Test, in this case, is done in a console application. 
Module Module1
  
    Sub Main()
        Dim demo As New ProductBuilderDemo
        Console.ReadLine()
    End Sub
  
End Module

Results

Summary 


In this article/code sample the Builder pattern has been shown with real-world examples on how the Builder pattern might be applied coupled with advantages and disadvantages of the pattern.  Having options such as this pattern can make code easier to read and maintain.

See also

SQL-Server- C# Find duplicate record with the identity  
Builder Pattern C#  
Builder Pattern  
Builder Pattern  

Source code


Although there is an attached Visual Studio 2017 solution there is also the same code on a GitHub repository which over time may get updated while not always in this code sample.