Supporto dell'associazione all'attributo MinOccurs

Questo argomento è specifico di una tecnologia legacy. Servizi Web XML e client di servizi Web XML devono essere creati attualmente tramite Windows Communication Foundation.

In .NET Framework è incluso un supporto parziale per l'associazione all'attributo minOccurs.

Solo per l'elemento <element> Xsd.exe controlla il valore dell'attributo minOccurs e solo se il valore dell'attributo Supporto dell'associazione all'attributo MaxOccurs non impone un campo matrice. Il valore viene quindi interpretato o prodotto in base a diversi fattori, a partire dalla presenza o meno di un tipo di riferimento o di valore nel campo corrispondente.

Descrizione

Gli attributi minOccurs e maxOccurs limitano il numero di volte in cui è possibile visualizzare in successione l'entità specificata nella posizione corrispondente in un documento di istanza XML.

Questi attributi vengono visualizzati solo all'interno delle definizioni dei tipi complessi. Pertanto, se si desidera associare questi attributi a un elemento <element> o <group>, è necessario che l'elemento sia una dichiarazione locale o un riferimento a una dichiarazione globale e non la dichiarazione globale stessa.

Per l'associazione dei tipi complessi di XML Schema, con classi non specifiche di XML, .NET Framework non dispone di un linguaggio di programmazione diretta equivalente all'attributo minOccurs o maxOccurs.

Conversione di XSD nel codice sorgente

Durante la generazione di codice sorgente da un documento XML Schema, Xsd.exe ignora l'attributo minOccurs applicato agli elementi <choice>, <sequence>, <group>, <all> e <any>.

Per l'elemento**<element>**, Xsd.exe ignora l'attributo minOccurs se il valore dell'attributo maxOccurs è maggiore di 1 oppure unbounded. In questo caso lo strumento produce una matrice del tipo corrispondente al tipo di dati XSD. Xsd.exe utilizza il valore dell'attributo maxOccurs per stabilire se produrre un'istanza singola o una matrice.

Per l'elemento <element>, Xsd.exe ignora anche l'attributo minOccurs se applicato a un tipo di dati dello schema che viene convertito in un tipo di riferimento .NET Framework.

Solo nel caso in cui si verificano tutte le condizioni, Xsd.exe utilizza il valore dell'attributo minOccurs:

• L'elemento <element> è coinvolto.

• L'attributo maxOccurs impone un'istanza singola.

• Il tipo di dati viene convertito in un tipo di valore.

Lo strumento interpreta il valore nel modo seguente:

• 1 or more: Xsd.exe genera un campo pubblico. Non viene applicato alcun attributo correlato a XML, pertanto viene utilizzato l'attributo predefinito System.Xml.Serialization.XmlElementAttribute.

• 0: Xsd.exe genera un campo pubblico. Non viene applicato alcun attributo correlato a XML, pertanto viene utilizzato l'attributo predefinito XmlElementAttribute. Xsd.exe genera, inoltre, un campo pubblico del tipo bool il cui nome è quello del campo dell'elemento, cui viene aggiunto Specified. Se, ad esempio, il nome del campo dell'elemento è startDate, il nome del campo bool diventa startDateSpecified. Quando si esegue la serializzazione di un oggetto in XML, la classe XmlSerializer controlla il valore del campo bool per stabilire se scrivere l'elemento. Il campo bool appare con un System.Xml.Serialization.XmlIgnoreAttribute per impedirne la serializzazione da XmlSerializer.

Ulteriori informazioni sulle associazioni di matrici. Quando Xsd.exe ignora l'attributo minOccurs, si verifica una perdita nella precisione della definizione se il valore dell'attributo maxOccurs impone un'associazione di matrici. Una conversione inversa dalla matrice generata in una nuova dichiarazione <element> non produce il valore minOccurs originale, bensì un valore pari a 0, cui si aggiunge un valore di maxOccurs pari a unbounded.

