<Employees>
    <Employee>
        <Id>1</Id>
        <Name>Tom</Name>
    </Employee>
    <Employee>
        <Id>1</Id>
        <Name>Mark</Name>
    </Employee>
</Employees>

有多种方法可以在最小设置下创建XML文件。

3.1. 快速写入 - 数据优先方法

这是零配置且最快的方法，可以立即创建XML文件。无需类型化的POCO对象。下面的示例代码展示了如何使用动态对象生成示例XML文件。

列表3.1.1 将对象列表写入XML文件

List<ExpandoObject> objs = new List<ExpandoObject>();
dynamic rec1 = new ExpandoObject();
rec1.Id = 1;
rec1.Name = "Mark";
objs.Add(rec1);
 
dynamic rec2 = new ExpandoObject();
rec2.Id = 2;
rec2.Name = "Jason";
objs.Add(rec2);
 
using (var parser = new ChoXmlWriter("Emp.xml").WithXPath("Employees/Employee"))
{
    parser.Write(objs);
}

在上面的示例中，我们将对象列表一次性传递给XmlWriter，将它们写入XML文件。

列表3.1.2 将每个对象写入XML文件

using (var parser = new ChoXmlWriter("Emp.xml").WithXPath("Employees/Employee"))
{
    dynamic rec1 = new ExpandoObject();
    rec1.Id = 1;
    rec1.Name = "Mark";
    parser.Write(item);

    dynamic rec1 = new ExpandoObject();
    rec1.Id = 2;
    rec1.Name = "Jason";
    parser.Write(item);
}

在上面的示例中，我们控制构造，并将每个单独的记录传递给XmlWriter，使用Write重载生成XML文件。

3.3. 配置优先方法

在此模型中，我们定义了XML配置，其中包含所有必要的参数以及生成示例XML文件所需的XML列。

列表3.3.1 定义XML配置

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

在上面，该类定义了两个与示例XML文件模板匹配的XML属性。

列表3.3.2 不使用POCO对象生成XML文件

List<ExpandoObject> objs = new List<ExpandoObject>();

dynamic rec1 = new ExpandoObject();
rec1.Id = 1;
rec1.Name = "Mark";
objs.Add(rec1);
 
dynamic rec2 = new ExpandoObject();
rec2.Id = 2;
rec2.Name = "Tom";
objs.Add(rec2);
 
using (var parser = new ChoXmlWriter("Emp.xml", config).WithXPath("Employees/Employee"))
{
    parser.Write(objs);
}

上面的示例代码展示了如何使用预定义的XML配置设置从动态对象列表生成XML文件。在XmlWriter构造函数中，我们指定了XML配置对象，以便在创建文件时遵循XML布局模式。如果XML列的名称或数量存在任何不匹配，将报告错误并停止写入过程。

列表3.3.3 使用POCO对象保存XML文件

List<EmployeeRecSimple> objs = new List<EmployeeRecSimple>();

EmployeeRecSimple rec1 = new EmployeeRecSimple();
rec1.Id = 1;
rec1.Name = "Mark";
objs.Add(rec1);
 
EmployeeRecSimple rec2 = new EmployeeRecSimple();
rec2.Id = 2;
rec2.Name = "Jason";
objs.Add(rec2);
 
using (var parser = new ChoXmlWriter<EmployeeRecSimple>
      ("Emp.xml", config).WithXPath("Employees/Employee"))
{
    parser.Write(objs);
}

上面的示例代码展示了如何使用XML配置对象从POCO对象列表生成XML文件。在XmlWriter构造函数中，我们指定了XML配置对象。

3.4. 代码优先声明式配置

这是一种组合方法，用于定义POCO实体类并声明性地附加XML配置参数。id是必需列，name是可选值列，默认值为"XXXX"。如果name不存在，它将采用默认值。

清单 3.4.1 定义 POCO 对象

public class EmployeeRec
{
    [ChoXmlElementRecordField]
    [Required]
    public int? Id
    {
        get;
        set;
    }

    [ChoXmlElementRecordField]
    [DefaultValue("XXXX")]
    public string Name
    {
        get;
        set;
    }
}

