MaxOccurs 屬性繫結支援

發行項
02/28/2011

本主題專門說明舊有技術。應該使用下列建立 XML Web Service 及 XML Web Service 用戶端： Windows Communication Foundation.

.NET Framework 會提供 maxOccurs 屬性的部分繫結支援。

就大部分可能會指定 maxOccurs 屬性的項目而言，Xsd.exe 會將 0 值解譯為 1，並產生非陣列欄位，而會將大於 1 的值解譯為 unbounded，並產生陣列欄位。行為會因項目而有所不同。

說明

maxOccurs 和 minOccurs 屬性會約束所指定實體 (Entity) 可以連續出現在 XML 執行個體文件中對應位置上的次數。

這些屬性只會出現在複雜型別定義中。因此，若要讓 <element> 或 <group> 項目具備這些屬性，這些項目就必須是區域宣告或是全域宣告的參考，而非全域宣告本身。

至於具有 XML 結構描述複雜型別的繫結類別，.NET Framework 沒有提供相當於 maxOccurs 或 minOccurs 的程式語言功能。

從 XML 結構描述文件產生原始程式碼，或是執行反向轉譯時，Xsd.exe 解譯 maxOccurs 屬性的方式會因屬性出現於何種 XML 結構描述定義語言項目中而有所不同。下列表格會依項目說明解譯方式：

項目	解譯
<element>	可能的值： `1`：Xsd.exe 會產生欄位，這個欄位的型別會對應到項目的資料型別。 `0`：Xsd.exe 無法處理為 `0` 的值，而會將此值視為預設值 `1`。 `unbounded`：Xsd.exe 會產生一個欄位，這個欄位是一個型別對應至項目資料型別的陣列。對於大於 1 的整數：如同和 `unbounded` 值的處理方式一般，Xsd.exe 會產生一個欄位，這個欄位是一個型別對應至項目資料型別的陣列。您可以使用 XmlValidatingReader 類別，比對 SOM 所表示的 XML 結構描述文件，驗證 XML 文件，藉此強制值大於 1。
<group>	對 <group> 項目而言，Xsd.exe 會將 `0` 的 maxOccurs 值解譯為 `1`，而將大於 `1` 的 maxOccurs 值解譯為 unbounded。但是，Xsd.exe 預設會將 <group> 項目的 `maxOccurs="unbounded"` 值視為已使用 `maxOccurs="unbounded"` 指定的每個子項目。例如，如果 <group> 項目的每個子項目都是 <element> 項目，則在結果類別中產生的每個欄位就是適當型別的陣列。為了正確匯入包含 maxOccurs 大於 `1` 之群組的結構描述，建議您在 Xsd.exe 中使用 /order 命令列選項。使用這個選項時，會將整個群組當做套用多個 XmlElementAttribute 屬性 (群組中的每個項目各套用一個) 的單一陣列匯入。陣列的型別是由項目型別所決定，且型別會是可指派給所有項目之衍生最多的型別。也就是說，如果群組包含同樣都是衍生自 TypeBase 的 Type1 和 Type2 型別項目，則陣列也會是 TypeBase 型別。如果沒有通用的基底型別 (Base Type)，則陣列將會是 Object 型別。如需相關範例，請參閱本主題下方的 <sequence> 範例。
<all>	`1` 以外的任何 maxOccurs 屬性值都是無效的。Xsd.exe 會回報出現無效值的錯誤。
<any>	可能的值`:` `1`：Xsd.exe 會產生具有 System.Xml.Serialization.XmlAnyElementAttribute 屬性、且型別為 System.Xml.XmlElement 的欄位。此屬性允許類別表示任意 XML 項目，而不會將這些項目繫結至其他可能類別成員所識別的非 XML 型別。 `0`：Xsd.exe 無法處理為 `0` 的值，而會將此值視為預設值 `1`。 `unbounded`：Xsd.exe 會產生具有 XmlAnyElement 屬性的 XmlElement 陣列。大於 1 的整數：對於 `unbounded` 值，Xsd.exe 會產生具有 XmlAnyElement 屬性的 XmlElement 陣列。您可以使用 XmlValidatingReader 類別，比對 SOM 所表示的 XML 結構描述文件，驗證 XML 文件，藉此強制值大於 1。
<choice>	<choice> 項目含有兩個或多個子項目，每一個都代表一個項目或項目群組。這表示在指定的執行個體文件中，那些實體中只有一個會出現在指定的位置。choice 必須依項目名稱來區分；或者，也可以依型別區分，若是群組，則可以依號碼來區分。如需詳細資訊，請參閱 <choice> 項目。對於 <choice> 項目，如果是 <element> 和 <any> 項目，Xsd.exe 會將 `0` 的 maxOccurs 值解譯為 `1`，而將大於 1 的 maxOccurs 值解譯為 `unbounded`。若是 `1` 值，Xsd.exe 會產生一般型別或一般基底型別的欄位。對於每個 choice，會將型別為 XmlElementAttribute 的屬性套用至欄位。如果 choice 並非依型別來區分，Xsd.exe 就會產生型別為 XmlChoiceIdentifierAttribute 的屬性，使用代表每個 choice 的列舉型別來指定第二個欄位。這個機制的詳細說明及範例隨附於 <choice> 項目。若為 `unbounded` 值，Xsd.exe 會執行相同的繫結，但是為 choice 所產生的欄位會是適當型別的陣列。如果所有的 choice 都具有相同的型別，則第二個欄位 (由 XmlChoiceIdentifier 屬性所識別) 就會是所產生之列舉型別的陣列。第二個陣列中的每個項目會為第一個陣列中對應的項目選擇項目名稱。
<sequence>	就 <sequence> 項目而言，情況正如上述大部分項目，Xsd.exe 會將 `0` 的 maxOccurs 值解譯為 `1`，而將大於 1 的 maxOccurs 值解譯為 `unbounded`。但是，Xsd.exe 會將 <sequence> 項目的 `maxOccurs="unbounded"` 值視為是使用 `maxOccurs="unbounded"` 指定了每個子項目。例如，如果 <sequence> 項目的每個子項目都是 <element> 項目，則在隨後的類別中產生的每個欄位就是適當型別的陣列。如果 Xsd.exe 執行反向解譯至新的 XSD 文件，可能會將此欄位結構繫結至 `<sequence maxOccurs="1">` 項目，該項目含有指定數目的 `<element maxOccurs="unbounded">` 項目。套用的 XmlElementAttribute 屬性，群組中的每個項目都套用一個屬性。陣列的型別是由項目型別所決定，且型別會是可指派給所有項目之衍生最多的型別。也就是說，如果群組包含同樣都是衍生自 TypeBase 的 Type1 和 Type2 型別項目，則陣列也會是 TypeBase 型別。如果沒有通用的基底型別 (Base Type)，則陣列將會是 Object 型別。如需相關範例，請參閱本主題下方的 <sequence> 範例。

