Embed Size (px)
DESCRIPTION
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.
Citation preview
Tool DevelopmentChapter 05: XML Schema, INI, JSON, YAML
Nick Prühs
5 Minute Review Session
• What are the main benefits of using XML?
• What are the three main XML processing steps?
• Which XML node types do you know?
• How do you properly create XmlWriter instances?
• How do you read types XML content?
• What is the difference between DOM and SAX parsing?
• What are the main parts of an XPath location step?
• What is XSLT and how does it work?
2 / 58
Assignment Solution #4
DEMO
3 / 58
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 fileformats
4 / 58
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
5 / 58
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
6 / 58
XML Serialization in .NET
• If a property or field returns a complex object (such as an array or a class instance), the XmlSerializerconverts it to an element nested within the main XML document
7 / 58
XML Serialization Example
C#
8 / 58
public class OrderItem
{
public string Name { get; set; }
public float PricePerUnit { get; set; }
}
XML Serialization Example
C#
9 / 58
public class Address
{
// Serialize as XML attribute.
[XmlAttribute]
public string Name { get; set; }
public string City { get; set; }
}
XML Serialization Example
C#
10 / 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);
}}
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", 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);
}
XML Serialization Example
C#
12 / 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);
}
XML Serialization Example
XML
13 / 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>
XML Serialization Example
C#
14 / 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);
// ...
}
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
15 / 58
XML Serialization in .NET
16 / 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.
Limitations ofXML 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]
17 / 58
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 deserializedinto an object of the same type
18 / 58
Hint
This approach works great with other data formats as well!
19 / 78
Gotcha!
Serialize enum values as strings!
20 / 58
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.
21 / 58
Simple vs. Complex Types
Simple Types Complex Types
Element Content no yes
Attributes no yes
22 / 58
Built-In Simple Types
• String
• Integer
• PositiveInteger
• Int
• Long
• Float
• Boolean
• DateTime
• anyURI
• anyType
• And many, many more…
23 / 58
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
24 / 58
Simple Type Restriction Facets
• length
• minLength/maxLength
• pattern
• enumeration
• minInclusive/maxInclusive
• minExclusive/maxExclusive
25 / 58
Restriction Example
XML (XSD)
26 / 58
<xsd:simpleType name="postcode">
<xsd:restriction base="xsd:integer">
<xsd:minInclusive value="10000"/>
<xsd:maxInclusive value="99999"/>
</xsd:restriction>
</xsd:simpleType>
Restriction Example
XML (XSD)
27 / 58
<xsd:simpleType name="SKU">
<xsd:restriction base="xsd:string">
<xsd:pattern value="\d{3}-[A-Z]{2}"/>
</xsd:restriction>
</xsd:simpleType>
Restriction Example
XML (XSD)
28 / 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>
List Types
• Comprised of white-space delimited sequences of atomic types
• Create new list types by deriving from existing atomic types
29 / 58
List Example
XML (XSD)
30 / 58
<xsd:simpleType name="intList">
<xsd:list itemType="xsd:int"/>
</xsd:simpleType>
XML<intList>20003 15037 95977 95945</intList>
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
31 / 58
Union Example
XML (XSD)
32 / 58
<xsd:simpleType name="intOrFloat">
<xsd:union memberTypes="xsd:int xsd:float"/>
</xsd:simpleType>
XML<intOrFloat>20003</intOrFloat>
<intOrFloat>42.0</intOrFloat>
Defining Complex Types
• New complex types are defined using the complexTypeelement
• Elements are declared using the element element, and attributes are declared using the attribute element.
33 / 58
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
34 / 58
Complex Type Example
XML (XSD)
35 / 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>
Complex Type Example
XML (XSD)
36 / 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>
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
37 / 58
Complex Type Example
XML (XSD)
38 / 58
<xsd:complexType name="ItemsType">
<xsd:sequence>
<xsd:element name="OrderItem" type="ItemType" minOccurs="0" maxOccurs="unbounded" />
</xsd:sequence>
</xsd:complexType>
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.
39 / 58
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
40 / 58
Element Group Example
XML (XSD)
41 / 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>
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
42 / 58
Annotation Example
XML (XSD)
43 / 58
<xsd:annotation>
<xsd:documentation xml:lang="en">
Order schema for npruehs.de
</xsd:documentation>
</xsd:annotation>
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
44 / 58
XSD Validation in .NET
C#
45 / 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()) { }
}
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
46 / 58
INI File Example
INI
47 / 58
[HostileWorlds.HWSM_Commander]
Scale=1.0
StructureMax=125
ShieldsMax=125
Armor=0
MovementSpeed=160
AttackDamage=4
SplashDamageRadius=0
Cooldown=1.5
Range=500
INI Property
• Name and value
• Delimited by =
48 / 58
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
49 / 58
INI Comment
• Indicated by semicolon at the beginning of the line
• Ignored by processors
50 / 58
Duplicate Propertiesin 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
51 / 58
JSON File Format
• Java Script Object Notation
• Human-readable
• Name-value pairs
52 / 58
JSON Example
JSON
53 / 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]
}}
JSON Primitive Types
• String (Unicode, quotation marks)
• Number (integer, floating point)
• Boolean
• Null
54 / 58
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
55 / 58
YAML File Format
• YAML Ain’t Markup Language
• Human-readable
• Unicode
• Superset of JSON• Every JSON file is also a valid YAML file.
56 / 58
YAML Example
YAML
57 / 58
---Time: 2001-11-23 15:01:42 -5User: edWarning:
This is an error messagefor the log file
---Time: 2001-11-23 15:02:31 -5User: edWarning:
A slightly different errormessage.
---Date: 2001-11-23 15:03:17 -5User: edFatal:
Unknown variable "bar"Stack:
- file: TopClass.pyline: 23
- file: MoreClass.pyline: 58
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
58 / 58
Comparison of File Formats
XML INI JSON YAML Binary
Human-readable
yes yes yes yes no
Data-to-markupratio
low high high high high
Arbitrary Nesting
yes no yes yes yes
59 / 58
Assignment #5
1. XML Serialization
Replace your implementation of the Save As and Open commands, using XMLSerializer for reading and writing your maps!
60 / 58
Assignment #5
2. Analysis of XML Serialization
What are the advantages of your new implementation, what are the drawbacks?
61 / 58
Assignment #5
3. XML Schema
1. Define an XML Schema for your map files.
2. Validate your map files against that schema before loading the map.
62 / 58
References
• MSDN. Introducing XML Serialization. http://msdn.microsoft.com/en-us/library/182eeyhh%28v=vs.110%29.aspx, August 2, 2012.
• MSDN. Attributes That Control XML Serialization. http://msdn.microsoft.com/en-us/library/83y7df3e%28v=vs.110%29.aspx, August 2, 2012.
• 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/schema/schema_complex_indicators.asp, April 2015.
• 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.
63 / 58
Thank you for your attention!
Contact
Blog
http://www.npruehs.de
@npruehs
Github
https://github.com/npruehs
64 / 58
