Compatibilidad con enlaces del atributo MinOccurs

Este tema es específico de una tecnología heredada. Ahora, los servicios Web XML y los clientes de servicios Web XML deben crearse con Windows Communication Foundation.

.NET Framework proporciona compatibilidad de enlace parcial para el atributo minOccurs.

Xsd.exe solo comprueba el valor del atributo minOccurs para el elemento <element>, y únicamente si el valor del atributo Compatibilidad con enlaces del atributo MaxOccurs no dicta ningún campo de matriz. Después, el valor se interpreta (o se genera) con arreglo a distintos factores, empezando por si el campo correspondiente tiene un tipo de valor o de referencia.

Explicación

Los atributos minOccurs y maxOccurs restringen el número de veces que puede aparecer sucesivamente la entidad especificada en la posición correspondiente de un documento XML de instancia.

Estos atributos solo aparecen en definiciones de tipo complejo. Por lo tanto, para elementos <element> o <group>, el elemento debe ser una declaración local o una referencia a una declaración global, no la propia declaración global.

Para enlazar tipos de esquema XML complejos con clases no específicas de XML, .NET Framework no proporciona ningún lenguaje de programación directo equivalente a los atributos minOccurs o maxOccurs.

Convertir XSD en código fuente

Al generar código fuente a partir de un documento de esquema XML, Xsd.exe omite el atributo minOccurs aplicado a los elementos <choice>, <sequence>, <group>, <all> y <any>.

Por lo que respecta al elemento <element>, Xsd.exe omite el atributo minOccurs si el valor del atributo maxOccurs es mayor que 1 o unbounded. En este caso, la herramienta genera una matriz del tipo que corresponde al tipo de datos XSD. Xsd.exe utiliza el valor del atributo maxOccurs para determinar si debe generar una instancia única o una matriz.

Por lo que respecta al elemento <element>, Xsd.exe también omite el atributo minOccurs si se aplica a un tipo de datos de esquema que realiza una conversión a un tipo .NET Framework de referencia.

Xsd.exe solo usa el valor del atributo minOccurs cuando se cumplen todas las condiciones siguientes:

• El elemento <element> está implicado.

• El atributo maxOccurs dicta una instancia única.

• El tipo de datos se convierte en un tipo de valor.

La herramienta interpreta el valor del siguiente modo:

• 1 or more: Xsd.exe genera un campo público. No se aplica ningún atributo relacionado con XML, por lo que se usa el valor System.Xml.Serialization.XmlElementAttribute predeterminado.

• 0: Xsd.exe genera un campo público. No se aplica ningún atributo relacionado con XML; por tanto, se usa el valor predeterminado XmlElementAttribute. Además, Xsd.exe genera un campo público de tipo bool cuyo nombre es el nombre del campo del elemento al que se anexa Specified. Por ejemplo, si el nombre del campo del elemento es startDate, el nombre del campo bool pasa a ser startDateSpecified. Al serializar un objeto a XML, la clase XmlSerializer comprueba el valor del campo bool para determinar si debe escribir el elemento. El campo bool aparece con System.Xml.Serialization.XmlIgnoreAttribute para evitar que XmlSerializer lo serialice.

Información adicional sobre los enlaces de matriz. Se pierde precisión en la definición cuando Xsd.exe omite el atributo minOccurs en el caso de que el valor del atributo maxOccurs dicte un enlace de matriz. Una conversión inversa de la matriz generada en una nueva declaración de <element> no genera el valor de minOccurs original, sino un valor 0 y un valor para maxOccurs de unbounded.

Para comprender el enlace de tipos a una matriz, considere la diferencia entre declarar un objeto de un tipo determinado y asignar un valor (literalmente, una ubicación de memoria en la pila o el montón) a ese objeto. Empiece por el siguiente elemento XSD:

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

Si escribiera el código manualmente, no expresaría el tamaño de la matriz de cinco en la declaración de tipos, que sería: public string[] items. En su lugar, expresaría el tamaño de la matriz al asignar un valor: items = new string[5].

Las únicas clases de código fuente que genera Xsd.exe a partir de un esquema son declaraciones de tipos y campos, así como metadatos que se pueden aplicar a tipos y campos como atributos. La asignación de valores a objetos supera dicho ámbito.

Para exigir un valor mayor que 1 se puede validar un documento XML con la clase XmlValidatingReader respecto a un documento de esquema XML representado por el Modelo de objetos de esquemas (SOM). Dicho modelo utiliza las propiedades System.Xml.Schema.XmlSchemaParticle.MinOccurs y las propiedades System.Xml.Schema.XmlSchemaParticle.MinOccursString; estas dos clases se aplican a todos los elementos que pueden incluir un atributo minOccurs.

Para obtener más información sobre cómo controla Xsd.exe las restricciones de aparición en distintos elementos de lenguaje de definición de esquemas XML, vea el atributo maxOccurs.

Convertir código fuente a XSD

El valor de minOccurs que Xsd.exe genera al crear un documento de esquema XML a partir de clases depende del elemento contenedor del lenguaje de definición de esquemas XML generado. A continuación se muestran los posibles elementos contenedores, junto con su comportamiento con relación a minOccurs:

<choice>: 1 si la opción representa un solo objeto, 0 si la opción representa una matriz.

<sequence>: no se especifica, recupera el valor predeterminado 1.

<group>: Xsd.exe no genera ningún elemento <group> a partir del código fuente.

<all>: Xsd.exe no genera ningún elemento <all> a partir del código fuente.

<any>: 0 según las reglas explicadas para el elemento <element>. El elemento <any> se describe más adelante en este tema.

