attribute 元素绑定支持

2007-12-31

.NET Framework 为 <attribute> 元素提供绑定支持。

但是，除非全局属性是在该架构的目标命名空间之外的命名空间中声明的，否则 Xsd.exe 将无法区分出局部声明的属性和对全局声明的属性的引用。

说明

XML 架构规范规定，可以在复杂类型定义内局部声明属性，也可以全局声明属性，在后一种情况下，一个或多个复杂类型定义可以通过 ref 属性来引用该属性。

下面是局部声明的属性的示例：

<xsd:complexType name="PurchaseOrderType">
  <xsd:sequence>
    <xsd:element name="field1" type="xsd:string"/>
  </xsd:sequence>
  <xsd:attribute name="name" type="xsd:string"/>
</xsd:complexType>

下面是先进行全局声明然后被引用的同一属性的示例：

<xsd:attribute name="name" type="xsd:string"/>
<xsd:complexType name="PurchaseOrderType">
  <xsd:sequence>
    <xsd:element name="field1" type="xsd:string"/>
  </xsd:sequence>
  <xsd:attribute ref="name"/>
</xsd:complexType>

除非全局属性是在该架构的目标命名空间之外的命名空间中声明的，否则 Xsd.exe 将无法区分出局部声明的属性和对全局声明的属性的引用。

同一命名空间内的引用

由于 Xsd.exe 无法在同一命名空间内对二者进行区分，因此，当执行 XML 架构与类之间的往返翻译时，会创建一个局部属性，该属性将取代曾是全局属性和引用的内容。

对另一个命名空间的引用

如果所引用的全局声明属于另一个命名空间，则 Xsd.exe 使用应用于所生成的字段的 XmlAttributeAttribute 属性 (Attribute) 的 Namespace 属性 (Property) 来指定该命名空间。对于该特定元素，通过 Namespace 属性 (Property) 指定的命名空间重写使用 XmlTypeAttribute 属性 (Attribute) 和 XmlRootAttribute（可选）在类级别指定的命名空间。下面是一个示例：

[System.Xml.Serialization.XmlAttributeAttribute(Namespace="http://example.org/attr")]

public string Key;

其他命名空间是使用 <import> 元素导入到 XML 架构定义中的。

示例

第一个示例演示当在包含对某个全局属性的引用的同一个目标命名空间中定义该属性时，Xsd.exe 如何处理该属性。

输入 XML 架构文档：

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
            xmlns="http://example.org/" targetNamespace="http://example.org/" elementFormDefault="qualified">
  <xsd:attribute name="version" type="xsd:string"/>
  <xsd:complexType name="keyInfo">
    <xsd:attribute ref="version" />
    <xsd:attribute name="public" type="xsd:boolean" use="required"/>
  </xsd:complexType>
  <xsd:element name="key" type="keyInfo"/>
</xsd:schema>

基于前面的 XML 架构文档生成的 C# 类：

[System.Xml.Serialization.XmlTypeAttribute(Namespace="http://example.org/")]
[System.Xml.Serialization.XmlRootAttribute("key", Namespace="http://example.org/", IsNullable=false)]
public class keyInfo {
        
    [System.Xml.Serialization.XmlAttributeAttribute()]
    public string version;
        
    [System.Xml.Serialization.XmlAttributeAttribute()]
    public bool @public;
}

基于通过前面的 C# 源代码编译得到的程序集生成的 XML 架构文档：

<xs:schema xmlns:tns="http://example.org/" elementFormDefault="qualified" targetNamespace="http://example.org/" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="key" type="tns:keyInfo" />
  <xs:complexType name="keyInfo">
    <xs:attribute name="version" type="xs:string" />
    <xs:attribute name="public" type="xs:boolean" />
  </xs:complexType>
</xs:schema>

在前面生成的 XML 架构中，version 属性（最初是全局声明的）已成为局部属性。

第二个示例演示当在一个单独的命名空间中定义某个全局属性时，Xsd.exe 如何处理对该属性的引用。此示例使用 <import> 元素导入另一个位于单独的 XSD 文件中的命名空间。（<import> 元素的 schemaLocation 属性不用于指定导入的 .xsd 文件的位置。对于 Xsd.exe 而言，该文件作为一个附加的命令行参数来指定。）

