System.Xml.XmlWriter, klasa

Artykuł
01/04/2024

Klasa XmlWriter zapisuje dane XML w strumieniu, pliku, czytniku tekstu lub ciągu. Obsługuje on rekomendacje języka W3C Extensible Markup Language (XML) 1.0 (czwarta wersja) i przestrzenie nazw w standardzie XML 1.0 (trzecia wersja).

Elementy członkowskie XmlWriter klasy umożliwiają:

Sprawdź, czy znaki są legalne znaki XML, a nazwy elementów i atrybutów są prawidłowymi nazwami XML.
Sprawdź, czy dokument XML jest poprawnie sformułowany.
Zakoduj bajty binarne jako Base64 lub BinHex i zapisz wynikowy tekst.
Przekazuj wartości przy użyciu typów środowiska uruchomieniowego języka wspólnego zamiast ciągów, aby uniknąć konieczności ręcznego przeprowadzania konwersji wartości.
Zapisz wiele dokumentów w jednym strumieniu wyjściowym.
Zapisuj prawidłowe nazwy, nazwy kwalifikowane i tokeny nazw.

Tworzenie składnika zapisywania XML

Aby utworzyć XmlWriter wystąpienie, użyj XmlWriter.Create metody . Aby określić zestaw funkcji, które chcesz włączyć w składniku zapisywania XML, przekaż element XmlWriterSettings do Create metody . W przeciwnym razie są używane ustawienia domyślne. Create Aby uzyskać szczegółowe informacje, zobacz strony referencyjne.

Określanie formatu danych wyjściowych

Klasa XmlWriterSettings zawiera kilka właściwości, które kontrolują sposób XmlWriter formatowania danych wyjściowych:

Właściwości	opis
Encoding	Określa kodowanie tekstu do użycia. Wartość domyślna to `Encoding.UTF8`.
Indent	Wskazuje, czy należy wciąć elementy. Wartość domyślna to `false` (bez wcięcia).
IndentChars	Określa ciąg znaków, który ma być używany podczas wcięcia. Wartość domyślna to dwie spacje.
NewLineChars	Określa ciąg znaków, który ma być używany dla podziałów wierszy. Wartość domyślna to `\r\n` (powrót karetki, źródło wiersza) dla platform innych niż Unix i `\n` (źródło danych liniowych) dla platform Unix.
NewLineHandling	Określa sposób obsługi znaków nowego wiersza.
NewLineOnAttributes	Wskazuje, czy należy zapisywać atrybuty w nowym wierszu. Indent należy ustawić wartość na `true` wartość w przypadku używania tej właściwości. Wartość domyślna to `false`.
OmitXmlDeclaration	Wskazuje, czy należy napisać deklarację XML. Wartość domyślna to `false`.

Właściwości Indent i IndentChars określają, jak nieistotne białe znaki są sformatowane. Aby na przykład wcięć węzły elementów:

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)

Użyj polecenia , NewLineOnAttributes aby zapisać każdy atrybut w nowym wierszu z jednym dodatkowym poziomem wcięcia:

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)

Zgodność danych

Składnik zapisywania XML używa dwóch właściwości z XmlWriterSettings klasy, aby sprawdzić zgodność danych:

Właściwość instruuje składnik zapisywania CheckCharacters XML, aby sprawdzał znaki i zgłaszał wyjątek, jeśli jakiekolwiek znaki znajdują się poza zakresem prawnym, zgodnie z definicją XmlException W3C.

Właściwość ConformanceLevel konfiguruje składnik zapisywania XML w celu sprawdzenia, czy strumień jest zapisywany, jest zgodny z regułami dla dobrze sformułowanego dokumentu XML 1.0 lub fragmentu dokumentu, zgodnie z definicją w W3C. Trzy poziomy zgodności opisano w poniższej tabeli. Wartość domyślna to Document. Aby uzyskać szczegółowe informacje, zobacz XmlWriterSettings.ConformanceLevel właściwość i System.Xml.ConformanceLevel wyliczenie.

Poziom	opis
Document	Dane wyjściowe XML są zgodne z regułami dla poprawnie sformułowanego dokumentu XML 1.0 i mogą być przetwarzane przez dowolny zgodny procesor.
Fragment	Dane wyjściowe XML są zgodne z regułami fragmentu dokumentu XML 1.0.
Auto	Moduł zapisywania XML określa, który poziom sprawdzania zgodności ma być stosowany (dokument lub fragment) na podstawie danych przychodzących.

Pisanie elementów

Do zapisu węzłów elementów można użyć następujących XmlWriter metod. Przykłady można znaleźć na liście metod.

Używanie	To
WriteElementString	Napisz cały węzeł elementu, w tym wartość ciągu.
WriteStartElement	Aby napisać wartość elementu przy użyciu wielu wywołań metody. Na przykład można wywołać WriteValue metodę zapisu wartości typizowanej, WriteCharEntity aby napisać jednostkę znaku, WriteAttributeString napisać atrybut lub napisać element podrzędny. Jest to bardziej zaawansowana wersja WriteElementString metody. Aby zamknąć element, należy wywołać metodę WriteEndElement or WriteFullEndElement .
WriteNode	Aby skopiować węzeł elementu znajdujący się w bieżącej XmlReader pozycji obiektu lub XPathNavigator . Po wywołaniu obiekt źródłowy kopiuje wszystko, od obiektu źródłowego XmlWriter do wystąpienia.

Zapisywanie atrybutów

Za pomocą poniższych XmlWriter metod można zapisywać atrybuty w węzłach elementów. Metody te mogą również służyć do tworzenia deklaracji przestrzeni nazw w elemecie, zgodnie z opisem w następnej sekcji.

