Element Builders – Create SVG Elements in C# with Fluent Builder API

Aspose.SVG Builder API allows developers to create and edit SVG elements programmatically in C# using fluent builder syntax. Instead of manually constructing SVG XML or manipulating DOM attributes directly, Element Builders provide a cleaner and more maintainable approach to SVG generation.

The Builder API supports common SVG elements such as rectangles, circles, paths, lines, polygons, text, and groups. Using nested builders and chained methods, developers can generate complex SVG graphics with less boilerplate code and improved readability.

This article explains how to create SVG elements in C#, build SVG graphics programmatically, and modify existing SVG documents using Aspose.SVG for .NET. You will learn about the SVGElementBuilder base class, the SVGSVGElementBuilder class, specialized element builders, and how they simplify SVG programming.

What Are SVG Element Builders?

Element Builders are specialized builder classes used to create SVG elements programmatically. Each builder corresponds to a specific SVG element and provides strongly typed methods for configuring SVG attributes and styles.

The Builder API supports:

• SVG shapes;
• text elements;
• groups;
• paths;
• styling;
• transformations;
• reusable SVG structures.

Using fluent syntax simplifies SVG generation and improves code maintainability in .NET applications.

Supported SVG Element Builders

Builder	SVG Element
SVGSVGElementBuilder	<svg>
SVGRectElementBuilder	<rect>
SVGCircleElementBuilder	<circle>
SVGLineElementBuilder	<line>
SVGPathElementBuilder	<path>
SVGTextElementBuilder	<text>
SVGGElementBuilder	<g>
SVGPolygonElementBuilder	<polygon>
SVGPolylineElementBuilder	<polyline>

You will find a complete list of SVG element builders on the API Reference Aspose.Svg.Builder page.

Creating New Elements

Aspose.SVG SVG Builder API employs the Fluent Builder Pattern, a design methodology that aligns perfectly with the need for simplicity, clarity, and versatility in SVG manipulation.

Fluent Builder Pattern

In the SVG Builder API the Fluent Builder Pattern is used to simplify the creation and updating of SVG elements, making the process intuitive and less error-prone. The essence of this pattern is methods that configure an SVG element and return the builder instance for method chaining. This design provides a consistent and coherent way to link methods, which is especially effective at reducing the complexity associated with creating and managing SVG elements.

In this context, lambda expressions are used to improve the clarity and conciseness of the builder’s configuration methods. Lambda expressions allow you to define the attributes and styles of SVG elements in a detailed yet compact way. For example, when adding a circle element, the lambda expression provides an inline readable configuration:

    using (SVGDocument document = new SVGDocument())
    {
        SVGSVGElement svgElement = new SVGSVGElementBuilder()
            .AddCircle(circle => circle
                .Cx(100).Cy(100).R(50)
                .Fill(Color.Red).Stroke(Paint.None)
                .StrokeWidth(2))
            .Build(document);
    }

Here, circle => circle.Cx(100).Cy(100).R(50).Fill(Color.Red).Stroke(Paint.None).StrokeWidth(2) is a succinct way to configure the circle’s properties, such as its center, radius, fill, and stroke. This approach not only simplifies the element configuration but also enhances the code’s readability and maintainability.

Create SVG from Scratch

Here, we will explore a concise and elegant approach to crafting SVGs from scratch using C#.

using Aspose.Svg.Builder;
using System.Drawing;
using System.IO;

    // Create SVG from scratch in C# using Builder API

    // Create an <svg> element with specified width, height and viewBox, and add into it other required elements
    SVGSVGElement svg = new SVGSVGElementBuilder()
        .Width(700).Height(300)
        .ViewBox(0, 0, 700, 300)

        .AddG(g => g
        .AddCircle(circle => circle.Cx(130).Cy(130).R(60).Fill(Paint.None).Stroke(Color.FromArgb(200, 0, 0)).StrokeWidth(70).StrokeDashArray(2, 14))
        .AddText("I can create SVG from scratch!", x: 270, y: 140, fontSize: 30, fill: Color.Teal)
        )
        .Build(document.FirstChild as SVGSVGElement);

    // Save the document
    document.Save(Path.Combine(OutputDir, "svg-from-scratch.svg"));
}

The example utilizes a Fluent Builder Pattern within SVGSVGElementBuilder to construct the SVG elements. This pattern provides an expressive and maintainable way to generate SVG documents compared to the approach described in the Edit SVG File article, which relies more on low-level DOM manipulation and explicit attribute setting. This approach:

• provides a more fluent and readable way to create complex structures, making the code easier to understand and maintain.
• reduces boilerplate code, as seen in the example where setting attributes like cx, cy, r, fill, etc., are achieved with method calls directly on the builder.

Editing SVG

One powerful technique for programmatically editing SVGs is through the use of Element Builders.

Adding New Elements

Editing SVGs using element builders provides a powerful and flexible approach to manipulating vector graphics programmatically. In the following example, we take an existing SVG file, add some elements to it, and save it:

using Aspose.Svg.Builder;
using System.Drawing;
using System.IO;

// Add multiple shapes (circle and polyline) to an existing SVG document using SVG Builder

string documentPath = Path.Combine(DataDir, "circles.svg");

// Initialize an SVG document
using (SVGDocument document = new SVGDocument(documentPath))
{
    // Create a <circle> element with attributes
    SVGCircleElement circle = new SVGCircleElementBuilder()
     .Cx(350).Cy(70).R(50).Fill(Paint.None).Stroke(Color.FromArgb(80, 132, 132)).StrokeWidth(10)
     .Build(document);

    // Append the newly created <circle> element to the root <svg> element
    document.RootElement.AppendChild(circle);

    // Create a <polyline> element with attributes
    SVGPolylineElement polyline = new SVGPolylineElementBuilder()
    .Points(new double[] { 125, 130, 275, 180, 425, 130 }).Stroke(Color.FromArgb(80, 132, 132)).Fill(Paint.None).StrokeWidth(10)
    .Build(document);

    // Append the newly created <polyline> element to the root <svg> element
    document.RootElement.AppendChild(polyline);

    // Save the document
    document.Save(Path.Combine(OutputDir, "circles-edited.svg"));
}

In this example:

• a new <circle> element is created using the SVGCircleElementBuilder. Its cx, cy, r, fill, stroke, and stroke-width attributes are configured with fluent method calls.
• a new <polyline> element is created using the SVGPolylineElementBuilder, with points and stroke settings defined programmatically.
• once each element is configured, the Build(Document document) method constructs the element and returns it for addition to the document.
• the newly created <circle> and <polyline> elements are appended as children to the root <svg> element of the SVG document.

Figure (a) shows a visualization of the original circles.svg file, and figure (b) shows an image of the edited circles-edited.svg file with added circle and polyline elements.

Modifying Existing Elements

In the following C# example, we update an existing SVG document by changing the fill and stroke color of the first SVG <circle> element in the document:

using Aspose.Svg;
using Aspose.Svg.Builder;
using System.Drawing;
using Aspose.Svg.Dom.Svg;
using System.Linq;
using System.IO;

// Modify an existing SVG element in C# using SVG Builder

string documentPath = Path.Combine(DataDir, "circles.svg");

// Initialize an SVG document
using (SVGDocument document = new SVGDocument(documentPath))
{
    // Assume an existing SVG element is part of the document
    SVGCircleElement circle = document.GetElementsByTagName("circle").First() as SVGCircleElement;

    // Modify the first <circle> element using SVGCircleElementBuilder
    new SVGCircleElementBuilder()
        .Stroke(Color.DarkRed).Fill(Color.LightGray)

        // The first <circle> element is now updated with new configurations
        .Build(circle);

    // Save the document
    document.Save(Path.Combine(OutputDir, "circles-modified.svg"));
}

Element builders offer the Build(T element) method for updating existing SVG elements, allowing modifications to their attributes or styles. Figure (a) shows the original circles.svg file, and figure (b) shows an image of the modified circles-modified.svg file with the recolored first circle element.

Example of Using Element Builders

The following code snippet shows how to use element builders to create an SVG document with various SVG shape elements.

using Aspose.Svg;
using Aspose.Svg.Builder;
using System.Drawing;
using Aspose.Svg.Dom.Svg;
using System.IO;

// Create all basic SVG shapes programmatically in C# using SVG Builder