上面的代码说明了如何使用生成XML文件所需的属性定义POCO对象。首先，为每个记录字段定义属性，并使用ChoXmlElementRecordFieldAttribute使其符合XML记录映射。Id是必需属性。我们使用RequiredAttribute对其进行修饰。Name使用DefaultValueAttribute给定默认值。这意味着如果对象中未设置Name值，XmlWriter会将默认值“XXXX”输出到文件中。

要将属性定义为XML属性，请使用ChoXmlAttributeRecordFieldAttribute。

它非常简单，可以立即保存XML数据。

列表3.4.2 使用POCO对象保存XML文件

List<EmployeeRec> objs = new List<EmployeeRec>();

EmployeeRec rec1 = new EmployeeRec();
rec1.Id = 10;
rec1.Name = "Mark";
objs.Add(rec1);
 
EmployeeRec rec2 = new EmployeeRec();
rec2.Id = 200;
rec2.Name = "Lou";
objs.Add(rec2);
 
using (var parser = new ChoXmlWriter<EmployeeRec>
      ("Emp.xml").WithXPath("Employees/Employee"))
{
    parser.Write(objs);
}

我们首先创建一个ChoXmlWriter对象的新实例。就是这样。所有从对象生成XML数据的繁重工作都由写入器在后台完成。

默认情况下，XmlWriter在保存XML文件时会发现并使用默认配置参数。这些参数可以根据您的需求进行覆盖。以下部分将为您提供每个配置属性的深入详细信息。

4. 写入所有记录

这就像设置POCO对象以匹配XML文件结构，构造对象列表并将其传递给XmlWriter的Write方法一样简单。这将通过一次调用将整个对象列表写入XML文件。

列表4.1 写入XML文件

List<EmployeeRec> objs = new List<EmployeeRec>();
//Construct and attach objects to this list
...

using (var parser = new ChoXmlWriter<EmployeeRec>
                    ("Emp.xml").WithXPath("Employees/Employee"))
{
    parser.Write(objs);
}

或

列表4.2 写入XML文件流

List<EmployeeRec> objs = new List<EmployeeRec>();
//Construct and attach objects to this list
...

using (var tx = File.OpenWrite("Emp.xml"))
{
    using (var parser = 
           new ChoXmlWriter<EmployeeRec>(tx).WithXPath("Employees/Employee"))
    {
        parser.Write(objs);
    }
}

这种模型使您的代码优雅、整洁、易于阅读和维护。

5. 手动写入记录

这是一种替代方法，用于在POCO对象以非连接方式构造的情况下将每个单独的记录写入XML文件。

列表5.1 写入XML文件

var writer = new ChoXmlWriter<EmployeeRec>("Emp.xml");
writer.WithXPath("Employees/Employee");

EmployeeRec rec1 = new EmployeeRec();
rec1.Id = 10;
rec1.Name = "Mark";
 
writer.Write(rec1);

EmployeeRec rec2 = new EmployeeRec();
rec1.Id = 11;
rec1.Name = "Top"; 

writer.Write(rec2);

6. 自定义XML记录

使用ChoXmlRecordObjectAttribute，您可以声明性地自定义POCO实体对象。

列表6.1 为每个记录自定义POCO对象

[ChoXmlRecordObject(Encoding = "Encoding.UTF32", 
ErrorMode = ChoErrorMode.IgnoreAndContinue, 
            IgnoreFieldValueMode = ChoIgnoreFieldValueMode.All)]
public class EmployeeRec
{
    [ChoXmlElementRecordField]
    public int Id { get; set; }
    [ChoXmlElementRecordField]
    [Required]
    [DefaultValue("ZZZ")]
    public string Name { get; set; }
}

以下是用于对文件上的XML加载操作进行自定义的可用属性。