用作输入的顶级 XML 架构文档：

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" 
            xmlns="http://example.org/" targetNamespace="http://example.org/" xmlns:attr="http://example.org/attr">
  <xsd:import  namespace="http://example.org/attr" />
  <xsd:element name="key" type="keyInfo" />
  <xsd:complexType name="keyInfo">
    <xsd:attribute ref="attr:version" />
    <xsd:attribute name="public" type="xsd:boolean" use="required" />
  </xsd:complexType>
</xsd:schema>

用作输入的已导入 XML 架构文档：

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" 
            xmlns="http://example.org/attr" targetNamespace="http://example.org/attr">
  <xsd:attribute name="version" type="xsd:string" />
</xsd:schema>

基于前面的两个 XML 架构文档生成的 C# 类：

[System.Xml.Serialization.XmlTypeAttribute(Namespace="http://example.org/")]
[System.Xml.Serialization.XmlRootAttribute("key", Namespace="http://example.org/", IsNullable=false)]
public class keyInfo {
        
    [System.Xml.Serialization.XmlAttributeAttribute(Namespace="http://example.org/attr")]
    public string version;
        
    [System.Xml.Serialization.XmlAttributeAttribute()]
    public bool @public;
}

基于通过前面的 C# 源代码编译得到的程序集生成的顶级 XML 架构文档：

<xs:schema xmlns:tns="http://example.org/" elementFormDefault="qualified" targetNamespace="http://example.org/" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:import namespace="http://example.org/attr" />
  <xs:element name="key" type="tns:keyInfo" />
  <xs:complexType name="keyInfo">
    <xs:attribute xmlns:q1="http://example.org/attr" ref="q1:version" />
    <xs:attribute name="public" type="xs:boolean" />
  </xs:complexType>
</xs:schema>

基于通过前面的 C# 源代码编译得到的程序集生成的已导入 XML 架构文档：

<xs:schema xmlns:tns="http://example.org/attr" elementFormDefault="qualified" targetNamespace="http://example.org/attr" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:attribute name="version" type="xs:string" />
</xs:schema>

use 属性

<attribute> 声明的 use 属性确定该属性是可以出现在 XML 实例文档中，还是必须出现在 XML 实例文档中。

use 属性：从 XML 架构文档生成源代码

Xsd.exe 对于 use 属性的 optional 值的解释取决于是否已通过 default 属性指定了默认属性值。下面列出了 use 的可能值（包括 optional 和 default 组合）及其 Xsd.exe 输出：

required：Xsd.exe 生成一个具有 System.Xml.Serialization.XmlAttributeAttribute 的公共字段。
已指定 default 的 optional：Xsd.exe 生成一个公共字段，该字段具有 XmlAttributeAttribute 以及指定默认值的 System.Component.DefaultValueAttribute。
未指定 default 的 optional：Xsd.exe 生成一个具有 XmlAttributeAttribute 的公共字段。此外，如果该属性的类型不是引用类型（例如字符串），它会生成一个 bool 类型的公共字段，该字段的名称为该属性字段的名称再追加 Specified。例如，如果属性字段的名称为 startDate，则 bool 字段的名称将为 startDateSpecified。将某个对象序列化为 XML 时，XmlSerializer 类将检查 bool 字段的值，以确定是否写入可选的属性。出现的 bool 字段将具有 System.Xml.Serialization.XmlIgnoreAttribute，以防止它被 XmlSerializer 序列化。
prohibited：Xsd.exe 不生成任何内容。

use 属性：基于类生成 XML 架构文档

在下面两种情况的任一种下，Xsd.exe 不指定 use 属性，而是恢复为默认值 optional：

存在遵循 Specified 命名约定的额外公共 bool 字段。
通过 System.Component.DefaultValueAttribute 类型的属性为成员分配了默认值。

如果上述条件均得不到满足，则 Xsd.exe 将为 use 属性生成 required 值。

示例：use 属性

输入 XML 架构复杂类型：

<xsd:complexType name="Numbers">
  <xsd:attribute name="optionalNumber" type="xsd:int" use="optional"/>
  <xsd:attribute name="requiredNumber" type="xsd:int" use="required"/>
  <xsd:attribute name="prohibitedNumber" type="xsd:int" use="prohibited"/>
