Builder

Code in:JavaC#PythonJavaScript

Kurz gesagt: Builder baut ein komplexes Objekt Schritt für Schritt zusammen, mit einem Namen für jedes Feld, prüft es in build() und gibt ein fertiges unveränderliches Objekt zurück.

Problem

Neun Parameter und zwei vertauschte Wörter

Der Shop schickt eine E-Mail, wenn eine Bestellung versandt wird. Die E-Mail hat neun Felder: an wen sie geht, die Adresse für Antworten, den Betreff, den Text, eine Kopie, eine Blindkopie, einen Anhang, ob sie wichtig ist und ob das Öffnen verfolgt wird.

class Email
{
    public string To { get; }
    public string ReplyTo { get; }
    public string Subject { get; }
    public string Body { get; }
    public string Cc { get; }
    public string Bcc { get; }
    public string Attachment { get; }
    public bool HighPriority { get; }
    public bool TrackOpens { get; }

    public Email(string to, string replyTo, string subject, string body, string cc,
                 string bcc, string attachment, bool highPriority, bool trackOpens)
    {
        To = to;
        ReplyTo = replyTo;
        Subject = subject;
        Body = body;
        Cc = cc;
        Bcc = bcc;
        Attachment = attachment;
        HighPriority = highPriority;
        TrackOpens = trackOpens;
    }

    public void Send()
    {
        Console.WriteLine($"An: {To}");
        if (ReplyTo != null)
        {
            Console.WriteLine($"Antwort an: {ReplyTo}");
        }
        Console.WriteLine($"Betreff: {Subject}");
        if (Attachment != null)
        {
            Console.WriteLine($"Anhang: {Attachment}");
        }
        if (HighPriority)
        {
            Console.WriteLine("Hohe Priorität");
        }
    }
}

So wird die Bestätigung für Bestellung 1042 verschickt:

var email = new Email("support@shop.example", "maria@example.com", "Bestellung 1042 wurde versandt",
    "Dein Paket ist unterwegs.", null, null, "invoice-1042.pdf", true, false);
email.Send();

Ausgabe

An: support@shop.example
Antwort an: maria@example.com
Betreff: Bestellung 1042 wurde versandt
Anhang: invoice-1042.pdf
Hohe Priorität

Die E-Mail ging an den Support des Shops, und Maria hat nichts bekommen. Die ersten beiden Argumente sind vertauscht. Beide sind Text, also kann der Compiler es nicht erkennen. Und welches ist am Ende true und welches false? Um das herauszufinden, zählst du Positionen im Konstruktor. Zwei null halten die Plätze von Feldern frei, die diese E-Mail nicht hat.

Jedes neue Feld, sagen wir die Sprache der E-Mail, ändert den Konstruktor und jede Stelle, die ihn aufruft.

Die Idee

Builder: über Namen, in Schritten, mit Prüfung

Das Objekt entsteht nicht durch einen Aufruf mit neun Positionen, sondern in Schritten, jeder mit einem Namen: .To(…), .Subject(…). Die Schritte gehen an ein eigenes Objekt, den Builder. Er sammelt die Werte, und am Ende Build():

• prüft die Pflichtfelder (hier: Empfänger, Betreff und Text) und wirft eine Exception, wenn eins fehlt;
• erzeugt ein unveränderliches Objekt: Danach kann sich die E-Mail nicht mehr ändern.

Das ist das Muster Builder. Die Rollen:

• das Produkt: Email, unveränderlich, mit einem privaten Konstruktor, sodass es keinen anderen Weg gibt, eine zu erzeugen;
• der Builder: Email.Builder, mit einer Methode für jedes Feld. Die Methode gibt den Builder selbst zurück, sodass sich die Aufrufe in einer Kette aneinanderreihen;
• Build(): die einzige Stelle, an der das Produkt geprüft und erzeugt wird.

Sieh es dir an

Die Kette und build()

class Email
{
    public string To { get; private init; }
    public string ReplyTo { get; private init; }
    public string Subject { get; private init; }
    public string Body { get; private init; }
    public string Cc { get; private init; }
    public string Bcc { get; private init; }
    public string Attachment { get; private init; }
    public bool HighPriority { get; private init; }
    public bool TrackOpens { get; private init; }

    private Email()
    {
    }