XPath - 可选。用于生成根元素和子元素的XPath表达式。通常，表达式的格式为“RootName/ElementName”。例如，“Employees/Employee”。如果未指定，“Root”将用作根元素，“XElement”将用于每个对象。
EOLDelimiter - 不适用
Culture - 用于读取和写入的文化信息。
IgnoreEmptyLine - 不适用
Comments - 不适用
QuoteChar - 不适用
QuoteAllFields - 不适用
Encoding - XML文件的编码。
ColumnCountStrict - 此标志指示如果XML字段配置与数据对象成员不匹配，是否应抛出异常。
ColumnOrderStrict - 不适用
BufferSize - 当读取器从StreamWriter读取时使用的内部缓冲区的大小。
ErrorMode - 此标志指示在写入过程中是否应抛出异常，并且预期的字段未能写入。可以按属性覆盖。可能的值是
- IgnoreAndContinue - 忽略错误，跳过记录并继续处理下一条。
- ReportAndContinue - 如果 POCO 实体是 IChoNotifyRecordWrite 类型，则向其报告错误
- ThrowAndStop - 抛出错误并停止执行
IgnoreFieldValueMode - 不适用
ObjectValidationMode - 一个标志，告知读取器关于记录对象要执行的验证类型。可能的值是
- Off - 不执行对象验证。(默认)
- MemberLevel - 在每个XML属性写入文件之前执行的验证。
- ObjectLevel - 在所有POCO属性写入文件之前执行的验证。

7. 自定义XML字段

对于每个XML列，您可以使用ChoXmlElementRecordFieldAttribute/ChoXmlAttributeRecordFieldAttribute在POCO实体属性中指定映射。

列表7.1 为XML列自定义POCO对象

[ChoXmlFileHeader]
public class EmployeeRec
{
    [ChoXmlElementRecordField]
    public int Id { get; set; }
    [ChoXmlElementRecordField]
    [Required]
    [DefaultValue("ZZZ")]
    public string Name { get; set; }
}

以下是您可以为每个属性添加自定义的可用成员

FieldName - XML元素/属性名称。如果未指定，将使用对象属性名称。
FillChar - 当列值大小小于列大小时使用的填充字符。默认为“ ”，不进行填充。
FieldValueJustification - 列值对齐方式。默认为左对齐。
FieldValueTrimOption - 不适用。
Truncate - 此标志告诉写入器如果XML列值超过列大小，则截断该值。默认为false。
Size - XML列值的大小。
QuoteField - 不适用
ErrorMode - 此标志指示在写入过程中是否应抛出异常，并且预期的字段未能转换和写入。可能的值是
- IgnoreAndContinue - 忽略错误，继续加载记录的其他属性。
- ReportAndContinue - 如果 POCO 实体是 IChoRecord 类型，则向其报告错误。
- ThrowAndStop - 抛出错误并停止执行。
IgnoreFieldValueMode - 不适用

7.1. 默认值

任何POCO实体属性都可以使用System.ComponentModel.DefaultValueAttribute指定默认值。当XML值为null时（通过IgnoreFieldValueMode控制）用于写入的值。

7.2. 后备值

任何POCO实体属性都可以使用ChoETL.ChoFallbackValueAttribute指定备用值。当XML值无法转换为文本时，该值用于设置属性。Fallback值仅在ErrorMode为IgnoreAndContinue或ReportAndContinue时设置。

7.3. 类型转换器

大多数基本类型会自动转换为字符串/文本并保存到XML文件。如果XML字段的值未自动转换为文本值，您可以指定自定义/内置.NET转换器将值转换为文本。这些可以是IValueConverter或TypeConverter转换器。

用于将/格式化属性值转换为文本的方法是IValueConverter.ConvertBack()或TypeConvert.ConvertTo()。

列表7.3.1 指定类型转换器

[ChoXmlFileHeader]
public class EmployeeRec
{
    [ChoXmlElementRecordField]
    [ChoTypeConverter(typeof(IntConverter))]
    public int Id { get; set; }
    [ChoXmlElementRecordField]
    [Required]
    [DefaultValue("ZZZ")]
    public string Name { get; set; }
}

列表7.3.2 IntConverter实现

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)
    {
        int intValue = (int)value;
        return intValue.ToString("D4");
    }
}

在上面的示例中，我们定义了自定义IntConverter类。并展示了如何使用前导零格式化“Id”XML属性。

7.4. 验证

XmlWriter利用System.ComponentModel.DataAnnotations和Validation Block验证属性来为POCO实体的各个字段指定验证规则。有关可用DataAnnotations验证属性的列表，请参阅MSDN网站。

图 7.4.1 在 POCO 实体中使用验证属性