Per comprendere l'associazione dei tipi a una matrice, è necessario tenere presente la differenza tra la dichiarazione di un oggetto di un determinato tipo e l'assegnazione di un valore (letteralmente una posizione di memoria nello stack o nell'heap) a tale oggetto. È possibile iniziare con l'elemento XSD seguente:

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

Durante la scrittura manuale del codice, non è consigliabile esprimere la dimensione della matrice pari a cinque nella dichiarazione del tipo seguente: public string[] items. Tale dimensione può invece essere espressa durante l'assegnazione di un valore: items = new string[5].

Gli unici tipi di codice sorgente che Xsd.exe genera da uno schema XML sono le dichiarazione di tipi e di campi e i metadati che possono essere applicati ai tipi e ai campi come attributi. L'assegnazione dei valori agli oggetti si estende oltre tale ambito.

Per imporre un valore maggiore di 1 è necessario convalidare un documento XML con la classe XmlValidatingReader in base a un documento XML Schema rappresentato dal modello SOM (Schema Object Model). Il modello SOM utilizza le proprietà System.Xml.Schema.XmlSchemaParticle.MinOccurs e System.Xml.Schema.XmlSchemaParticle.MinOccursString, entrambe applicabili a tutti gli elementi che possono contenere un attributo minOccurs.

Per ulteriori informazioni sulla modalità con cui Xsd.exe gestisce i vincoli di occorrenza in diversi elementi del linguaggio XSD (XML Schema Definition), vedere l'attributo maxOccurs.

Conversione del codice sorgente in XSD

Il valore minOccurs prodotto da Xsd.exe durante la generazione di un documento XML Schema dalle classi dipende dall'elemento contenitore del linguaggio XSD generato. Di seguito è riportato un elenco degli elementi contenitore possibili con il rispettivo comportamento minOccurs.

<choice>: 1 se la scelta rappresenta un singolo oggetto, 0 se la scelta rappresenta una matrice.

<sequence>: non specificato, viene ripristinato il valore predefinito 1.

<group>: Xsd.exe non genera un elemento <group> dal codice sorgente.

<all>: Xsd.exe non genera un elemento <all> dal codice sorgente.

<any>: 0 secondo le regole illustrate per l'elemento <element>. L'elemento <any> verrà descritto più avanti in questo argomento.

<element>: Xsd.exe produce valori diversi per minOccurs a seconda se un campo o una proprietà è una matrice o un'istanza singola, se ha un tipo di valore o un tipo di riferimento, se un tipo di valore ha un valore predefinito o un campo supplementare che indica se è stato specificato un valore, nonché a seconda se a un tipo di riferimento viene assegnato un attributo relativo a XML con una proprietà IsNullable impostata su true.

La proprietà IsNullable viene utilizzata da determinate classi di attributi relative a XML. La proprietà viene visualizzata nel modo seguente:

• System.Xml.Serialization.XmlElementAttribute.IsNullable

• System.Xml.Serialization.XmlRootAttribute.IsNullable

• System.Xml.Serialization.XmlArrayAttribute.IsNullable

• System.Xml.Serialization.XmlArrayItemAttribute.IsNullable

Se la proprietà IsNullable di un membro di una classe è impostata su true e un oggetto è stato impostato su un riferimento null (Nothing in Visual Basic), la classe XmlSerializer genera un attributo xsi:nil con un valore true. (Il prefisso xsi viene utilizzato per lo spazio dei nomi dell'istanza XML Schema http://www.w3.org/2001/XMLSchema-instance).

La presenza di xsi:nil="true" in un elemento all'interno di un documento di istanza dichiara in modo esplicito che l'elemento non ha contenuto, sia che si tratti di elementi figlio sia di testo del corpo. Vedere l'attributo xsi:nil.

La proprietà IsNullable corrisponde all'attributo nillable nel linguaggio XSD (XML Schema Definition Language). Se, durante la generazione di definizioni XSD dalle classi, Xsd.exe rileva la presenza di un valore true per una proprietà IsNullable di una classe o di un membro, e al tipo è possibile assegnare un riferimento null, viene generata un'impostazione nillable="true" per l'elemento XSD <element> corrispondente. Vedere l'attributo nillable.

Le regole illustrate nella tabella riportata di seguito stabiliscono il valore dell'attributo minOccurs corrispondente a un membro di classe costituito da un'istanza singola. Anche per le matrici valgono le stesse regole, con un'unica eccezione, descritta più avanti in questo argomento. La tabella è organizzata in base alle variazioni rilevanti dei membri di classe, insieme ai valori minOccurs risultanti:

Membro di classe di input	valore minOccurs dell’elemento di output <element>
Tipo di valore con un valore predefinito specificato mediante un attributo System.Component.DefaultValueAttribute.	0. Nell'elemento <element>, il valore predefinito viene specificato anche mediante l'attributo XML default.
Tipo di valore a cui si associa un campo pubblico bool che utilizza la convenzione di denominazione Specified descritta precedentemente in Conversione di XSD nel codice sorgente.	0.
Tipo di valore senza valore predefinito o campo booleano associato.	1.
Tipo di riferimento con la proprietà IsNullable di un attributo XmlElement impostata su true.	1. Nell'elemento <element>, anche l'attributo nillable è impostato su true.
Tipo di riferimento con IsNullable=false o con nessuna impostazione per IsNullable.	0.

Xsd.exe conserva queste funzionalità di distinzione in una conversione inversa da un documento XML Schema al codice sorgente.

Nota: se un attributo default XML si presenta con l'attributo minOccurs impostato su 0, e il tipo di dati viene mappato a un tipo di valore, verrà generato solo l'attributo DefaultValue. Il campo booleano associato non verrà generato. Vedere anche l'attributo default.

Si supponga, ad esempio, che nel file di origine di input venga rilevato l'elemento seguente:

<xsd:element name="birthdate" type="xsd:date" default="2002-03-04" minOccurs="0" />Xsd.exe would then produce: 
[System.Xml.Serialization.XmlElementAttribute(DataType="date")]
[System.ComponentModel.DefaultValueAttribute(typeof(System.DateTime), "2002-03-04")]
public System.DateTime birthdate = new System.DateTime(631507968000000000);

Associazioni di matrici. Xsd.exe produce sempre una dichiarazione <element> con il formato riportato di seguito per le matrici.

<element minOccurs="0" maxOccurs="unbounded" />

Ciò è reso possibile dal fatto che i tipi di matrici sono tipi di riferimento. A differenza degli altri tipi di riferimento, tuttavia, ciò è reso possibile anche se al membro della matrice viene applicata la dichiarazione di attributo seguente:

[XmlElementAttribute(IsNullable=true)]

Quando viene applicato un attributo XmlElement, anziché l’attributo predefinito XmlArrayAttribute, a una matrice, gli elementi della matrice vengono visualizzati in un documento di istanza come figli dell'elemento associato alla classe. Non vengono introdotti altri elementi che fungano esclusivamente da elementi padre degli elementi della matrice. Xsd.exe riconosce l'impostazione IsNullable=true producendo un elemento con nillable="true", tuttavia viene comunque generato un valore di minOccurs pari a 0 ed è possibile che gli elementi della matrice siano comunque assenti.

Se viene applicato l'attributo XmlArray predefinito, viene creato un tipo di dati dello schema, il cui nome inizia con ArrayOf, che rappresenta l'elemento padre della matrice. Per ulteriori informazioni sulle associazioni di matrici, vedere l'attributo maxOccurs e Controllo della serializzazione XML mediante attributi.

Il tipo di dati dello schema degli elementi padre corrisponde a un tipo di riferimento e come tale viene considerato da Xsd.exe nella generazione di un valore minOccurs. In altri termini, viene generato un valore minOccurs pari a 1 se la proprietà IsNullable è impostata su true, come descritto di seguito:

[System.Xml.Serialization.XmlArrayAttribute(IsNullable=true)]

In caso contrario, viene generato un valore minOccurs pari a 0.

elemento <any>. Il motivo per cui Xsd.exe genera minOccurs="0" per un elemento <any>, indipendentemente dall'interessamento di un oggetto singolo o di una matrice, è che il costrutto di codice equivalente è un tipo di riferimento. Tale costrutto è un campo del tipo System.Xml.XmlElement (o una matrice dello stesso tipo), con un attributo System.Xml.Serialization.XmlAnyElementAttribute. È possibile applicare una dichiarazione di attributo, [XmlElementAttribute(IsNullable=true)], all'oggetto o alla matrice XmlElement, ma Xsd.exe non interpreta questa sintassi come elemento <any> con minOccurs="1".

Elementi contenitore possibili: <all>, <any>, <choice>, <element>, <group>, <sequence>

Vedere anche

Riferimento

System.Xml.Schema.XmlSchemaParticle.MinOccurs
System.Xml.Schema.XmlSchemaParticle.MinOccursString
XmlSchemaAll
XmlSchemaAny
XmlSchemaChoice
XmlSchemaElement
XmlSchemaGroupRef
XmlSchemaSequence