Cinchoo ETL - XML Reader

Cinchoo

5.00/5 (13 votes)

9 Feb 2022CPOL31 min read

37.2K

Simple XML file reader for .NET

ChoETL is an open source ETL (extract, transform and load) framework for .NET. It is a code based library for extracting data from multiple sources, transforming, and loading into your very own data warehouse in .NET environment. You can have data in your data warehouse in no time.

Introduction
Requirement
"Hello World!" Sample
1. Quick load - Data First Approach
2. Code First Approach
3. Configuration First Approach
4. Code First with declarative configuration
Reading All Records
Read Records Manually
Customize XML Record
Customize XML Fields
1. DefaultValue
2. ChoFallbackValue
3. Type Converters
  1. Declarative Approach
  2. Configuration Approach
4. Validations
Callback Mechanism
1. Using ChoXmlReader events
2. Implementing IChoNotifyRecordRead interface
3. BeginLoad
4. EndLoad
5. BeforeRecordLoad
6. AfterRecordLoad
7. RecordLoadError
8. BeforeRecordFieldLoad
9. AfterRecordFieldLoad
10. RecordLoadFieldError
Customization
AsDataReader Helper Method
AsDataTable Helper Method
Using Dynamic Object
1. DefaultValue
2. ChoFallbackValue
3. FieldType
4. Type Converters
5. Validations
Working with sealed POCO object
Exceptions
Using MetadataType Annotation
Configuration Choices
1. Manual Configuration
2. Auto Map Configuration
3. Attaching MetadataType class
LoadText Helper Method
Advanced Topics
1. Override Converters Format Specs
2. Currency Support
3. Enum Support
4. Boolean Support
5. DateTime Support
6. CDATA Support
Fluent API
1. WithXPath
2. WithXmlNamespaceManager
3. WithXmlNamespace
4. WithFields
5. WithField
6. ColumnCountStrict
History

1. Introduction

This article talks about using ChoXmlReader component offered by ChoETL framework. It is a simple utility class to extract XML data from file / source to objects.

UPDATE: Corresponding XmlWriter article can be found here.

Features

Uses XML Reader, parses XML file in fastest manner
Stream based parsers allow for ultimate performance, low resource usage, and nearly unlimited versatility scalable to any size data file, even tens or hundreds of gigabytes
Event based data manipulation and validation allows total control over the flow of data during the bulk insert process
Exposes IEnumerable list of objects - which is often used with LINQ query for projection, aggregation and filtration, etc.
Supports deferred reading
Supports processing files with culture specific date, currency and number formats
Supports different character encoding
Recognizes a wide variety of date, currency, enum, boolean and number formats when reading files
Provides fine control of date, currency, enum, boolean, number formats when writing files
Detailed and robust error handling, allowing you to quickly find and fix problems

2. Requirement

This framework library is written in C# using .NET 4.x Framework / .NET Core 2.x.

3. "Hello World!" Sample

Open VS.NET 2017 or higher
Create a sample VS.NET (.NET Framework 4.x / .NET Core 2.x) Console Application project
Install ChoETL via Package Manager Console using Nuget Command:
- Install-Package ChoETL
- Install-Package ChoETL.NETStandard
Use the ChoETL namespace

Let's begin by looking into a simple example of reading XML file having two columns.

Listing 3.1 Sample XML Data File

XML

<Employees>
    <Employee Id='1'>
        <Name>Tom</Name>
    </Employee>
    <Employee Id='2'>
        <Name>Mark</Name>
    </Employee>
</Employees>

There are a number of ways you can get the XML file parsing started with minimal setup.

3.1. Quick load - Data First Approach

It is the zero config, quick way to load a XML file in no time. No POCO object is required. Sample code below shows how to load the file.

Listing 3.1.1 Load XML File using Iterator

foreach (dynamic rec in new ChoXmlReader("emp.xml"))
{
    Console.WriteLine(rec.Id);
    Console.WriteLine(rec.Name);
}

Sample fiddle: https://dotnetfiddle.net/X4nJO9

Listing 3.1.2 Load XML File using Loop

var reader = new ChoXmlReader("emp.xml");
dynamic rec;
 
while ((rec = reader.Read()) != null)
{
    Console.WriteLine(rec.Id);
    Console.WriteLine(rec.Name);
}