</xsd:complexType>

基于前面的复杂类型生成的 C# 类：

[System.Xml.Serialization.XmlTypeAttribute(Namespace="http://example.org/")]
[System.Xml.Serialization.XmlRootAttribute(Namespace="http://example.org/", IsNullable=false)]
public class Numbers {
        
    [System.Xml.Serialization.XmlAttributeAttribute()]
    public int optionalNumber;
        
    [System.Xml.Serialization.XmlIgnoreAttribute()]
    public bool optionalNumberSpecified;
        
    [System.Xml.Serialization.XmlAttributeAttribute()]
    public int requiredNumber;
}

基于前面的 C# 类生成的复杂类型实际上等同于原始复杂类型。

可能的属性	绑定支持
default	default 属性提供默认值，如果在收到实例文档时该元素为空或该属性不存在，将使用该默认值。当从 XML 架构生成源代码时，Xsd.exe 工具会提取与具有默认值的属性相对应的每个字段，应用 System.ComponentModel.DefaultValueAttribute，并将默认值作为参数传递。此外，Xsd.exe 还以静态方式将该字段初始化为默认值，如下面的示例所示： `[System.ComponentModel.DefaultValueAttribute(-1)] [System.Xml.Serialization.XmlAttributeAttribute()] public int age = -1;` 另外，当从架构生成源代码时，Xsd.exe 还检查是否已指定了 default 属性，以确定如何解释值为 `optional` 的 use 属性。有关完整说明，请参见 default 属性。 Xsd.exe 工具无法为具有默认值的列表类型属性生成有效的源代码。介绍 default 属性时对这一情况进行了说明。另请参见 <list> 元素。
fixed	对于 <attribute> 声明，Xsd.exe 使用 fixed 属性的值以静态方式将该字段初始化为固定值，如下面的示例所示： `[System.Xml.Serialization.XmlAttribute()] public in age = -1;` 请参见 fixed 属性。
form	Xsd.exe 工具将 <attribute> 元素的 form XML 属性 (Attribute) 等同于 XmlAttributeAttribute 的 Form 属性 (Property)。 .NET Framework 的 XML 序列化基础结构识别 XML 架构的默认值 `unqualified`。如果 XML 架构中的 <attribute> 声明指定 `form="qualified"`，则 Xsd.exe 会为对应的字段生成 XmlAttribute 属性，并为该属性传递属性参数 `Form=XmlSchemaForm.Qualified`。请参见 form 属性。
id	Xsd.exe 实用工具会忽略旨在提供唯一标识符的 id 属性。而改为识别 name 属性。
name	如果要从 XSD 文档生成源代码，则 name 属性的值提供表示该属性的公共类字段的名称。如果名称与保留的关键字冲突，则会生成一个带有符号 @ 前缀的名称。当 Xsd.exe 从某个公共类字段生成 <attribute> 声明时，会将该字段的名称用作 name 属性的值。通过 AttributeName 属性 (Property) 可以提供替代名称 - name 属性 (Attribute) 值。请参见 name 属性绑定支持属性。
ref	当从 XML 架构复杂类型生成 .NET Framework 类型时，除非全局属性是在该架构的目标命名空间之外的命名空间中声明的，否则 Xsd.exe 将无法区分出局部声明的属性和对全局声明的元素的引用。请参见同一命名空间内的引用和对另一个命名空间的引用部分。
type	Xsd.exe tool 工具将使用 < attribute> 和 <element> 声明的 type 属性引用的数据类型与 .NET Framework 类型关联。除非某个 XML 架构数据类型可以追溯到通过 type 属性引用某个数据类型的全局元素声明，否则 Xsd.exe 不会为该 XML 架构数据类型生成 .NET Framework 类型。
use	如果 `use=“optional”`，则 Xsd.exe 会检查 default 属性是否存在，以确定是生成 DefaultValueAttribute 还是生成额外的 –Specified 字段。对于引用类型（例如字符串），不生成额外字段。对于公共字段而言，如果两者都不存在，则会导致 Xsd.exe 在所生成的 XSD 文档中指定 `use=“required”`。请参见前面的“use 属性”一节。