Chapter 05 of the lecture Tool Development taught at SAE Institute Hamburg. Introduction to XML serialization in .NET, XML Schema and Schema validation in .NET, as well as other common text file formats.

1. Tool Development
Chapter 05: XML Schema, INI, JSON, YAML
Nick Prühs

2. Assignment Solution #4
DEMO
2 / 58

3. Objectives
• To learn how to use XML serialization via reflection
in .NET
• To understand how to validate documents with
XML Schema
• To get an overview of other common text-based file
formats
3 / 58

4. XML Serialization
• Data in your objects is described using
programming language constructs like classes,
fields, properties, primitive types, arrays
• XML serialization is the process of converting an
object's public properties and fields to XML
• For storage
• For transport
• Deserialization re-creates the object in its original
state
4 / 58

5. XML Serialization in .NET
• Transferring data between objects and XML
requires a mapping from the programming
language constructs to XML schema and vice versa
• XmlSerializer provides the bridge between these
two technologies at runtime
• Classes are annotated with custom attributes to
instruct the XmlSerializer how to map between
the XML schema system and the CLR
5 / 58

6. XML Serialization in .NET
• If a property or field returns a complex object (such
as an array or a class instance), the XmlSerializer
converts it to an element nested within the main
XML document
6 / 58

7. XML Serialization Example
C#
7 / 58
public class OrderItem
{
public string Name { get; set; }
public float PricePerUnit { get; set; }
}

8. XML Serialization Example
C#
8 / 58
public class Address
{
// Serialize as XML attribute.
[XmlAttribute]
public string Name { get; set; }
public string City { get; set; }
}

9. XML Serialization Example
C#
9 / 58
// Serialize as document element with namespace.
[XmlRoot("Order", Namespace = "http://www.npruehs.de/teaching")]
public class Order
{
public Address ShipTo { get; set; }
// Serialize with different name.
[XmlArrayAttribute("OrderedItems")]
public OrderItem[] Items { get; set; }
public float TotalCost { get; set; }
public string OrderDate { get; set; }
public void CalculateTotalCost()
{
// Sum cost of all ordered items.
this.TotalCost = this.Items.Sum(item => item.PricePerUnit);
}
}

10. XML Serialization Example
C#
10 / 58
// Create new order.
OrderItem item = new OrderItem { Name = "Awesome Book", PricePerUnit = 19.99f };
Address address = new Address { City = "Hamburg", Name = "Nick Pruehs" };
Order order = new Order { OrderDate = "20.11.2013", Items = new[] { item }, ShipTo =
address };
order.CalculateTotalCost();
// Serialize order.
XmlSerializer serializer = new XmlSerializer(typeof(Order));
using (TextWriter writer = new StreamWriter("order.xml"))
{
serializer.Serialize(writer, order);
}

11. XML Serialization Example
C#
11 / 58
// Create new order.
OrderItem item = new OrderItem { Name = "Awesome Book", PricePerUnit = 19.99f };
Address address = new Address { City = "Hamburg", Customer = "Nick Pruehs" };
Order order = new Order { OrderDate = "20.11.2013", Items = new[] { item }, ShipTo = address };
order.CalculateTotalCost();
// Create serializer.
XmlSerializer serializer = new XmlSerializer(typeof(Order));
// Set serializer namespace.
XmlSerializerNamespaces ns = new XmlSerializerNamespaces();
ns.Add("np", "http://www.npruehs.de/teaching");
// Serialize order.
using (TextWriter writer = new StreamWriter("order.xml"))
{
serializer.Serialize(writer, order, ns);
}

12. XML Serialization Example
XML
12 / 58
<?xml version="1.0" encoding="utf-8"?>
<np:Order xmlns:np="http://www.npruehs.de/teaching">
<np:ShipTo Customer="Nick Pruehs">
<np:City>Hamburg</np:City>
</np:ShipTo>
<np:OrderedItems>
<np:OrderItem>
<np:Name>Awesome Book</np:Name>
<np:PricePerUnit>19.99</np:PricePerUnit>
</np:OrderItem>
</np:OrderedItems>
<np:TotalCost>19.99</np:TotalCost>
<np:OrderDate>20.11.2013</np:OrderDate>
</np:Order>

13. XML Serialization Example
C#
13 / 58
// Create serializer.
XmlSerializer serializer = new XmlSerializer(typeof(Order));
FileInfo fileInfo = new FileInfo("order.xml");
using (FileStream fileStream = fileInfo.OpenRead())
{
// Read order.
Order order = (Order)serializer.Deserialize(fileStream);
// ...
}