    public void Send()
    {
        Console.WriteLine($"An: {To}");
        if (ReplyTo != null)
        {
            Console.WriteLine($"Antwort an: {ReplyTo}");
        }
        Console.WriteLine($"Betreff: {Subject}");
        if (Attachment != null)
        {
            Console.WriteLine($"Anhang: {Attachment}");
        }
        if (HighPriority)
        {
            Console.WriteLine("Hohe Priorität");
        }
    }

    public class Builder
    {
        private string to;
        private string replyTo;
        private string subject;
        private string body;
        private string cc;
        private string bcc;
        private string attachment;
        private bool highPriority;
        private bool trackOpens;

        public Builder To(string value) { to = value; return this; }
        public Builder ReplyTo(string value) { replyTo = value; return this; }
        public Builder Subject(string value) { subject = value; return this; }
        public Builder Body(string value) { body = value; return this; }
        public Builder Cc(string value) { cc = value; return this; }
        public Builder Bcc(string value) { bcc = value; return this; }
        public Builder Attachment(string value) { attachment = value; return this; }
        public Builder HighPriority() { highPriority = true; return this; }
        public Builder TrackOpens() { trackOpens = true; return this; }

        public Email Build()
        {
            if (to == null)
            {
                throw new InvalidOperationException("Empfänger fehlt");
            }
            if (subject == null)
            {
                throw new InvalidOperationException("Betreff fehlt");
            }
            if (body == null)
            {
                throw new InvalidOperationException("Text fehlt");
            }
            return new Email
            {
                To = to,
                ReplyTo = replyTo,
                Subject = subject,
                Body = body,
                Cc = cc,
                Bcc = bcc,
                Attachment = attachment,
                HighPriority = highPriority,
                TrackOpens = trackOpens,
            };
        }
    }
}

Ein Builder kostet Code: Jedes Feld wird dreimal geschrieben: in der E-Mail, im Builder und in seiner Methode. Deshalb baut man ihn nicht für jede Klasse.

Email.Builder ist eine geschachtelte Klasse: Sie kann das private init der Properties und den privaten Konstruktor benutzen, sonst niemand.

var email = new Email.Builder()
    .To("maria@example.com")
    .Subject("Bestellung 1042 wurde versandt")
    .Body("Dein Paket ist unterwegs.")
    .Attachment("invoice-1042.pdf")
    .HighPriority()
    .Build();
email.Send();

var draft = new Email.Builder()
    .To("peter@example.com")
    .Body("Dein Paket ist unterwegs.");
try
{
    draft.Build();
}
catch (InvalidOperationException e)
{
    Console.WriteLine(e.Message);
}

Ausgabe

An: maria@example.com
Betreff: Bestellung 1042 wurde versandt
Anhang: invoice-1042.pdf
Hohe Priorität
Betreff fehlt

var email = new Email.Builder()
    .To("maria@example.com")
    .Subject("Bestellung 1042 wurde versandt")
    .Body("Dein Paket ist unterwegs.")
    .Attachment("invoice-1042.pdf")
    .HighPriority()
    .Build();
email.Send();

var draft = new Email.Builder()
    .To("peter@example.com")
    .Body("Dein Paket ist unterwegs.");
try
{
    draft.Build();
}
catch (InvalidOperationException e)
{
    Console.WriteLine(e.Message);
}

Schritt für Schritt, in Worten

1. new Email.Builder(): ein leerer Bauplan mit neun Feldern. Die drei Pflichtfelder (To, Subject, Body) sind markiert.
2. .To(…) füllt ein Feld und gibt denselben Builder zurück, also geht die Kette weiter.
3. Jeder Aufruf hat einen Namen: Ein Wert kann nicht im falschen Feld landen, wie es bei den Positionen im Konstruktor passierte.
4. .Body(…): Alle drei Pflichtfelder sind gefüllt.
5. Optionale Felder schreibst du nur, wenn du sie brauchst. HighPriority() hat kein Argument: kein true mehr an achter Stelle.
6. Build() prüft die Pflichtfelder und stanzt eine Email aus. Ihre Felder sind private init: Das Objekt ändert sich nicht mehr.
7. Die E-Mail geht an Maria, mit der Rechnung, mit hoher Priorität.
8. Ein neuer Builder, ein neuer leerer Bauplan. Hier hat jemand den Betreff vergessen.
9. draft.Build() stößt auf das leere Feld Subject und bricht mit einer Exception ab. Eine E-Mail ohne Betreff entsteht gar nicht erst.
10. Der Fehler sagt, was fehlt. Es wurde nichts gesendet.

