Classe System.Xml.XmlWriter

Articolo
01/04/2024

La XmlWriter classe scrive dati XML in un flusso, un file, un lettore di testo o una stringa. Supporta le raccomandazioni del W3C Extensible Markup Language (XML) 1.0 (Fourth Edition) e Namespaces in XML 1.0 (Third Edition).

I membri della XmlWriter classe consentono di:

Verificare che i caratteri siano caratteri XML validi e che i nomi di attributi ed elementi siano nomi XML validi.
Verificare che il documento XML sia in formato corretto.
Codificare byte binari come Base64 o BinHex e scrivere il testo risultante.
Passare valori usando tipi Common Language Runtime anziché stringhe, per evitare di dover eseguire manualmente conversioni di valori.
Scrivere più documenti in un unico flusso di output.
Scrivere nomi validi, qualificati e token del nome.

Creare un writer XML

Per creare un'istanza XmlWriter di , usare il XmlWriter.Create metodo . Per specificare il set di funzionalità che si desidera abilitare nel writer XML, passare un oggetto XmlWriterSettings al Create metodo . In caso contrario, vengono usate le impostazioni predefinite. Per informazioni dettagliate, vedere le pagine di Create riferimento.

Specificare il formato di output

La XmlWriterSettings classe include diverse proprietà che controllano la formattazione XmlWriter dell'output:

Proprietà	Descrizione
Encoding	Specifica la codifica di testo da utilizzare. Il valore predefinito è `Encoding.UTF8`.
Indent	Indica se impostare il rientro per gli elementi. Il valore predefinito è `false` (nessun rientro).
IndentChars	Specifica la stringa di caratteri da utilizzare quando si esegue il rientro. Il valore predefinito è due spazi.
NewLineChars	Specifica la stringa di caratteri da utilizzare per le interruzioni di riga. Il valore predefinito è `\r\n` (ritorno a capo, avanzamento riga) per le piattaforme non Unix e `\n` (avanzamento riga) per le piattaforme Unix.
NewLineHandling	Specifica come gestire i caratteri di nuova riga.
NewLineOnAttributes	Indica se scrivere attributi in una nuova riga. Indent deve essere impostato su `true` quando si utilizza questa proprietà. Il valore predefinito è `false`.
OmitXmlDeclaration	Indica se scrivere una dichiarazione XML. Il valore predefinito è `false`.

Le proprietà Indent e IndentChars consentono di controllare il modo in cui vengono formattati gli spazi vuoti non significativi. Ad esempio, per impostare il rientro dei nodi dell'elemento:

XmlWriterSettings settings = new XmlWriterSettings();
settings.Indent = true;
settings.IndentChars = "\t";
XmlWriter writer = XmlWriter.Create("books.xml", settings);

Dim settings As New XmlWriterSettings()
settings.Indent = True
settings.IndentChars = vbTab
Dim writer As XmlWriter = XmlWriter.Create("books.xml", settings)

Usare per NewLineOnAttributes scrivere ogni attributo in una nuova riga con un livello aggiuntivo di rientro:

XmlWriterSettings settings = new XmlWriterSettings();
settings.Indent = true;
settings.NewLineOnAttributes = true;
XmlWriter writer = XmlWriter.Create("books.xml", settings);

Dim settings As New XmlWriterSettings()
settings.Indent = True
settings.NewLineOnAttributes = True
Dim writer As XmlWriter = XmlWriter.Create("books.xml", settings)

Conformità dei dati

Un writer XML usa due proprietà della classe per verificare la XmlWriterSettings conformità dei dati:

La CheckCharacters proprietà indica al writer XML di controllare i caratteri e generare un'eccezione XmlException se i caratteri non rientrano nell'intervallo legale, come definito dal W3C.

La ConformanceLevel proprietà configura il writer XML per verificare che il flusso scritto sia conforme alle regole per un documento o un frammento di documento XML 1.0 ben formato, come definito dal W3C. I tre livelli di conformità sono descritti nella tabella seguente. Il valore predefinito è Document. Per informazioni dettagliate, vedere la XmlWriterSettings.ConformanceLevel proprietà e l'enumerazione System.Xml.ConformanceLevel .

Livello	Descrizione
Document	L'output XML è conforme alle regole per un documento XML 1.0 ben formato e può essere elaborato da qualsiasi processore conforme.
Fragment	L'output XML è conforme alle regole per un frammento di documento XML 1.0 ben formato.
Auto	Il writer XML determina il livello di verifica della conformità da applicare (documento o frammento) in base ai dati in ingresso.

Scrivere elementi

Per scrivere nodi elemento, è possibile usare i metodi seguenti XmlWriter . Per esempi, vedere i metodi elencati.

Utilizzo	Per
WriteElementString	Scrivere un intero nodo di elemento, incluso un valore stringa.
WriteStartElement	Per scrivere un valore di elemento utilizzando più chiamate al metodo. Ad esempio, è possibile chiamare WriteValue per scrivere un valore tipizzato, WriteCharEntity per scrivere un'entità di carattere, WriteAttributeString per scrivere un attributo, oppure è possibile scrivere un elemento figlio. Si tratta di una versione più sofisticata del WriteElementString metodo . Per chiudere l'elemento, chiamare il WriteEndElement metodo o WriteFullEndElement .
WriteNode	Per copiare un nodo elemento trovato nella posizione corrente di un XmlReader oggetto o XPathNavigator . Quando viene chiamato, il metodo copia tutto dall'oggetto di origine all'istanza XmlWriter.

Scrittura attributi

È possibile usare i metodi seguenti XmlWriter per scrivere attributi nei nodi degli elementi. Questi metodi possono essere usati anche per creare dichiarazioni di spazio dei nomi su un elemento, come illustrato nella sezione successiva.