從組件中的一組類別產生 XML 結構描述文件時，Xsd.exe 會還原之前執行的轉換，從單一執行個體產生值為 1 的 maxOccurs，並從陣列產生值為 unbounded 的 maxOccurs。

Xsd.exe 會將值為 unbounded 的 maxOccurs 繫結至陣列，而將值為 1 的 maxOccurs 繫結至陣列中所指定的父項目 (如果有的話)。

如果將預設的 System.Xml.Serialization.XmlArrayAttribute 套用至陣列，就會建立名稱開頭為 ArrayOf 的結構描述資料型別，以表示陣列的父項目。但是，如果改為將 System.Xml.Serialization.XmlElementAttribute 套用至陣列，陣列項目會出現在執行個體文件中，當做是繫結至類別之項目的子系。如需陣列繫結的詳細資訊，請參閱使用屬性控制 XML 序列化。

更多陣列繫結的相關資訊： 若要了解如何將大於 1 的值轉譯至陣列，請想一想宣告特定型別的物件與指派值 (也就是堆疊或堆積中的記憶體位置) 給該物件兩者之間的差異。從下列 XSD 項目開始：

<xsd:element minOccurs="5" maxOccurs="5" name="items" type="xsd:token" />

如果手動撰寫程式碼，就不會在型別宣告上表示五個陣列大小，宣告會是：public string[] items。但是，如果指定值，則會表示該陣列大小：items = new string[5]。

Xsd.exe 可從 XML 結構描述產生的原始程式碼，就只有型別和欄位宣告以及中繼資料，此中繼資料可以套用至型別和欄位做為屬性。指派值至物件已超出範圍。