Sample fiddle: https://dotnetfiddle.net/bm47gw

3.2. Code First Approach

This is another zero config way to parse and load XML file using POCO class. First, define a simple data class to match the underlying XML file layout.

Listing 3.2.1 Simple POCO Entity Class

public partial class EmployeeRec
{
    public int Id { get; set; }
    public string Name { get; set; } 
}

In the above, the class defines two properties matching the sample XML file template.

Listing 3.2.2 Load XML File

foreach (var e in new ChoXmlReader<EmployeeRec>("emp.xml"))
{
    Console.WriteLine(e.Id);
    Console.WriteLine(e.Name);
}

Sample fiddle: https://dotnetfiddle.net/C2B7KO

3.3. Configuration First Approach

In this model, we define the XML configuration with all the necessary parsing parameters along with XML columns matching with the underlying XML file.

Listing 3.3.1 Define XML Configuration

ChoXmlRecordConfiguration config = new ChoXmlRecordConfiguration();
config.XmlRecordFieldConfigurations.Add(new ChoXmlRecordFieldConfiguration("Id"));
config.XmlRecordFieldConfigurations.Add(new ChoXmlRecordFieldConfiguration("Name"));

In the above, the class defines two properties matching the sample XML file template.

Listing 3.3.2 Load XML File without POCO Object

foreach (dynamic e in new ChoXmlReader("emp.xml", config))
{
    Console.WriteLine(e.Id);
    Console.WriteLine(e.Name);
}

Sample fiddle: https://dotnetfiddle.net/hHbVLP

Listing 3.3.3 Load XML file with POCO Object

foreach (var e in new ChoXmlReader<EmployeeRec>("emp.xml", config))
{
    Console.WriteLine(e.Id);
    Console.WriteLine(e.Name);
}

Sample fiddle: https://dotnetfiddle.net/U3QO5e

3.4. Code First with Declarative Configuration

This is the combined approach to define POCO entity class along with XML configuration parameters decorated declaratively. Id is required column and Name is optional value column with default value "XXXX". If Name is not present, it will take the default value. This is OptIn method, telling only decorated members to participate in the serialization operation. Any members not decorated using ChoXmlNodeRecordFieldAttribute will be ignored.

Listing 3.4.1 Define POCO Object

public class EmployeeRec
{
    [ChoXmlNodeRecordField(XPath = "//@Id")]
    [Required]
    public int Id
    {
        get;
        set;
    }
    [ChoXmlNodeRecordField(XPath = "//Name")]
    [DefaultValue("XXXX")]
    public string Name
    {
        get;
        set;
    }
 
    public override string ToString()
    {
        return "{0}. {1}".FormatString(Id, Name);
    }
}

The code above illustrates about defining POCO object to carry the values of each record line in the input file. First thing defines property for each record field with ChoXmlNodeRecordFieldAttribute to qualify for XML record mapping. XPath is a optional property. If not specified, framework automatically discovers and loads the values either from xmlattribute or xmlelement. Id is decorated with RequiredAttribute, if the value is missing, it will throw an exception. Name is given default value using DefaultValueAttribute. It means that if the Name XML column contains empty value in the file, it will be defaulted to 'XXXX' value.

It is very simple and ready to extract XML data in no time.

Listing 3.4.2 Main Method

foreach (var e in new ChoXmlReader<EmployeeRec>("emp.xml"))
{
    Console.WriteLine(e.Id);
    Console.WriteLine(e.Name);
}

We start by creating a new instance of ChoXmlReader object. That's all! All the heavy lifting of parsing and loading XML data stream into the objects is done by the parser under the hood.

By default, ChoXmlReader discovers and uses default configuration parameters while loading XML file. These can be overridable according to your needs. The following sections will give details about each configuration attributes.

Sample fiddle: https://dotnetfiddle.net/lnO6ft

3.4.1. Using BCL Serialization Attributes

This is one other approach to decorate members of the POCO object using BCL serialization attributes, aka. XmlElementAttribute, XmlAttributeAttribute, etc.

Listing 3.4.1.1 Define POCO Object

public class EmployeeRec
{
    [XmlAttribute]
    [Required]
    [ChoXPath("@Id")]   //Optional
    public int Id
    {
        get;
        set;
    }
    [XmlElement]
    [DefaultValue("XXXX")]
    public string Name
    {
        get;
        set;
    }
 
