XML Literals Overview (Visual Basic)

An XML literal allows you to incorporate XML directly into your Visual Basic code. The XML literal syntax represents LINQ to XML objects, and it is the similar to the XML 1.0 syntax. This makes it easier to create XML elements and documents programmatically because your code has the same structure as the final XML.

Visual Basic compiles XML literals into LINQ to XML objects. LINQ to XML provides a simple object model for creating and manipulating XML, and this model integrates well with Language-Integrated Query (LINQ). For more information, see XElement.

You can embed a Visual Basic expression in an XML literal. At run time, your application creates a LINQ to XML object for each literal, incorporating the values of the embedded expressions. This lets you specify dynamic content inside an XML literal. For more information, see Embedded Expressions in XML (Visual Basic).

For more information about the differences between the XML literal syntax and the XML 1.0 syntax, see XML Literals and the XML 1.0 Specification (Visual Basic).

Simple Literals

You can create a LINQ to XML object in your Visual Basic code by typing or pasting in valid XML. An XML element literal returns an XElement object. For more information, see XML Element Literal (Visual Basic) and XML Literals and the XML 1.0 Specification (Visual Basic). The following example creates an XML element that has several child elements.

Dim contact1 As XElement = 
    <contact>
      <name>Patrick Hines</name>
      <phone type="home">206-555-0144</phone>
      <phone type="work">425-555-0145</phone>
    </contact>

You can create an XML document by starting an XML literal with <?xml version="1.0"?>, as shown in the following example. An XML document literal returns an XDocument object. For more information, see XML Document Literal (Visual Basic).

Dim contactDoc As XDocument = 
    <?xml version="1.0"?>
    <contact>
      <name>Patrick Hines</name>
      <phone type="home">206-555-0144</phone>
      <phone type="work">425-555-0145</phone>
    </contact>

Line Continuation

An XML literal can span multiple lines without using line continuation characters (the space-underscore-enter sequence). This makes it easier to compare XML literals in code with XML documents.

The compiler treats line continuation characters as part of an XML literal. Therefore, you should use the space-underscore-enter sequence only when it belongs in the LINQ to XML object.

However, you do need line continuation characters if you have a multiline expression in an embedded expression. For more information, see Embedded Expressions in XML (Visual Basic).

Embedding Queries in XML Literals

You can use a query in an embedded expression. When you do this, the elements returned by the query are added to the XML element. This lets you add dynamic content, such as the result of a user's query, to an XML literal.

For example, the following code uses an embedded query to create XML elements from the members of the phoneNumbers2 array and then add those elements as children of contact2.

Public Class XmlSamples

  Public Sub Main()
    ' Initialize the objects.  

    Dim phoneNumbers2 As Phone() = { 
        New Phone("home", "206-555-0144"), 
        New Phone("work", "425-555-0145")}

    ' Convert the data contained in phoneNumbers2 to XML.  

    Dim contact2 = 
        <contact>
          <name>Patrick Hines</name>
          <%= From p In phoneNumbers2 
            Select <phone type=<%= p.Type %>><%= p.Number %></phone> 
          %>
        </contact>

    Console.WriteLine(contact2)
  End Sub 

End Class 

Class Phone
  Public Type As String 
  Public Number As String 
  Public Sub New(ByVal t As String, ByVal n As String)
    Type = t
    Number = n
  End Sub 
End Class

How the Compiler Creates Objects from XML Literals

The Visual Basic compiler translates XML literals into calls to the equivalent LINQ to XML constructors to build up the LINQ to XML object. For example, the Visual Basic compiler will translate the following code example into a call to the XProcessingInstruction constructor for the XML version instruction, calls to the XElement constructor for the <contact>, <name>, and <phone> elements, and calls to the XAttribute constructor for the type attribute. Specifically, given the attributes in the following sample, the Visual Basic compiler will call the #ctor(XName, Object) constructor twice. The first will pass the value type for the name parameter and the value home for the value parameter. The second will also pass the value type for the name parameter, but the value work for the value parameter.

Dim contactDoc As XDocument = 
    <?xml version="1.0"?>
    <contact>
      <name>Patrick Hines</name>
      <phone type="home">206-555-0144</phone>
      <phone type="work">425-555-0145</phone>
    </contact>

See Also

Reference

XML Document Literal (Visual Basic)

XML Element Literal (Visual Basic)

XElement

Concepts

Embedded Expressions in XML (Visual Basic)

Other Resources

Creating XML in Visual Basic

XML Literals (Visual Basic)