14. XML Serialization in .NET
• Class must have a default constructor to be
serialized by XmlSerializer
• To control the generated XML, you can apply
special attributes to classes and members
• By default, an XML element name is determined by the
class or member name. This default behavior can be
changed if you want to give the element a new name.
• XmlSerializer creates C# source code files (.cs)
and compiles them (.dll) in the directory named by
the TEMP environment variable
14 / 58

15. XML Serialization in .NET
15 / 58
Attribute Description
XmlArrayAttribute Member will be serialized as XML array.
XmlArrayItemAttribute Derived types that can be inserted into an array.
XmlAttributeAttribute Member will be serialized as an XML attribute.
XmlElementAttribute Member will be serialized as an XML element.
XmlIgnoreAttribute Member will be ignored when the containing class is serialized.
XmlRootAttribute
Controls XML serialization of the attribute target as an XML root
element. Use the attribute to further specify the namespace
and element name.
XmlTextAttribute Member will be serialized as XML text.

16. Limitations of
XML Serialization in .NET
• Can be serialized:
• Public read/write properties and fields of public classes
• Classes that implement ICollection or IEnumerable
• Can not be serialized:
• Arrays of ArrayList
• Arrays of List<T>
• Enumerations of type unsigned long (ulong in C#)
containing any member with a value larger than
9,223,372,036,854,775,807
• Objects that are marked as [Obsolete]
16 / 58

17. XML Serialization Caveats
• Does not convert methods, indexers, private fields,
or read-only properties
• Does not include type information
• If you have a Book object that exists in the Library
namespace, there is no guarantee that it is deserialized
into an object of the same type
17 / 58

18. Hint
This approach works great with
other data formats as well!
18 / 78

19. Gotcha!
Serialize enum values as strings!
19 / 58

20. XML Schema
• Description of a type of XML document
• Expressed in terms of constraints on the structure
and content of documents of that type
• Correct vs. valid documents
• Elements and attributes that must/may be included
• Their permitted structure
• How character data is to be interpreted, e.g. as number,
date, URL, Boolean, etc.
20 / 58

21. Simple vs. Complex Types
Simple Types Complex Types
Element Content no yes
Attributes no yes
21 / 58

22. Built-In Simple Types
• String
• Integer
• PositiveInteger
• Int
• Long
• Float
• Boolean
• DateTime
• anyURI
• anyType
• And many, many more…
22 / 58

23. Restricting Simple Types
• New simple types are defined by deriving them
from existing simple types (built-in's and derived)
• simpleType element defines and names the new simple
type
• restriction element indicates the existing (base) type,
and to identify the facets that constrain the range of
values
23 / 58

24. Simple Type Restriction Facets
• length
• minLength/maxLength
• pattern
• enumeration
• minInclusive/maxInclusive
• minExclusive/maxExclusive
24 / 58

25. Restriction Example
XML (XSD)
25 / 58
<xsd:simpleType name="postcode">
<xsd:restriction base="xsd:integer">
<xsd:minInclusive value="10000"/>
<xsd:maxInclusive value="99999"/>
</xsd:restriction>
</xsd:simpleType>

26. Restriction Example
XML (XSD)
26 / 58
<xsd:simpleType name="SKU">
<xsd:restriction base="xsd:string">
<xsd:pattern value="d{3}-[A-Z]{2}"/>
</xsd:restriction>
</xsd:simpleType>

27. Restriction Example
XML (XSD)
27 / 58
<xsd:simpleType name="color">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="red"/>
<xsd:enumeration value="blue"/>
<xsd:enumeration value="green"/>
</xsd:restriction>
</xsd:simpleType>

28. List Types
• Comprised of white-space delimited sequences of
atomic types
• Create new list types by deriving from existing
atomic types
28 / 58

29. List Example
XML (XSD)
29 / 58
<xsd:simpleType name="intList">
<xsd:list itemType="xsd:int"/>
</xsd:simpleType>
XML
<intList>20003 15037 95977 95945</intList>

30. Union Types
• Enable element or attribute value to be one or
more instances of one type drawn from the union
of multiple atomic and list types
30 / 58

31. Union Example
XML (XSD)
31 / 58
<xsd:simpleType name="intOrFloat">
<xsd:union memberTypes="xsd:int xsd:float"/>
</xsd:simpleType>
XML
<intOrFloat>20003</intOrFloat>
<intOrFloat>42.0</intOrFloat>

32. Defining Complex Types
• New complex types are defined using the complexType
element
• Elements are declared using the element element, and
attributes are declared using the attribute element.
32 / 58

33. Defining Complex Types
• sequence indicator specifies that the child elements
must appear in a specific order
• choice specifies that either one child element or
another can occur
• all specifies that the child elements can appear in
any order, and that each child element must occur
only once
33 / 58

34. Complex Type Example
XML (XSD)
34 / 58
<xsd:complexType name="AddressType">
<xsd:sequence>
<xsd:element name="City" type="xsd:string"/>
</xsd:sequence>
<xsd:attribute name="Customer" type="xsd:string" />
</xsd:complexType>
<xsd:complexType name="ItemType">
<xsd:sequence>
<xsd:element name="Name" type ="xsd:string" />
<xsd:element name="PricePerUnit" type ="xsd:float" />
</xsd:sequence>
</xsd:complexType>

35. Complex Type Example
XML (XSD)
35 / 58
<xsd:element name="Order" type="OrderType"/>
<xsd:complexType name="OrderType">
<xsd:sequence>
<xsd:element name="ShipTo" type="AddressType"/>
<xsd:element name="OrderedItems" type="ItemsType"/>
<xsd:element name="TotalCost" type ="xsd:float" />
<xsd:element name="OrderDate" type ="xsd:string" />
</xsd:sequence>
</xsd:complexType>

36. Occurrence Constraints
• Elements: minOccurs/maxOccurs
• May be a positive integer such as 41, or the term
unbounded to indicate there is no maximum number of
occurrences.
• Default value is 1
• Attributes: use
• Indicates whether the attribute is required, optional, or
even prohibited
36 / 58

37. Complex Type Example
XML (XSD)
37 / 58
<xsd:complexType name="ItemsType">
<xsd:sequence>
<xsd:element name="OrderItem" type="ItemType" minOccurs="0" maxOccurs="unbounded" />
</xsd:sequence>
</xsd:complexType>

38. Default Values
• Default values of both attributes and elements are
declared using the default attribute
• Fixed is used in both attribute and element
declarations to ensure that the attributes and
elements are set to particular values.
38 / 58

39. Element Groups
• Group indicators are used to define related sets of
elements
• After you have defined a group, you can reference
it in another definition
39 / 58

40. Element Group Example
XML (XSD)
40 / 58
<xsd:group name="person">
<xsd:sequence>
<xsd:element name="firstname" type="xsd:string"/>
<xsd:element name="lastname" type="xsd:string"/>
<xsd:element name="birthday" type="xsd:date"/>
</xsd:sequence>
</xsd:group>
<xsd:complexType name="personinfo">
<xsd:sequence>
<xsd:group ref="person"/>
<xsd:element name="country" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>

41. Annotations
• XML Schema provides three elements for annotating
schemas for the benefit of both human readers and
applications
• XML representation for an annotation schema component is
an annotation element
• documentation element is the recommended location for
human readable material
• appinfo element can be used to provide information for
tools, stylesheets and other applications
• xml:lang attribute is used to indicate the language of the
information
41 / 58

42. Annotation Example
XML (XSD)
42 / 58
<xsd:annotation>
<xsd:documentation xml:lang="en">
Order schema for npruehs.de
</xsd:documentation>
</xsd:annotation>

43. A little criminal energy…
• Sending a continuous stream of XML data to a Web
server (= denial of service attack)
• Server continues to process the data until the
computer runs low on resources
43 / 58

44. XSD Validation in .NET
C#
44 / 58
// Validate schema.
XmlReaderSettings readerSettings = new XmlReaderSettings();
readerSettings.Schemas.Add("http://www.npruehs.de/teaching", "order.xsd");
readerSettings.ValidationType = ValidationType.Schema;
using (XmlReader reader = XmlReader.Create("order.xml", readerSettings))
{
while (reader.Read()) { }
}

45. INI File Format
• Text file format
• Structured in sections and properties
• Used since MS DOS and 16-bit Windows platforms
• Alternative formats like XML, JSON and YAML can nest
arbitrarily but are more heavyweight
• Human-readable
• Simple to parse
45 / 58

46. INI File Example
INI
46 / 58
[HostileWorlds.HWSM_Commander]
Scale=1.0
StructureMax=125
ShieldsMax=125
Armor=0
MovementSpeed=160
AttackDamage=4
SplashDamageRadius=0
Cooldown=1.5
Range=500

47. INI Property
• Name and value
• Delimited by =
47 / 58

48. INI Section
• Keys can (but don’t need to) be grouped into
sections
• Section names appear in own lines in square
brackets
• Keys after the section declaration are associated
with that section.
• No explicit end of section
• Sections end at the next section declaration, or the end
of the file
• Sections may not be nested
48 / 58

49. INI Comment
• Indicated by semicolon at the beginning of the line
• Ignored by processors
49 / 58

50. Duplicate Properties
in INI Files
• Handling depends on the implementation
• May cause an abort
• May be ignored
• May override first occurrence
• May be used to implement multi-valued properties
50 / 58

51. JSON File Format
• Java Script Object Notation
• Human-readable
• Name-value pairs
51 / 58

52. JSON Example
JSON
52 / 58
{
"Image": {
"Width": 800,
"Height": 600,
"Title": "View from 15th Floor",
"Thumbnail": {
"Url": "http://www.example.com/image/481989943",
"Height": 125,
"Width": "100"
},
"IDs": [116, 943, 234, 38793]
}
}

53. JSON Primitive Types
• String (Unicode, quotation marks)
• Number (integer, floating point)
• Boolean
• Null
53 / 58

54. JSON Structured Types
• Array
• Ordered
• Square brackets
• Elements are separated by commas
• Object
• Unordered
• Curly brackets
• Name/Value pairs
• Name is a string
• Value is a string, number, boolean, null, object, or array
• Single colon separates the name from the value
54 / 58

55. YAML File Format
• YAML Ain’t Markup Language
• Human-readable
• Unicode
• Superset of JSON
• Every JSON file is also a valid YAML file.
55 / 58

56. YAML Example
YAML
56 / 58
---
Time: 2001-11-23 15:01:42 -5
User: ed
Warning:
This is an error message
for the log file
---
Time: 2001-11-23 15:02:31 -5
User: ed
Warning:
A slightly different error
message.
---
Date: 2001-11-23 15:03:17 -5
User: ed
Fatal:
Unknown variable "bar"
Stack:
- file: TopClass.py
line: 23
- file: MoreClass.py
line: 58

57. YAML Document Structure
• Uses indentation for scope
• Begins each entry on its own line
• Sequences indicate entries with dashes
• Mappings mark key-value pairs with colons
• Structures use three dashes for separation
• Comments begin with a hash
57 / 58

58. Comparison of File Formats
XML INI JSON YAML Binary
Human-
readable
yes yes yes yes no
Data-to-
markup
ratio
low high high high high
Arbitrary
Nesting
yes no yes yes yes
58 / 58

59. Assignment #5
1. XML Serialization
Replace your implementation of the Save As and
Open commands, using XMLSerializer for reading and
writing your maps!
59 / 58

60. Assignment #5
2. Analysis of XML Serialization
What are the advantages of your new
implementation, what are the drawbacks?
60 / 58

61. Assignment #5
3. XML Schema
1. Define an XML Schema for your map files.
1. Specify the root element of the XML map document in the
schema.
2. Define all required complex types in the schema (e.g. Map,
MapTile, Vector2I).
2. Validate your map files against that schema before
loading the map.
61 / 58

62. References
• MSDN. Introducing XML Serialization. http://msdn.microsoft.com/en-
us/library/182eeyhh%28v=vs.110%29.aspx, May 2016.
• MSDN. Attributes That Control XML Serialization.
http://msdn.microsoft.com/en-
us/library/83y7df3e%28v=vs.110%29.aspx, May 2016.
• Fallside, Walmsley. XML Schema Part 0: Primer Second Edition.
http://www.w3.org/TR/xmlschema-0/, October 28, 2004.
• w3schools.com. XSD Indicators.
http://www.w3schools.com/xml/schema_complex_indicators.asp, May
2016.
• Wikipedia.org. INI File. http://en.wikipedia.org/wiki/INI_file, October
16, 2013.
• Crockford. The application/json Media Type for JavaScript Object
Notation (JSON). IETF, July 2006.
• Ben-Kiki, Evans. YAML Ain’t Markup Language (YAML™) Version 1.2. 3rd
Edition. http://www.yaml.org/spec/1.2/spec.html, 2009.
62 / 58

63. Thank you!
http://www.npruehs.de
https://github.com/npruehs
@npruehs
dev@npruehs.de

64. 5 Minute Review Session
• What is XML serialization?
• How is XML serialization controlled in .NET?
• What is XML Schema?
• What is the difference between simple and complex
types in XML Schema?
• How do you define new simple types?
• How do you define new complex types?
• What is the major drawback of the INI file format?
• What is JSON?
• What is the main motivation behind YAML?
64 / 58