    public override string ToString()
    {
        return "{0}. {1}".FormatString(Id, Name);
    }
}

The code above illustrates about defining POCO object to carry the values of each record line in the input file. First thing defines property for each record field either XAttributeAttribute / XElementAttribute to specify the type of node to map to. It is optional to use these attribute. If not specified, the framework automatically discovers and load the members appropriately. ChoXPath is an optional property to specify xpath of the node to be loaded. Id is decorated with RequiredAttribute, if the value is missing, it will throw an exception. Name is given default value using DefaultValueAttribute. It means that if the Name XML column contains empty value in the file, it will be defaulted to 'XXXX' value.

It is very simple and ready to extract XML data in no time.

Listing 3.4.1.2 Main Method

foreach (var e in new ChoXmlReader<EmployeeRec>("emp.xml"))
{
    Console.WriteLine(e.Id);
    Console.WriteLine(e.Name);
}

We start by creating a new instance of ChoXmlReader object. That's all. All the heavy lifting of parsing and loading XML data stream into the objects is done by the parser under the hood.

4. Reading All Records

It is as easy as setting up POCO object match up with XML file structure, you can read the whole file as enumerable pattern. It is a deferred execution mode, but take care while making any aggregate operation on them. This will load the entire file records into memory.

Listing 4.1 Read XML File

foreach (var e in new ChoXmlReader<EmployeeRec>("emp.xml"))
{
    Console.WriteLine(e.Id);
    Console.WriteLine(e.Name);
}

or:

Listing 4.2 Read XML File Stream

foreach (var e in new ChoXmlReader<EmployeeRec>(textReader))
{
    Console.WriteLine(e.Id);
    Console.WriteLine(e.Name);
}

This model keeps your code elegant, clean, easy to read and maintain. Also leverages LINQ extension methods to perform grouping, joining, projection, aggregation, etc.

Listing 4.3 Using LINQ

var list = (from o in new ChoXmlReader<EmployeeRec>("emp.xml")
           where o.Name != null && o.Name.StartsWith("R")
           select o).ToArray();
 
foreach (var e in list)
{
    Console.WriteLine(e.Id);
    Console.WriteLine(e.Name);
}

5. Read Records Manually

It is as easy as setting up POCO object match up with XML file structure, you can read the whole file as enumerable pattern.

Listing 5.1 Read XML File

var reader = new ChoXmlReader<EmployeeRec>("emp.xml");
EmployeeRec rec = null;
 
while ((rec = reader.Read()) != null)
{
    Console.WriteLine(rec.Id);
    Console.WriteLine(rec.Name);
}

Sample fiddle: https://dotnetfiddle.net/BYK1n4

6. Customize XML Record

Using ChoXmlRecordObjectAttribute, you can customize the POCO entity object declaratively.

Listing 6.1 Customizing POCO Object for Each Record

[ChoXmlRecordObject]
public class EmployeeRec
{
    [ChoXmlNodeRecordField(XPath = "/@Id")] 
    public int Id { get; set; }
    [ChoXmlNodeRecordField(XPath = "/Name")] 
    [Required]
    [DefaultValue("ZZZ")]
    public string Name { get; set; }
}

Here are the available attributes to carry out customization of XML load operation on a file:

XPath - Optional. XPath expression used to pick the elements to load. If not specified, the member value will be discovered and loaded automatically.
ColumnCountStrict - This flag indicates if an exception should be thrown if reading an expected field is missing.
ErrorMode - This flag indicates if an exception should be thrown if reading and an expected field is failed to load. This can be overridden per property. Possible values are:
- IgnoreAndContinue - Ignore the error, record will be skipped and continue with next
- ReportAndContinue - Report the error to POCO entity if it is of IChoNotifyRecordRead type
- ThrowAndStop - Throw the error and stop the execution
IgnoreFieldValueMode - A flag to let the reader know if a record should be skipped when reading if it's empty / null. This can be overridden per property. Possible values are:
- Null - N/A
- DBNull - N/A
- Empty - skipped if the record value is empty
- WhiteSpace - skipped if the record value contains only whitespaces
ObjectValidationMode - A flag to let the reader know about the type of validation to be performed with record object. Possible values are:
- Off - No object validation performed. (Default)
- MemberLevel - Validation performed at the time of each XML property gets loaded with value.
- ObjectLevel - Validation performed after all the properties are loaded to the POCO object.