[ChoXmlFileHeader]
[ChoXmlRecordObject(Encoding = "Encoding.UTF32", 
       ErrorMode = ChoErrorMode.IgnoreAndContinue,
       IgnoreFieldValueMode = ChoIgnoreFieldValueMode.All, 
       ThrowAndStopOnMissingField = false)]
public partial class EmployeeRec
{
    [ChoXmlElementRecordField]
    [ChoTypeConverter(typeof(IntConverter))]
    [Range(1, int.MaxValue, ErrorMessage = "Id must be > 0.")]
    [ChoFallbackValue(1)]
    public int Id { get; set; }
 
    [ChoXmlElementRecordField]
    [Required]
    [DefaultValue("ZZZ")]
    [ChoFallbackValue("XXX")]
    public string Name { get; set; }
}

在上面的示例中，将Range验证属性用于Id属性。将Required验证属性用于Name属性。当Configuration.ObjectValidationMode设置为ChoObjectValidationMode.MemberLevel或ChoObjectValidationMode.ObjectLevel时，XmlWriter在将数据保存到文件之前对它们执行验证。

在某些情况下，您可能希望获得控制权并在 POCO 实体类中执行手动**自验证**。这可以通过继承 POCO 对象并实现 IChoValidatable 接口来实现。

图 7.4.2 在 POCO 实体上手动验证

[ChoXmlFileHeader]
[ChoXmlRecordObject(Encoding = "Encoding.UTF32", 
       ErrorMode = ChoErrorMode.IgnoreAndContinue,
       IgnoreFieldValueMode = ChoIgnoreFieldValueMode.All, 
       ThrowAndStopOnMissingField = false)]
public partial class EmployeeRec : IChoValidatable
{
    [ChoXmlElementRecordField]
    [ChoTypeConverter(typeof(IntConverter))]
    [Range(1, int.MaxValue, ErrorMessage = "Id must be > 0.")]
    [ChoFallbackValue(1)]
    public int Id { get; set; }
 
    [ChoXmlElementRecordField]
    [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)
    {
    }
}

上面的示例展示了如何在 POCO 对象中实现自定义自验证。

IChoValidatable 接口公开以下方法

TryValidate - 验证整个对象，如果所有验证都通过，则返回true。否则，返回false。
Validate - 验证整个对象，如果验证未通过，则抛出异常。
TryValidateFor - 验证对象的特定属性，如果所有验证都通过，则返回true。否则返回false。
ValidateFor - 验证对象的特定属性，如果验证未通过则抛出异常。

8. 回调机制

XmlWriter开箱即用，提供行业标准的XML数据文件生成功能，可满足大多数需求。如果生成过程无法满足您的任何需求，您可以使用XmlWriter提供的回调机制来处理此类情况。为了参与回调机制，POCO实体对象或DataAnnotation的MetadataType类型对象必须继承IChoNotifyRecordWrite接口。

提示：从此接口方法中引发的任何异常都将被忽略。

IChoNotifyRecordWrite 公开了以下方法

BeginWrite - 在XML文件写入开始时调用
EndWrite - 在XML文件写入结束时调用
BeforeRecordWrite - 在XML记录写入之前引发
AfterRecordWrite - 在XML记录写入之后引发
RecordWriteError - 在写入XML记录时发生错误时引发
BeforeRecordFieldWrite - 在XML列值写入之前引发
AfterRecordFieldWrite - 在XML列值写入之后引发
RecordFieldWriteError - 在写入XML列值时发生错误时引发

列表8.1 直接POCO回调机制实现

[ChoXmlFileHeader]
[ChoXmlRecordObject(Encoding = "Encoding.UTF32", 
                    ErrorMode = ChoErrorMode.IgnoreAndContinue,
       IgnoreFieldValueMode = ChoIgnoreFieldValueMode.All, 
                  ThrowAndStopOnMissingField = false)]
public partial class EmployeeRec : IChoNotifyrRecordWrite
{
    [ChoXmlElementRecordField]
    [ChoTypeConverter(typeof(IntConverter))]
    [Range(1, int.MaxValue, ErrorMessage = "Id must be > 0.")]
    [ChoFallbackValue(1)]
    public int Id { get; set; }
    
    [ChoXmlElementRecordField]
    [Required]
    [DefaultValue("ZZZ")]
    [ChoFallbackValue("XXX")]
    public string Name { get; set; }