Utilizzo	Per
WriteAttributeString	Per scrivere un intero nodo dell'attributo, incluso un valore stringa.
WriteStartAttribute	Per scrivere il valore dell'attributo usando più chiamate al metodo. Ad esempio, è possibile chiamare WriteValue per scrivere un valore tipizzato. Si tratta di una versione più sofisticata del WriteElementString metodo . Per chiudere l'elemento, chiamare il WriteEndAttribute metodo .
WriteAttributes	Per copiare tutti gli attributi trovati nella posizione corrente di un XmlReader oggetto . Gli attributi scritti dipendono dal tipo di nodo in cui il lettore è attualmente posizionato: - Per un nodo attributo, scrive l'attributo corrente e quindi il resto degli attributi fino al tag di chiusura dell'elemento. - Per un nodo di elemento, scrive tutti gli attributi contenuti nell'elemento . - Per un nodo di dichiarazione XML, scrive tutti gli attributi nella dichiarazione. - Per tutti gli altri tipi di nodo, il metodo genera un'eccezione.

Gestire gli spazi dei nomi

Gli spazi dei nomi consentono di qualificare i nomi di elementi e attributi in un documento XML. I prefissi dello spazio dei nomi associano elementi e attributi agli spazi dei nomi, che a loro volta sono associati ai riferimenti URI. Gli spazi dei nomi assicurano l'univocità dei nomi di elementi e attributi in un documento XML.

XmlWriter gestisce uno stack di spazi dei nomi che corrisponde a tutti gli spazi dei nomi definiti nell'ambito dello spazio dei nomi corrente. Quando si scrivono elementi e attributi, è possibile utilizzare gli spazi dei nomi nei seguenti modi:

Dichiarare gli spazi dei nomi manualmente usando il WriteAttributeString metodo . Può essere utile quando si conosce il metodo migliore per ottimizzare il numero di dichiarazioni dello spazio dei nomi. Per un esempio, vedere il WriteAttributeString(String, String, String, String) metodo .

Sostituire la dichiarazione dello spazio dei nomi corrente con un nuovo spazio dei nomi. Nel codice seguente il WriteAttributeString metodo modifica l'URI dello spazio dei nomi per il "x" prefisso da "123" a "abc".

writer.WriteStartElement("x", "root", "123");
writer.WriteStartElement("item");
writer.WriteAttributeString("xmlns", "x", null, "abc");
writer.WriteEndElement();
writer.WriteEndElement();

writer.WriteStartElement("x", "root", "123")
writer.WriteStartElement("item")
writer.WriteAttributeString("xmlns", "x", Nothing, "abc")
writer.WriteEndElement()
writer.WriteEndElement()

Tale codice genererà la stringa XML seguente:

<x:root xmlns:x="123">
  <item xmlns:x="abc" />
</x:root>

Specificare un prefisso dello spazio dei nomi quando si scrivono attributi o elementi. Molti dei metodi usati per scrivere elementi e attributi consentono di eseguire questa operazione. Ad esempio, il WriteStartElement(String, String, String) metodo scrive un tag iniziale e lo associa a uno spazio dei nomi e un prefisso specificati.

Scrivere dati tipizzato

Il WriteValue metodo accetta un oggetto CLR (Common Language Runtime), converte il valore di input nella relativa rappresentazione di stringa in base alle regole di conversione dei tipi di dati XSD (XML Schema Definition Language) e lo scrive usando il WriteString metodo . Questa operazione è più semplice rispetto all'uso dei metodi nella XmlConvert classe per convertire i dati tipizzato in un valore stringa prima di scriverli.

Quando si scrive in testo, il valore tipizzato viene serializzato in testo usando le XmlConvert regole per tale tipo di schema.

Per i tipi di dati XSD predefiniti che corrispondono ai tipi CLR, vedere il WriteValue metodo .

Può XmlWriter essere utilizzato anche per scrivere in un archivio dati XML. Ad esempio, la classe XPathNavigator può creare un oggetto XmlWriter e quindi creare nodi per un oggetto XmlDocument. Se nell'archivio dati sono disponibili informazioni sullo schema, il WriteValue metodo genera un'eccezione se si tenta di eseguire la conversione in un tipo non consentito. Se all'archivio dati non sono disponibili informazioni sullo schema, il WriteValue metodo considera tutti i valori come xsd:anySimpleType tipo.

Chiudere il writer XML

Quando si usano XmlWriter metodi per l'output XML, gli elementi e gli attributi non vengono scritti fino a quando non si chiama il Close metodo . Ad esempio, se si usa XmlWriter per popolare un XmlDocument oggetto, non sarà possibile visualizzare gli elementi e gli attributi scritti nel documento di destinazione finché non si chiude l'istanza XmlWriter .

Programmazione asincrona

La maggior parte dei XmlWriter metodi ha controparti asincrone che hanno "Async" alla fine dei nomi dei metodi. Ad esempio, l'equivalente asincrono di WriteAttributeString è WriteAttributeStringAsync.

Per il WriteValue metodo , che non ha una controparte asincrona, convertire il valore restituito in una stringa e usare invece il WriteStringAsync metodo .

Considerazioni sulla sicurezza

Quando si lavora con la XmlWriter classe , tenere presente quanto segue:

Le eccezioni generate da XmlWriter possono divulgare le informazioni sul percorso che non si desidera visualizzare nell'app. L'app deve intercettare le eccezioni ed elaborarle in modo appropriato.
XmlWriter non convalida i dati passati al WriteDocType metodo o WriteRaw . Non è consigliabile passare dati arbitrari a questi metodi.

Condividi tramite