7. Customize XML Fields

For each XML column, you can specify the mapping in POCO entity property using ChoXmlNodeRecordFieldAttribute. Only use this attribute if you want to use custom xpath to map to this column. Otherwise use the simple variation attributes aka. ChoXmlElementRecordFieldAttribute/ChoXmlAttributeRecordFieldAttribute.

Listing 7.1 Customizing POCO object for XML columns

public class EmployeeRec
{
    [ChoXmlNodeRecordField(XPath="/@Id")]
    public int Id { get; set; }
    [ChoXmlNodeRecordField(XPath="/Name")]
    [Required]
    [DefaultValue("ZZZ")]
    public string Name { get; set; }
}

Here are the available members to add some customization to it for each property:

XPath - Optional. XPath expression uses a path notation, like those used in URLs, for addressing parts of an XML document. If not specified, ChoXmlReader automatically discover and load the value either from XmlElement or XmlAttribute. If not specified, ChoXmlReader discover and load the value from XElement or XAttribute matching the field name.
ErrorMode - This flag indicates if an exception should be thrown if reading and an expected field failed to load. Possible values are:
- IgnoreAndContinue - Ignore the error and continue to load other properties of the record.
- ReportAndContinue - Report the error to POCO entity if it is of IChoRecord type.
- ThrowAndStop - Throw the error and stop the execution.
IgnoreFieldValueMode - A flag to let the reader know if a record should be skipped when reading if it's empty / null. Possible values are:
- Null - N/A
- DBNull - N/A
- Empty - skipped if the record value is empty.
- WhiteSpace - skipped if the record value contains only whitespaces.

7.1. DefaultValue

It is the value used and set to the property when the XML value is empty or whitespace (controlled via IgnoreFieldValueMode).

Any POCO entity property can be specified with default value using System.ComponentModel.DefaultValueAttribute.

7.2. ChoFallbackValue

It is the value used and set to the property when the XML value failed to set. Fallback value only set when ErrorMode is either IgnoreAndContinue or ReportAndContinue.

Any POCO entity property can be specified with fallback value using ChoETL.ChoFallbackValueAttribute.

7.3. Type Converters

Most of the primitive types are automatically converted and set them to the properties. If the value of the XML field can't automatically be converted into the type of the property, you can specify a custom / built-in .NET converters to convert the value. These can be either IValueConverter or TypeConverter converters.

There are couple of ways you can specify the converters for each field:

Declarative Approach
Configuration Approach

7.3.1. Declarative Approach

This model is applicable to POCO entity object only. If you have POCO class, you can specify the converters to each property to carry out necessary conversion on them. Samples below shows the way to do it.

Listing 7.3.1.1 Specifying Type Converters

public class EmployeeRec
{
    [ChoXmlNodeRecordField(XPath: "/@Id")]
    [ChoTypeConverter(typeof(IntConverter))]
    public int Id { get; set; }
    [ChoXmlNodeRecordField(XPath: "/Name")]
    [Required]
    [DefaultValue("ZZZ")]
    public string Name { get; set; }
}

Listing 7.3.1.2 IntConverter Implementation

public class IntConverter : IValueConverter
{
    public object Convert(object value, Type targetType, 
                          object parameter, CultureInfo culture)
    {
        return value;
    }
 
    public object ConvertBack(object value, Type targetType, 
                              object parameter, CultureInfo culture)
    {
        return value;
    }
}

In the example above, we defined custom IntConverter class. And showed how to use it with 'Id' Xml property.

7.3.2. Configuration Approach

This model is applicable to both dynamic and POCO entity object. This gives freedom to attach the converters to each property at runtime. This takes precedence over the declarative converters on POCO classes.

Listing 7.3.2.2 Specifying TypeConverters

ChoXmlRecordConfiguration config = new ChoXmlRecordConfiguration();

ChoXmlNodeRecordFieldConfiguration idConfig = 
      new ChoXmlNodeRecordFieldConfiguration("Id", XPath: "/@Id");
idConfig.AddConverter(new IntConverter());
config.XmlRecordFieldConfigurations.Add(idConfig);