您可以使用 XmlValidatingReader 類別，對照結構描述物件模型 (SOM) 所表示的 XML 結構描述文件，驗證 XML 文件，藉此強制值大於 1。SOM 使用 System.Xml.Schema.XmlSchemaParticle.MaxOccurs 和 System.Xml.Schema.XmlSchemaParticle.MaxOccursString 屬性 (Property)，這兩個屬性 (Property) 會套用至所有可能含有 maxOccurs 屬性 (Attribute) 的項目。

Example

在複雜型別定義中找到的輸入 XML 結構描述 <choice> 項目：

<xsd:choice maxOccurs="unbounded">
    <xsd:element name="stringA" type="xsd:string"/>
    <xsd:element name="stringB" type="xsd:string"/>
</xsd:choice>

先前 XML 結構描述文件所產生之 C# 類別的相關事件，加上代表項目選擇的列舉型別 (假設目標命名空間為 http://example.org/)：

    [System.Xml.Serialization.XmlElementAttribute("stringA", typeof(string))]
    [System.Xml.Serialization.XmlElementAttribute("stringB", typeof(string))]
    [System.Xml.Serialization.XmlChoiceIdentifierAttribute("ItemsElementName")]
    public string[] Items;
        
    [System.Xml.Serialization.XmlElementAttribute("ItemsElementName")]
    [System.Xml.Serialization.XmlIgnoreAttribute()]
    public ItemsChoiceType[] ItemsElementName;
...
[System.Xml.Serialization.XmlTypeAttribute(Namespace="http://example.org/", IncludeInSchema=false)]
public enum ItemsChoiceType {
    stringA,
    stringB,
}

由類別產生的複雜型別會有效等同於原始複雜型別，該類別由前面的 C# 原始程式碼所編譯。

<sequence>

Example

輸入 XML 結構描述文件，其中包含 maxOccurs 大於 1 的序列：

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
      xmlns="http://example.org/" targetNamespace="http://example.org/" elementFormDefault="qualified">
  <xsd:element name="ComplexInstance">
   <xsd:complexType>
     <xsd:sequence maxOccurs="unbounded">
       <xsd:element name="Field1" type="xsd:token"/>
       <xsd:element name="Field2" type="xsd:int" />
     </xsd:sequence>
   </xsd:complexType>
  </xsd:element>
</xsd:schema>

不需使用任何命令列選項，即可從前述之 XML 結構描述文件產生 C# 類別：

[System.Xml.Serialization.XmlTypeAttribute(Namespace="http://example.org/")]
[System.Xml.Serialization.XmlRootAttribute(Namespace="http://example.org/", IsNullable=false)]
public class ComplexInstance {        
    [System.Xml.Serialization.XmlElementAttribute("Field1", DataType="token")]
    public string[] Field1;
        
    [System.Xml.Serialization.XmlElementAttribute("Field2")]
    public int[] Field2;
}

從前面 C# 原始程式所編譯的組件產生的 XML 結構描述複雜型別：

<xs:complexType name="ComplexInstance">
  <xs:sequence>
    <xs:element minOccurs="0" maxOccurs="unbounded" name="Field1" type="xs:token" />
    <xs:element minOccurs="0" maxOccurs="unbounded" name="Field2" type="xs:int" />
  </xs:sequence>
</xs:complexType>

如您所見，產生的結構描述與原來的結構描述並不相同。若要正確地匯入序列的 maxOccurs 大於 1 的結構描述，請使用會產生下列結果的 /order 命令列選項：

[System.Xml.Serialization.XmlTypeAttribute

(Namespace="http://example.org/")]

[System.Xml.Serialization.XmlRootAttribute

(Namespace="http://example.org/", IsNullable=false)]

public partial class ComplexInstance

{

/// <remarks/>

[System.Xml.Serialization.XmlElementAttribute

("Field1", typeof(string), DataType="token", Order=0)]

[System.Xml.Serialization.XmlElementAttribute("Field2",

typeof(int), Order=0)]

public object[] Items;

}

可能的包含項目：<all>、<any>、<choice>、<element>、<group>、<sequence>

另請參閱

參考

System.Xml.Schema.XmlSchemaParticle.MaxOccurs
System.Xml.Schema.XmlSchemaParticle.MaxOccursString
XmlSchemaAll
XmlSchemaAny
XmlSchemaChoice
XmlSchemaElement
XmlSchemaGroupRef
XmlSchemaSequence

共用方式為

MaxOccurs 屬性繫結支援

說明

<sequence>

另請參閱

參考

其他資源