Tool Development 05 - XML Schema, INI, JSON, YAML

1,463 views

Published on

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.

Published in: Technology
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
1,463
On SlideShare
0
From Embeds
0
Number of Embeds
2
Actions
Shares
0
Downloads
23
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

Tool Development 05 - XML Schema, INI, JSON, YAML

  1. 1. Tool Development Chapter 05: XML Schema, INI, JSON, YAML Nick Prühs
  2. 2. Assignment Solution #4 DEMO 2 / 58
  3. 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. 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. 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. 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. 7. XML Serialization Example C# 7 / 58 public class OrderItem { public string Name { get; set; } public float PricePerUnit { get; set; } }
  8. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 18. Hint This approach works great with other data formats as well! 18 / 78
  19. 19. Gotcha! Serialize enum values as strings! 19 / 58
  20. 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. 21. Simple vs. Complex Types Simple Types Complex Types Element Content no yes Attributes no yes 21 / 58
  22. 22. Built-In Simple Types • String • Integer • PositiveInteger • Int • Long • Float • Boolean • DateTime • anyURI • anyType • And many, many more… 22 / 58
  23. 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. 24. Simple Type Restriction Facets • length • minLength/maxLength • pattern • enumeration • minInclusive/maxInclusive • minExclusive/maxExclusive 24 / 58
  25. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 42. Annotation Example XML (XSD) 42 / 58 <xsd:annotation> <xsd:documentation xml:lang="en"> Order schema for npruehs.de </xsd:documentation> </xsd:annotation>
  43. 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. 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. 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. 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. 47. INI Property • Name and value • Delimited by = 47 / 58
  48. 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. 49. INI Comment • Indicated by semicolon at the beginning of the line • Ignored by processors 49 / 58
  50. 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. 51. JSON File Format • Java Script Object Notation • Human-readable • Name-value pairs 51 / 58
  52. 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. 53. JSON Primitive Types • String (Unicode, quotation marks) • Number (integer, floating point) • Boolean • Null 53 / 58
  54. 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. 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. 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. 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. 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. 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. 60. Assignment #5 2. Analysis of XML Serialization What are the advantages of your new implementation, what are the drawbacks? 60 / 58
  61. 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. 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. 63. Thank you! http://www.npruehs.de https://github.com/npruehs @npruehs dev@npruehs.de
  64. 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

×