    public bool AfterRecordFieldWrite
           (object target, int index, string propName, object value)
    {
        throw new NotImplementedException();
    }

    public bool AfterRecordWrite(object target, int index, object source)
    {
        throw new NotImplementedException();
    }

    public bool BeforeRecordFieldWrite
           (object target, int index, string propName, ref object value)
    {
        throw new NotImplementedException();
    }

    public bool BeforeRecordWrite(object target, int index, ref object source)
    {
        throw new NotImplementedException();
    }

    public bool BeginWrite(object source)
    {
        throw new NotImplementedException();
    }

    public void EndWrite(object source)
    {
        throw new NotImplementedException();
    }

    public bool RecordFieldWriteError
    (object target, int index, string propName, object value, Exception ex)
    {
        throw new NotImplementedException();
    }

    public bool RecordWriteError
    (object target, int index, object source, Exception ex)
    {
        throw new NotImplementedException();
    }
}

列表8.2 基于MetaDataType的回调机制实现

[ChoXmlFileHeader]
[ChoXmlRecordObject(Encoding = "Encoding.UTF32", 
       ErrorMode = ChoErrorMode.IgnoreAndContinue,
       IgnoreFieldValueMode = ChoIgnoreFieldValueMode.All, 
       ThrowAndStopOnMissingField = false)]
public class EmployeeRecMeta : IChoNotifyRecordWrite
{
    [ChoXmlElementRecordField]
    [ChoTypeConverter(typeof(IntConverter))]
    [Range(1, int.MaxValue, ErrorMessage = "Id must be > 0.")]
    [ChoFallbackValue(1)]
    public int Id { get; set; }

    [ChoXmlElementRecordField]
    [Required]
    [DefaultValue("ZZZ")]
    [ChoFallbackValue("XXX")]
    public string Name { get; set; }
 
    public bool AfterRecordFieldWrite
           (object target, int index, string propName, object value)
    {
        throw new NotImplementedException();
    }

    public bool AfterRecordWrite(object target, int index, object source)
    {
        throw new NotImplementedException();
    }

    public bool BeforeRecordFieldWrite
    (object target, int index, string propName, ref object value)
    {
        throw new NotImplementedException();
    }

    public bool BeforeRecordWrite(object target, int index, ref object source)
    {
        throw new NotImplementedException();
    }

    public bool BeginWrite(object source)
    {
        throw new NotImplementedException();
    }

    public void EndWrite(object source)
    {
        throw new NotImplementedException();
    }

    public bool RecordFieldWriteError
    (object target, int index, string propName, object value, Exception ex)
    {
        throw new NotImplementedException();
    }

    public bool RecordWriteError(object target, int index, object source, Exception ex)
    {
        throw new NotImplementedException();
    }
} 

[MetadataType(typeof(EmployeeRecMeta))]
public partial class EmployeeRec
{
    [ChoXmlElementRecordField]
    [ChoTypeConverter(typeof(IntConverter))]
    [Range(1, int.MaxValue, ErrorMessage = "Id must be > 0.")]
    [ChoFallbackValue(1)]
    public int Id { get; set; }
    
    [ChoXmlElementRecordField]
    [Required]
    [DefaultValue("ZZZ")]
    [ChoFallbackValue("XXX")]
    public string Name { get; set; }
}

8.1 BeginWrite

此回调在XML文件写入开始时调用一次。source是XML文件流对象。在此处，您有机会检查流，返回true以继续XML生成。返回false以停止生成。

列表 10.1.1 BeginWrite 回调示例

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

8.2 EndWrite

此回调在XML文件生成结束时调用一次。source是XML文件流对象。在此处，您有机会检查流，对流执行任何后续步骤。

列表 10.2.1 EndWrite 回调示例

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

8.3 BeforeRecordWrite

此回调在每个POCO记录对象写入XML文件之前调用。target是POCO记录对象的实例。index是文件中的行索引。source是XML记录行。在此处，您有机会检查POCO对象，并在需要时生成XML记录行。

提示：如果您想跳过记录而不写入，请将 source 设置为 null。

提示：如果您想控制XML记录行生成，请将源设置为有效的XML记录行文本。