Literal do elemento XML (Visual Basic)

  • Artigo

Um literal que representa um objeto XElement.

Sintaxe

<name [ attributeList ] />
-or-
<name [ attributeList ] > [ elementContents ] </[ name ]>

Partes

  • <

    Obrigatórios. Abre a marca de elemento inicial.

  • name

    Obrigatórios. Nome do elemento. O formato é um dos seguintes:

    • Texto literal para o nome do elemento, do formulário [ePrefix:]eName, em que:

      Parte Descrição
      ePrefix Opcional. O prefixo do namespace XML para o elemento. Deve ser um namespace XML global definido com uma instrução Imports no arquivo ou no nível do projeto, ou um namespace XML local definido neste elemento ou um elemento pai.
      eName Obrigatórios. Nome do elemento. O formato é um dos seguintes:

      - Texto literal. Confira Nomes de elementos e atributos XML declarados.
      - A expressão inserida da forma <%= eNameExp %>. O tipo de eNameExp deve ser String ou um tipo de dados implicitamente conversível para XName.

    • Expressão inserida da forma <%= nameExp %>. O tipo de nameExp deve ser String ou um tipo de dados implicitamente conversível para XName. Uma expressão inserida não é permitida em uma marca de fechamento de um elemento.

  • attributeList

    Opcional. Lista de atributos declarados no literal.

    attribute [ attribute ... ]

    Cada attribute uma tem uma das seguintes sintaxes:

    • Atribuição de atributo, da forma [aPrefix:]aName=aValue, em que:

      Parte Descrição
      aPrefix Opcional. O prefixo do namespace XML para o atributo. Deve ser um namespace XML global definido por uma instrução Imports, ou um namespace XML local definido neste elemento ou um elemento pai.
      aName Obrigatórios. Nome do atributo. O formato é um dos seguintes:

      - Texto literal. Confira Nomes de elementos e atributos XML declarados.
      - A expressão inserida da forma <%= aNameExp %>. O tipo de aNameExp deve ser String ou um tipo de dados implicitamente conversível para XName.
      aValue Opcional. Valor do atributo. O formato é um dos seguintes:

      - Texto literal, entre aspas.
      - A expressão inserida da forma <%= aValueExp %>. Qualquer tipo é permitido.

    • Expressão inserida da forma <%= aExp %>.

  • />

    Opcional. Indica que o elemento é um elemento vazio, sem conteúdo.

  • >

    Obrigatórios. Termina a marca de elemento inicial ou vazia.

  • elementContents

    Opcional. O conteúdo do elemento.

    content [ content ... ]

    Cada content pode ser uma destas opções:

  • </[name]>

    Opcional. Representa a marca de fechamento do elemento. O parâmetro opcional name não é permitido quando é o resultado de uma expressão inserida.

Valor Retornado

Um objeto XElement.

Comentários

Você pode usar a sintaxe literal do elemento XML para criar objetos XElement em seu código.

Observação

Um literal do XML pode abranger várias linhas sem usar caracteres de continuação de linha. Essa funcionalidade permite que você copie o conteúdo de um documento XML e cole-o diretamente em um programa do Visual Basic.

Expressões inseridas do formulário <%= exp %> permitem adicionar informações dinâmicas a um literal do elemento XML. Para obter mais informações, consulte Expressões Inseridas em XML.

O compilador do Visual Basic converte o literal do elemento XML em chamadas para o construtor XElement e, se for necessário, para o construtor XAttribute.

Namespaces de XML

Prefixos de namespace de XML são úteis quando você precisa criar literais do XML com elementos do mesmo namespace muitas vezes no código. Você pode usar prefixos de namespace de XML globais, que você define usando a instrução Imports, ou prefixos locais, que você define usando a sintaxe do atributo xmlns:xmlPrefix="xmlNamespace". Para obter mais informações, confira Instrução Imports (namespace de XML).

De acordo com as regras de escopo para namespaces de XML, os prefixos locais têm precedência sobre os prefixos globais. No entanto, se um literal do XML definir um namespace de XML, esse namespace não estará disponível para expressões que aparecem em uma expressão inserida. A expressão inserida pode acessar apenas o namespace de XML global.

O compilador do Visual Basic converte cada namespace de XML global usado por um literal do XML em uma definição de namespace local no código gerado. Namespaces de XML globais que não são usados não aparecem no código gerado.

Exemplo 1

O exemplo a seguir mostra como criar um elemento XML simples que tenha dois elementos vazios aninhados.

Dim test1 As XElement = 
<outer>
    <inner1></inner1>
    <inner2/>
</outer>

Console.WriteLine(test1)

O exemplo exibe o texto a seguir. Observe que o literal preserva a estrutura dos elementos vazios.

<outer>
  <inner1></inner1>
  <inner2 />
</outer>

Exemplo 2

O exemplo a seguir mostra como usar expressões inseridas para nomear um elemento e criar atributos.

Dim elementType = "book"
Dim authorName = "My Author"
Dim attributeName1 = "year"
Dim attributeValue1 = 1999
Dim attributeName2 = "title"
Dim attributeValue2 = "My Book"

Dim book As XElement = 
<<%= elementType %>
    isbn="1234"
    author=<%= authorName %>
    <%= attributeName1 %>=<%= attributeValue1 %>
    <%= New XAttribute(attributeName2, attributeValue2) %>
/>

Console.WriteLine(book)

Este código exibe o seguinte texto:

<book isbn="1234" author="My Author" year="1999" title="My Book" />

Exemplo 3

O exemplo a seguir declara ns como um prefixo de namespace de XML. Em seguida, ele cria um literal do XML que usa o prefixo de namespace e exibe a forma final do elemento.

' Place Imports statements at the top of your program.  
Imports <xmlns:ns="http://SomeNamespace">

Class TestClass1

    Shared Sub TestPrefix()
        ' Create test using a global XML namespace prefix. 
        Dim inner2 = <ns:inner2/>

        Dim test = 
        <ns:outer>
            <ns:middle xmlns:ns="http://NewNamespace">
                <ns:inner1/>
                <%= inner2 %>
            </ns:middle>
        </ns:outer>

        ' Display test to see its final form. 
        Console.WriteLine(test)
    End Sub

End Class

Este código exibe o seguinte texto:

<ns:outer xmlns:ns="http://SomeNamespace">
  <ns:middle xmlns:ns="http://NewNamespace">
    <ns:inner1 />
    <inner2 xmlns="http://SomeNamespace" />
  </ns:middle>
</ns:outer>

Observe que o compilador converteu o prefixo do namespace de XML global em uma definição de prefixo para o namespace de XML. O elemento <ns:middle> redefine o prefixo de namespace de XML para o elemento <ns:inner1>. No entanto, o elemento <ns:inner2> usa o namespace definido pela instrução Imports.

Confira também