Die E-Mail ohne Betreff erreicht nie die Post: Build() stoppt sie schon beim Zusammenbau.

Sieh es dir an

Ohne Builder: was die Sprache bietet

C# hat das, was Builder tut, in der Sprache selbst. init erlaubt, eine Property nur bei der Erzeugung zu setzen, required lässt den Compiler die Pflichtfelder prüfen, und der Objektinitialisierer schreibt jede über ihren Namen:

class Email
{
    public required string To { get; init; }
    public string ReplyTo { get; init; }
    public required string Subject { get; init; }
    public required string Body { get; init; }
    public string Cc { get; init; }
    public string Bcc { get; init; }
    public string Attachment { get; init; }
    public bool HighPriority { get; init; }
    public bool TrackOpens { get; init; }
}

var email = new Email
{
    To = "maria@example.com",
    Subject = "Bestellung 1042 wurde versandt",
    Body = "Dein Paket ist unterwegs.",
    Attachment = "invoice-1042.pdf",
    HighPriority = true,
};
Console.WriteLine($"{email.To} / {email.Subject} / {email.HighPriority}");

Ausgabe

maria@example.com / Bestellung 1042 wurde versandt / True

Ein vergessener Betreff und eine Änderung nach der Erzeugung sind Kompilierfehler:

var email = new Email { To = "maria@example.com", Body = "Dein Paket ist unterwegs." };
email.To = "peter@example.com";

Fehler

error CS9035: Required member 'Email.Subject' must be set in the object initializer or attribute constructor.
error CS8852: Init-only property or indexer 'Email.To' can only be assigned in an object initializer, or on 'this' or 'base' in an instance constructor or an 'init' accessor.

Hat die Klasse einen Konstruktor, ruft C# ihn auch mit benannten Argumenten auf: new Email(to: "…", replyTo: "…"). Dann bleibt auch die Vertauschung von der ersten Karte nicht unbemerkt.

Wann sich ein Builder trotzdem lohnt:

• die E-Mail wird in Schritten an verschiedenen Stellen des Codes zusammengesetzt: Der Anhang kommt nur dazu, wenn es eine Rechnung gibt, die Kopie nur bei Firmen;
• es gibt eine Prüfung über mehrere Felder: Zum Beispiel darf die Blindkopie nicht die Adresse des Empfängers sein;
• es gibt viele Felder, die meisten optional, und der Zusammenbau muss von einer Stelle zur anderen weitergereicht werden, bevor er fertig ist.

Probier es aus

Sag die Ausgabe voraus

Ein Builder, zwei Aufrufe von Build(). Was gibt das Programm aus?

var builder = new Email.Builder()
    .To("maria@example.com")
    .Subject("Bestellung 1042 wurde versandt")
    .Body("Dein Paket ist unterwegs.");
Email first = builder.Build();
builder.HighPriority();
Email second = builder.Build();
Console.WriteLine($"{first.HighPriority} {second.HighPriority}");

Antwort

False True

False False

True True

Prüfen

Probier es aus

Finde den Fehler

Der Shop schickt die E-Mails für versandte Bestellungen in einer Schleife. Nur die erste Bestellung hat eine Rechnung:

var orders = new List<Order>
{
    new("maria@example.com", 1042, "invoice-1042.pdf"),
    new("peter@example.com", 1043, null),
};
var builder = new Email.Builder().ReplyTo("support@shop.example");
foreach (var order in orders)
{
    builder.To(order.Email)
        .Subject($"Bestellung {order.Id} wurde versandt")
        .Body("Dein Paket ist unterwegs.");
    if (order.Invoice != null)
    {
        builder.Attachment(order.Invoice);
    }
    builder.Build().Send();
}

Ausgabe

An: maria@example.com
Antwort an: support@shop.example
Betreff: Bestellung 1042 wurde versandt
Anhang: invoice-1042.pdf
An: peter@example.com
Antwort an: support@shop.example
Betreff: Bestellung 1043 wurde versandt
Anhang: invoice-1042.pdf

Peter hat die Rechnung von Maria bekommen. In welcher Zeile steckt der Fehler?

Wähle die Zeile mit dem Fehler.