<element>: Xsd.exe genera distintos valores para minOccurs, que dependen de si un campo o una propiedad son una matriz o una instancia única; si un campo o una propiedad tienen un tipo de valor o de referencia; si un tipo de valor tiene un valor predeterminado o un campo adicional que indica si se ha especificado un valor; y si se ha asignado a un tipo de referencia un atributo relacionado con XML con una propiedad IsNullable establecida en true.

Algunas clases de atributos relacionados con XML usan la propiedad IsNullable. La propiedad aparece de la siguiente forma:

• System.Xml.Serialization.XmlElementAttribute.IsNullable

• System.Xml.Serialization.XmlRootAttribute.IsNullable

• System.Xml.Serialization.XmlArrayAttribute.IsNullable

• System.Xml.Serialization.XmlArrayItemAttribute.IsNullable

Si una propiedad IsNullable de un miembro de clase se establece en true y se ha establecido un objeto como referencia null (Nothing en Visual Basic), la clase XmlSerializer genera un atributo xsi:nil con un valor true. (El prefijo xsi se utiliza para el espacio de nombres de la instancia XML Schema, http://www.w3.org/2001/XMLSchema-instance).

La presencia de xsi:nil="true" en un elemento en un documento de instancia indica explícitamente que el elemento no tiene contenido, ya se trate de elementos secundarios o de texto principal. Consulte el atributo xsi:nil.

La propiedad IsNullable corresponde al atributo nillable en el lenguaje de definición de esquemas XML. Si, durante la generación de definiciones XSD a partir de clases, Xsd.exe busca un valor true para una propiedad IsNullable del miembro o la clase (y se puede asignar una referencia nula al tipo), se genera una configuración nillable="true" para el elemento <element> XSD correspondiente. Consulte el atributo nillable.

Las reglas que se muestran en la tabla siguiente determinan el valor del atributo minOccurs correspondiente a un miembro de clase que es una instancia única. Las matrices también siguen estas reglas, con una excepción que se describe más adelante en este tema. La tabla se organiza según las variaciones de miembro de clase pertinentes, junto con los valores de minOccurs resultantes:

Miembro de clase de entrada	Valor de minOccurs resultante del elemento <element>
Tipo de valor con un valor predeterminado especificado a través de un atributo System.Component.DefaultValueAttribute.	0. En el elemento <element>, el valor predeterminado también se especifica a través del atributo XML default.
Tipo de valor acompañado por un campo bool público que utiliza la convención de nomenclatura Specified descrita anteriormente en Convertir XSD en código fuente.	0.
Tipo de valor sin valor predeterminado o campo booleano acompañante.	1.
Tipo de referencia con una propiedad IsNullable de un atributo XmlElement establecida en true.	1. En el elemento <element>, el atributo nillable también se establece en true.
Tipo de referencia con IsNullable=false o sin configuración IsNullable.	0.

Xsd.exe conserva estas características distintivas en una conversión inversa de un documento de esquema XML a código fuente.

Nota: si aparece un atributo XML default con un atributo minOccurs establecido en 0 (y el tipo de datos se asigna a un tipo de valor), solo se genera el atributo DefaultValue. No ocurre así con el campo booleano acompañante. Consulte también el atributo default.

Por ejemplo, suponga que se encontró el elemento siguiente en el archivo de código fuente de entrada:

<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);

Enlaces de matriz. Xsd.exe siempre genera una declaración de <element> con el siguiente formato para las matrices.

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

Esto obedece a que los tipos de matriz son tipos de referencia. Sin embargo, a diferencia de lo que ocurre con otros tipos de referencia, también se da cuando se aplica la siguiente declaración de atributos al miembro de matriz:

[XmlElementAttribute(IsNullable=true)]

Cuando se aplica un atributo XmlElement en vez del atributo XmlArrayAttribute predeterminado a una matriz, los elementos de la matriz aparecerán en un documento de instancia como elementos secundarios del elemento que se enlaza a la clase. No hay ningún elemento adicional especificado estrictamente para actuar como elemento primario de los elementos de la matriz. Si bien Xsd.exe reconoce la configuración IsNullable=true mediante la generación de un elemento con nillable="true", se genera un valor 0 para minOccurs y aun así pueden estar ausentes los elementos de la matriz.

Si se aplica el atributo XmlArray predeterminado, se crea un tipo de datos de esquema, con un nombre que empieza por ArrayOf, para representar el elemento primario de la matriz. Para obtener más información sobre enlaces de matriz, consulte el atributo maxOccurs, y también Controlar la serialización XML mediante atributos.

El tipo de datos de esquema de los elementos primarios corresponde a un tipo de referencia y Xsd.exe lo trata como tal cuando genera un valor de minOccurs. Es decir, se genera un valor para minOccurs de 1 si la propiedad IsNullable se establece en true como se indica a continuación:

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

En caso contrario, se genera un valor para minOccurs de 0.

Elemento <any>. El motivo por el que Xsd.exe genera minOccurs="0" para un elemento <any> (independientemente de si está implicado un objeto o una matriz únicos) es que la construcción de código equivalente es un tipo de referencia. Esa construcción es un campo de tipo System.Xml.XmlElement (o una matriz), con un atributo System.Xml.Serialization.XmlAnyElementAttribute. Se podría aplicar una declaración de atributo, [XmlElementAttribute(IsNullable=true)], al objeto XmlElement o a la matriz, pero Xsd.exe no interpreta este uso como elemento <any> con minOccurs="1".

Posibles elementos contenedores: <all>, <any>, <choice>, <element>, <group>, <sequence>

Vea también

Referencia

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