string svgContent = "<svg xmlns=\"http://www.w3.org/2000/svg\"></svg>";
using (SVGDocument document = new SVGDocument(svgContent, "."))
{
    SVGSVGElement svg = new SVGSVGElementBuilder()
        .Width(100, LengthType.Percentage).Height(100, LengthType.Percentage)
        .ViewBox(0, 0, 800, 800)

            .AddG(g => g.FontSize(20).TextAnchor(TextAnchor.End)
                .AddText("<rect>", y: 30)
                .AddText("<circle>", y: 70)
                .AddText("<ellipse>", y: 110)
                .AddText("<line>", y: 150)
                .AddText("<polyline>", x: 300, y: 30)
                .AddText("<polygon>", x: 300, y: 70)
                .AddText("<path>", x: 300, y: 110)
                )

            .AddG(gg => gg.Fill(Color.Teal).StrokeWidth(3)
                .AddRect(r => r.X(35).Y(5).Width(30).Height(30))
                .AddCircle(c => c.Cx(50).Cy(60).R(17))
                .AddEllipse(e => e.Cx(50).Cy(100).Rx(25).Ry(12))
                .AddLine(l => l.X1(30).X2(70).Y1(140).Y2(140).Stroke(Color.Teal))
                )
            .AddG(ggg => ggg.Fill(Paint.None).StrokeWidth(3).Stroke(Color.Teal).Transform(t => t.Translate(300, -160))
                .AddPolygon(points: new double[] { 30, 215, 90, 215, 120, 230, 70, 240, 30, 215 }, fill: Color.Teal)
                .AddPolyline(points: new double[] { 30, 200, 65, 170, 90, 190, 120, 180 })
                .AddPath(d: path => path.M(30, 275).Q(55, 250, 70, 250).T(80, 275).T(120, 260))
                )

        .Build(document.FirstChild as SVGSVGElement);
    document.Save(Path.Combine(OutputDir, "svg-elements.svg"));
}

Element builders provide a fluent and expressive syntax for constructing SVG elements, enhancing code readability and maintainability. In this example, the SVGSVGElementBuilder is employed to construct an SVG element with width, height, and viewBox attributes. The Fluent Builder Pattern is then used to create shapes like rectangles, circles, ellipses, lines, polylines, polygons, and paths, each positioned and styled accordingly within <g> elements.

Why Use Fluent SVG Builders?

DOM Manipulation	Builder API
Manual attribute handling	Strongly typed methods
More verbose code	Fluent chained syntax
Harder to maintain	Easier to read
Repeated XML operations	Reusable builder logic

FAQ

1. Why do developers use Builder APIs instead of direct XML generation?
Builder APIs simplify SVG creation by replacing manual XML construction with typed fluent methods, making SVG code easier to read, maintain, and extend.

2. Is the generated SVG standards-compliant?
Yes. Aspose.SVG generates standards-based SVG markup compatible with modern SVG rendering engines.

3. Can I generate interactive SVG graphics with Element Builders?
Yes. Generated SVG elements can later be styled, animated, or manipulated with CSS and JavaScript in web applications.

4. Can generated SVG graphics be embedded directly into HTML pages?
Yes. SVG documents created with Aspose.SVG can be embedded inline into HTML or used as standalone SVG files in web applications.

Common Mistakes and Fixes

Problem	Possible Cause	Recommended Fix
SVG element is not visible	Missing fill or stroke	Apply Fill() or Stroke() styles
SVG changes are not saved	Document was not saved after modification	Call document.Save() after updates
Elements appear outside the canvas	Incorrect coordinates or viewBox	Verify SVG dimensions and positions
Existing element is not updated	Incorrect element reference	Ensure the target SVG element is retrieved correctly
Shapes appear distorted	Invalid viewBox proportions	Use consistent SVG coordinate systems

Related Resources

• The SVG Builder API article explains how to create and manipulate SVG elements programmatically in C# using the Aspose.SVG Builder API. Learn how fluent builders simplify SVG generation and improve code readability in .NET applications.
• In the Edit SVG File article, you can learn how to edit SVG using Aspose.SVG for .NET library and consider detailed C# examples of how to add elements to an SVG document and edit them.
• Please visit the Path Builder article to learn how to use Path Builder to programmatically create SVG paths, a group of commands for drawing various outlines or shapes by combining SVG lines, SVG arcs, and Bezier curves.
• The Rule Builder article is about the RuleBuilder class, which is a builder class for constructing CSS style rules in an SVG document.
• The Paint Builder article is about PaintBuilder, a builder class for creating paint values for SVG elements. This class is used to specify the value of the stroke or fill attributes for various SVG shapes and elements when filling them with paint, pattern, or gradient.