Używanie	To
WriteAttributeString	Aby napisać cały węzeł atrybutu, w tym wartość ciągu.
WriteStartAttribute	Aby zapisać wartość atrybutu przy użyciu wielu wywołań metody. Można na przykład wywołać metodę WriteValue zapisu wpisanej wartości. Jest to bardziej zaawansowana wersja WriteElementString metody. Aby zamknąć element, należy wywołać metodę WriteEndAttribute .
WriteAttributes	Aby skopiować wszystkie atrybuty znalezione w bieżącej XmlReader pozycji obiektu. Atrybuty, które są zapisywane, zależą od typu węzła, na który jest obecnie umieszczony czytnik: - W przypadku węzła atrybutu zapisuje bieżący atrybut, a następnie pozostałe atrybuty do momentu zamknięcia tagu elementu. — W przypadku węzła elementu zapisuje wszystkie atrybuty zawarte przez element. - W przypadku węzła deklaracji XML zapisuje wszystkie atrybuty w deklaracji. — W przypadku wszystkich innych typów węzłów metoda zgłasza wyjątek.

Obsługa przestrzeni nazw

Przestrzenie nazw służą do kwalifikowania nazw elementów i atrybutów w dokumencie XML. Prefiksy przestrzeni nazw kojarzą elementy i atrybuty z przestrzeniami nazw, które są z kolei skojarzone z odwołaniami do identyfikatora URI. Przestrzenie nazw tworzą unikatowość nazw elementów i atrybutów w dokumencie XML.

Obiekt XmlWriter obsługuje stos przestrzeni nazw odpowiadający wszystkim przestrzeniom nazw zdefiniowanym w bieżącym zakresie przestrzeni nazw. Podczas pisania elementów i atrybutów można używać przestrzeni nazw w następujący sposób:

Zadeklaruj WriteAttributeString przestrzenie nazw ręcznie przy użyciu metody . Może to być przydatne, gdy wiesz, jak najlepiej zoptymalizować liczbę deklaracji przestrzeni nazw. Aby zapoznać się z przykładem, zobacz metodę WriteAttributeString(String, String, String, String) .

Zastąpić bieżącą deklarację przestrzeni nazw nową przestrzenią nazw. W poniższym kodzie WriteAttributeString metoda zmienia identyfikator URI przestrzeni nazw dla prefiksu "x" z "123" na "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()

Kod generuje następujący ciąg XML:

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

Określ prefiks przestrzeni nazw podczas pisania atrybutów lub elementów. Wiele metod używanych do pisania elementów i atrybutów umożliwia wykonanie tej czynności. Na przykład WriteStartElement(String, String, String) metoda zapisuje tag startowy i kojarzy go z określoną przestrzenią nazw i prefiksem.

Zapis wpisanych danych

Metoda WriteValue akceptuje obiekt środowiska uruchomieniowego języka wspólnego (CLR), konwertuje wartość wejściową na reprezentację ciągu zgodnie z regułami konwersji typu definicji schematu XML (XSD) i zapisuje ją przy użyciu WriteString metody . Jest to łatwiejsze niż użycie metod w XmlConvert klasie w celu przekonwertowania typowanych danych na wartość ciągu przed ich zapisaniem.

Podczas zapisywania tekstu typowana wartość jest serializowana do tekstu przy użyciu XmlConvert reguł dla tego typu schematu.

Aby uzyskać informacje o domyślnych typach danych XSD odpowiadających typom CLR, zobacz metodę WriteValue .

Element XmlWriter może być również używany do zapisywania w magazynie danych XML. Na przykład XPathNavigator klasa może utworzyć XmlWriter obiekt w celu utworzenia XmlDocument węzłów dla obiektu. Jeśli magazyn danych zawiera dostępne informacje o schemacie, WriteValue metoda zgłasza wyjątek, jeśli spróbujesz przekonwertować na typ, który nie jest dozwolony. Jeśli magazyn danych nie ma dostępnych informacji o schemacie, WriteValue metoda traktuje wszystkie wartości jako xsd:anySimpleType typ.

Zamykanie składnika zapisywania XML

W przypadku używania XmlWriter metod do wyprowadzania kodu XML elementy i atrybuty nie są zapisywane, dopóki nie wywołasz Close metody . Jeśli na przykład używasz XmlWriter polecenia w celu wypełnienia XmlDocument obiektu, nie będzie można wyświetlić zapisanych elementów i atrybutów w dokumencie docelowym do momentu zamknięcia XmlWriter wystąpienia.

Programowanie asynchroniczne

XmlWriter Większość metod ma asynchroniczne odpowiedniki, które mają wartość "Async" na końcu nazw metod. Na przykład asynchroniczny odpowiednik elementu WriteAttributeString to WriteAttributeStringAsync.

W przypadku WriteValue metody, która nie ma asynchronicznego odpowiednika, przekonwertuj wartość zwracaną na ciąg i użyj WriteStringAsync metody .

Zagadnienia dotyczące zabezpieczeń

Podczas pracy z klasą XmlWriter należy wziąć pod uwagę następujące kwestie:

Wyjątki zgłaszane przez program XmlWriter mogą ujawniać informacje o ścieżkach, których nie chcesz przekazywać do aplikacji. Aplikacja musi przechwytywać wyjątki i odpowiednio je przetwarzać.
XmlWriter nie weryfikuje żadnych danych przekazanych do WriteDocType metody lub WriteRaw . Nie należy przekazywać dowolnych danych do tych metod.