1var orders = new List<Order>2{3 new("maria@example.com", 1042, "invoice-1042.pdf"),4 new("peter@example.com", 1043, null),5};6var builder = new Email.Builder().ReplyTo("support@shop.example");7foreach (var order in orders)8{9 builder.To(order.Email)10 .Subject($"Bestellung {order.Id} wurde versandt")11 .Body("Dein Paket ist unterwegs.");12 if (order.Invoice != null)13 {14 builder.Attachment(order.Invoice);15 }16 builder.Build().Send();17}

Prüfen

Die Idee

Wann du ihn nicht brauchst

Builder verdoppelt den Code der Klasse. Er lohnt sich nicht, wenn:

• es zwei oder drei Felder gibt und alle Pflicht sind: Ein einfacher Konstruktor ist klarer;
• required und init mit einem Objektinitialisierer dasselbe ohne zweite Klasse tun;
• das Objekt nichts zu prüfen hat und nicht in Schritten zusammengesetzt wird.

Er lohnt sich, wenn es viele Felder gibt und die meisten optional sind, wenn es eine Prüfung über mehrere gibt oder wenn das Objekt in Schritten an verschiedenen Stellen des Codes zusammengesetzt wird.

Übung

Ein Paket für den Kurier

Löse die Aufgabe in deinem Editor.

Ein Builder für ein Paket. Der Kurier will ein Paket mit Empfänger, Telefon, Adresse und Gewicht (Pflicht) und optional: zerbrechlich und Nachnahme. Schreibe Shipment und einen Builder dafür. Build() prüft, dass die Pflichtfelder gesetzt sind und dass das Gewicht über 0 und bis 30 kg liegt. Erzeuge ein Paket für Maria (2,5 kg, zerbrechlich, Nachnahme 42,90 €), gib es aus und probiere ein Paket mit 45 kg:

Ausgabe

Paket für Maria, 0888 123 456
Adresse: Gartenstraße 5, Hamburg
Gewicht: 2.5 kg, zerbrechlich
Nachnahme: 42.90 €
Das Gewicht muss über 0 und bis 30 kg liegen

Weitere Aufgaben

• Die Schleife reparieren. Repariere das Programm aus „Finde den Fehler“ so, dass jede E-Mail nur ihre eigene Rechnung trägt. Die Antwortadresse muss für alle E-Mails bleiben.
• Eine Kopie mit einer Änderung. Füge eine Methode hinzu, die aus einer fertigen E-Mail einen Builder mit denselben Werten macht (in Java heißt sie oft toBuilder()). Schicke dieselbe E-Mail an einen anderen Empfänger.
• Der Weg der Sprache. Schreibe Shipment wie in der Karte „Ohne Builder“ und vergleiche die beiden Versionen. Welche ist kürzer, und was verlierst du?

Test

Teste dich

1. new Email("support@…", "maria@…", …) kompiliert, und die E-Mail geht woandershin. Warum hat der Compiler nicht geholfen?

Der Compiler prüft keine StringsBeide Parameter sind string: Eine Position hat keinen Namen, also ist die Vertauschung gültiger CodeDer Konstruktor ist falsch geschrieben

2. Was macht build()?

Es prüft die Pflichtfelder und macht ein unveränderliches ObjektEs leert den Builder für die nächste E-MailEs sendet die E-Mail

3. Der Builder wird vor der Schleife erzeugt und für jede E-Mail benutzt. Die zweite E-Mail hat den Anhang der ersten bekommen. Warum?

Es gibt einen Builder, und er merkt sich die Werte vom letzten Zusammenbaubuild() kopiert die alten E-MailsDer Anhang liegt in einem gemeinsamen Feld der Klasse

4. Wann lohnt sich Builder trotzdem?

Wenn die Klasse unveränderlich istImmer, sobald es mehr als zwei Felder gibtWenn das Objekt in Schritten zusammengesetzt wird, an verschiedenen Stellen im Code, oder wenn es eine Prüfung über mehrere Felder gibt

5. Was macht in C# fast dasselbe wie Builder, ohne eine zweite Klasse?

Partielle KlassenEin statischer KonstruktorProperties mit required und init und ein Objektinitialisierer

Prüfen

Lektion von vorn beginnen

Verwandte Lektionen

• Baut auf: Klassen in Klassen · record, switch und Muster · Entwurfsmuster · Factory Method und Simple Factory
• Geht weiter in: Der Shop: welches Muster wohin
• Aufgaben zum Thema: Entwurfsmuster