attribute 元素绑定支持

2011-02-28

本主题专门介绍一项旧有技术。现在应通过使用以下链接来创建 XML Web 服务和 XML Web 服务客户端： Windows Communication Foundation.

.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 特性的 Namespace 属性来指定该命名空间。对于该特定元素，通过 Namespace 属性指定的命名空间重写使用 XmlTypeAttribute 特性和 XmlRootAttribute（可选）在类级别指定的命名空间。下面是一个示例：

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

public string Key;

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

Example

第一个示例演示当在包含对某个全局特性的引用的同一个目标命名空间中定义该特性时，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 特性等同于 XmlAttributeAttribute 的 Form 属性。.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 属性可以提供替代名称 - name 特性值。请参见 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 特性”一节。

可能的父元素：<attributeGroup>、<complexType>、<extension>、<restriction>、<schema>

可能的子元素：<annotation>、<simpleType>

另请参见

参考

XmlSchemaAttribute

通过