config.XmlRecordFieldConfigurations.Add
       (new ChoXmlNodeRecordFieldConfiguration("Name", XPath: "/Name"));
config.XmlRecordFieldConfigurations.Add
       (new ChoXmlNodeRecordFieldConfiguration("Name1", XPath: "/Name1"));

In the above, we construct and attach the IntConverter to 'Id' field using AddConverter helper method in ChoXmlNodeRecordFieldConfiguration object.

Likewise, if you want to remove any converter from it, you can use RemoveConverter on ChoXmlNodeRecordFieldConfiguration object.

7.4. Validations

ChoXmlReader leverages both System.ComponentModel.DataAnnotations and Validation Block validation attributes to specify validation rules for individual fields of POCO entity. Refer to the MSDN site for a list of available DataAnnotations validation attributes.

Listing 7.4.1 Using Validation Attributes in POCO Entity

[ChoXmlRecordObject]
public partial class EmployeeRec
{
    [ChoXmlNodeRecordField(FieldName = "id", XPath: "/@Id")]
    [ChoTypeConverter(typeof(IntConverter))]
    [Range(1, int.MaxValue, ErrorMessage = "Id must be > 0.")]
    [ChoFallbackValue(1)]
    public int Id { get; set; }
 
    [ChoXmlNodeRecordField(FieldName = "Name", XPath: "/Name")]
    [Required]
    [DefaultValue("ZZZ")]
    [ChoFallbackValue("XXX")]
    public string Name { get; set; }
}

In the example above, used Range validation attribute for Id property. Required validation attribute to Name property. ChoXmlReader performs validation on them during load based on Configuration.ObjectValidationMode is set to ChoObjectValidationMode.MemberLevel or ChoObjectValidationMode.ObjectLevel.

Sometimes, you may want override the defined declarative validation behaviors that come with POCO class, you can do with Cinchoo ETL via configuration approach. The sample below shows the way to override them.

static void ValidationOverridePOCOTest()
{
    ChoXmlRecordConfiguration config = new ChoXmlRecordConfiguration();
    var idConfig = new ChoXmlNodeRecordFieldConfiguration("Id", XPath: "/@Id");
    idConfig.Validators = new ValidationAttribute[] { new RequiredAttribute() };
    config.XmlRecordFieldConfigurations.Add(idConfig);
    config.XmlRecordFieldConfigurations.Add
      (new ChoXmlNodeRecordFieldConfiguration("Name", XPath: "/Name));
    config.XmlRecordFieldConfigurations.Add
      (new ChoXmlNodeRecordFieldConfiguration("Salary", XPath: "/Salary"));
 
    using (var parser = new ChoXmlReader<EmployeeRecWithCurrency>("emp.xml", config))
    {
        object rec;
        while ((rec = parser.Read()) != null)
        {
            Console.WriteLine(rec.ToStringEx());
        }
    }
}
 
public class EmployeeRecWithCurrency
{
    public int? Id { get; set; }
    public string Name { get; set; }
    public ChoCurrency Salary { get; set; }
}

In some cases, you may want to take control and perform manual self validation within the POCO entity class. This can be achieved by inheriting POCO object from IChoValidatable interface.

Listing 7.4.2 Manual Validation on POCO Entity

[ChoXmlRecordObject]
public partial class EmployeeRec : IChoValidatable
{
    [ChoXmlNodeRecordField(FieldName = "id", XPath: "/@Id")]
    [ChoTypeConverter(typeof(IntConverter))]
    [Range(1, int.MaxValue, ErrorMessage = "Id must be > 0.")]
    [ChoFallbackValue(1)]
    public int Id { get; set; }
 
    [ChoXmlNodeRecordField(FieldName = "Name", XPath: "/Name")]
    [Required]
    [DefaultValue("ZZZ")]
    [ChoFallbackValue("XXX")]
    public string Name { get; set; }
 
    public bool TryValidate
    (object target, ICollection<ValidationResult> validationResults)
    {
        return true;
    }
 
    public bool TryValidateFor
    (object target, string memberName, ICollection<ValidationResult> validationResults)
    {
        return true;
    }
 
    public void Validate(object target)
    {
    }
 
    public void ValidateFor(object target, string memberName)
    {
    }
}

The sample above shows how to implement custom self-validation in POCO object.

IChoValidatable interface exposes the below methods:

TryValidate - Validate entire object, return true if all validation passed. Otherwise return false.
Validate - Validate entire object, throw exception if validation is not passed.
TryValidateFor - Validate specific property of the object, return true if all validation passed. Otherwise return false.
ValidateFor - Validate specific property of the object, throw exception if validation is not passed.

8. Callback Mechanism

ChoXmlReader offers industry standard XML parsing out of the box to handle most of the parsing needs. If the parsing is not handling any of the needs, you can use the callback mechanism offered by ChoXmlReader to handle such situations. In order to participate in the callback mechanism, you can use either of the following models:

Using event handlers exposed by ChoXmlReader via IChoReader interface.
Inheriting POCO entity object from IChoNotifyRecordRead / IChoNotifyFileRead / IChoNotifyRecordFieldRead interfaces
Inheriting DataAnnotation's MetadataType type object by IChoNotifyRecordRead / IChoNotifyFileRead / IChoNotifyRecordFieldRead interfaces.
Inheriting IChoNotifyRecordFieldConfigurable / IChoNotifyRecordFieldConfigurable configuration interfaces

Note: Any exceptions raised out of these interface methods will be ignored.

IChoReader exposes the below events:

BeginLoad - Invoked at the begin of the XML file load
EndLoad - Invoked at the end of the XML file load
BeforeRecordLoad - Raised before the XML record load
AfterRecordLoad - Raised after XML record load
RecordLoadError - Raised when XML record load errors out
BeforeRecordFieldLoad - Raised before XML field value load
AfterRecordFieldLoad - Raised after XML field value load
RecordFieldLoadError - Raised when XML field value errors out
SkipUntil - Raised before the XML parsing kicks off to add custom logic to skip record lines.
DoWhile - Raised during XML parsing where you can add custom logic to stop the parsing.

IChoNotifyRecordRead exposes the below methods:

BeforeRecordLoad - Raised before the XML record load
AfterRecordLoad - Raised after XML record load
RecordLoadError - Raised when XML record load errors out

IChoNotifyFileRead exposes the below methods:

BeginLoad - Invoked at the begin of the XML file load
EndLoad - Invoked at the end of the XML file load
SkipUntil - Raised before the XML parsing kicks off to add custom logic to skip record lines
DoWhile - Raised during XML parsing where you can add custom logic to stop the parsing

IChoNotifyRecordFieldRead exposes the below methods:

BeforeRecordFieldLoad - Raised before XML field value load
AfterRecordFieldLoad - Raised after XML field value load
RecordFieldLoadError - Raised when XML field value errors out

IChoNotifyRecordConfigurable exposes the below method:

RecordConfigure - Raised for XML record configuration

IChoNotifyRecordFieldConfigurable exposes the below method:

RecondFieldConfigure - Raised for each XML record field configuration

8.1. Using ChoXmlReader Events

This is more direct and simplest way to subscribe to the callback events and handle your odd situations in parsing XML files. The downside is that code can't be reusable as you do by implementing IChoNotifyRecordRead with POCO record object.

The sample below shows how to use the BeforeRecordLoad callback method to skip nodes having Id < 100.

static void IgnoreNodeTest()
{
    using (var parser = new ChoXmlReader("emp.xml"))
    {
        parser.BeforeRecordLoad += (o, e) =>
        {
            if (e.Source != null)
            {
                e.Skip = ((XElement)e.Source).Attribute["Id"].Value < 100;
            }
        };
        foreach (var e in parser)
            Console.WriteLine(e.Dump());
    }
}

Likewise, you can use other callback methods as well with ChoXmlReader.

8.2. Implementing IChoNotifyRecordRead Interface

The sample below shows how to implement IChoNotifyRecordRead interface to direct POCO class.

Listing 8.2.1 Direct POCO callback mechanism implementation

[ChoXmlRecordObject]
public partial class EmployeeRec : IChoNotifyRecordRead
{
    [ChoXmlNodeRecordField(FieldName = "Id", XPath: "/@Id")]
    [ChoTypeConverter(typeof(IntConverter))]
    [Range(1, int.MaxValue, ErrorMessage = "Id must be > 0.")]
    [ChoFallbackValue(1)]
    public int Id { get; set; }
    
    [ChoXmlNodeRecordField(FieldName = "Name", XPath: "/Name")]
    [Required]
    [DefaultValue("ZZZ")]
    [ChoFallbackValue("XXX")]
    public string Name { get; set; }
 
    public bool AfterRecordLoad(object target, int index, object source)
    {
        throw new NotImplementedException();
    }
 
    public bool BeforeRecordLoad(object target, int index, ref object source)
    {
        throw new NotImplementedException();
    }
 
    public bool RecordFieldLoadError
    (object target, int index, string propName, object value, Exception ex)
    {
        throw new NotImplementedException();
    }
}

The sample below shows how to attach Metadata class to POCO class by using MetadataTypeAttribute on it.

Listing 8.2.2 MetaDataType based callback mechanism implementation

[ChoXmlRecordObject]
public class EmployeeRecMeta : IChoNotifyRecordRead
{
    [ChoXmlNodeRecordField(FieldName = "Id", XPath: "/@Id")]
    [ChoTypeConverter(typeof(IntConverter))]
    [Range(1, int.MaxValue, ErrorMessage = "Id must be > 0.")]
    [ChoFallbackValue(1)]
    public int Id { get; set; }

    [ChoXmlNodeRecordField(FieldName = "Name", XPath: "/Name")]
    [Required]
    [DefaultValue("ZZZ")]
    [ChoFallbackValue("XXX")]
    public string Name { get; set; }
 
    public bool AfterRecordLoad(object target, int index, object source)
    {
        throw new NotImplementedException();
    }
 
    public bool BeforeRecordLoad(object target, int index, ref object source)
    {
        throw new NotImplementedException();
    }
 
    public bool RecordFieldLoadError
    (object target, int index, string propName, object value, Exception ex)
    {
        throw new NotImplementedException();
    }
} 

[MetadataType(typeof(EmployeeRecMeta))]
public partial class EmployeeRec
{
    public int Id { get; set; }
    public string Name { get; set; }
}

The sample below shows how to attach Metadata class for sealed or third party POCO class by using ChoMetadataRefTypeAttribute on it.

Listing 8.2.3 ChoMetaDataRefType based callback mechanism implementation

[ChoMetadataRefType(typeof(EmployeeRec))]
[ChoXmlRecordObject]
public class EmployeeRecMeta : IChoNotifyRecordRead
{
    [ChoXmlNodeRecordField(FieldName = "Id", XPath: "/@Id")]
    [ChoTypeConverter(typeof(IntConverter))]
    [Range(1, int.MaxValue, ErrorMessage = "Id must be > 0.")]
    [ChoFallbackValue(1)]
    public int Id { get; set; }

    [ChoXmlNodeRecordField(FieldName = "Name", XPath: "/Name")]
    [Required]
    [DefaultValue("ZZZ")]
    [ChoFallbackValue("XXX")]
    public string Name { get; set; }
 
    public bool AfterRecordLoad(object target, int index, object source)
    {
        throw new NotImplementedException();
    }
 
    public bool BeforeRecordLoad(object target, int index, ref object source)
    {
        throw new NotImplementedException();
    }
 
    public bool RecordLoadError(object target, int index, object source, Exception ex)
    {
        throw new NotImplementedException();
    }
} 

public partial class EmployeeRec
{
    public int Id { get; set; }    
    public string Name { get; set; }
}

8.3. BeginLoad

This callback invoked once at the beginning of the XML file load. source is the XML file stream object. In here, you have a chance to inspect the stream, return true to continue the XML load. Return false to stop the parsing.

Listing 10.3.1 BeginLoad Callback Sample

public bool BeginLoad(object source)
{
    StreamReader sr = source as StreamReader;
    return true;
}

8.4. EndLoad

This callback invoked once at the end of the XML file load. source is the XML file stream object. In here, you have a chance to inspect the stream, do any post steps to be performed on the stream.

Listing 8.4.1 EndLoad Callback Sample

public void EndLoad(object source)
{
    StreamReader sr = source as StreamReader;
}

8.5. BeforeRecordLoad

This callback invoked before each record line in the XML file is loaded. target is the instance of the POCO record object. index is the line index in the file. source is the XML record line. In here, you have a chance to inspect the line, and override it with new line if you want to.

TIP: If you want to skip the XNode from loading, set the source to null.

TIP: If you want to take control of parsing and loading the record properties by yourself, set the source to String.Empty.