Crear tipos definidos por el usuario: requisitosCreating User-Defined Types - Requirements

SE APLICA A: síSQL Server noAzure SQL Database noAzure SQL Data Warehouse noAlmacenamiento de datos paralelos APPLIES TO: yesSQL Server noAzure SQL Database noAzure SQL Data Warehouse noParallel Data Warehouse

Debe realizar varias decisiones de diseño importante al crear un tipo definido por el usuario (UDT) se instale en MicrosoftMicrosoft SQL ServerSQL Server.You must make several important design decisions when creating a user-defined type (UDT) to be installed in MicrosoftMicrosoftSQL ServerSQL Server. Para la mayoría de los UDT, se recomienda la creación del UDT como una estructura, aunque también puede crearse como una clase.For most UDTs, creating the UDT as a structure is recommended, although creating it as a class is also an option. La definición del UDT debe cumplir las especificaciones de creación de los UDT a fin de registrarse con SQL ServerSQL Server.The UDT definition must conform to the specifications for creating UDTs in order for it to be registered with SQL ServerSQL Server.

Requisitos para implementar un UDTRequirements for Implementing UDTs

El UDT, para poder ejecutarse en SQL ServerSQL Server, debe implementar los requisitos siguientes en la definición del UDT:To run in SQL ServerSQL Server, your UDT must implement the following requirements in the UDT definition:

El UDT debe especificar el Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute.The UDT must specify the Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute. El uso de la System.SerializableAttribute con es opcional pero recomendable.The use of the System.SerializableAttribute is optional, but recommended.

  • El UDT debe implementar la System.Data.SqlTypes.INullable interfaz en la clase o estructura mediante la creación de un público estático (Shared en MicrosoftMicrosoft Visual Basic) Null método.The UDT must implement the System.Data.SqlTypes.INullable interface in the class or structure by creating a public static (Shared in MicrosoftMicrosoft Visual Basic) Null method. SQL ServerSQL Server tiene en cuenta el valor NULL de forma predeterminada.is null-aware by default. Esto es necesario para que el código que se ejecuta en el UDT pueda reconocer un valor NULL.This is necessary for code executing in the UDT to be able to recognize a null value.

  • El UDT debe contener una pública estático (o Shared) analizar método que admita el análisis y una pública ToString método para convertir en una representación de cadena del objeto.The UDT must contain a public static (or Shared) Parse method that supports parsing from, and a public ToString method for converting to a string representation of the object.

  • Debe implementar un UDT con un formato de serialización definido por el usuario la System.Data.IBinarySerialize interfaz y proporcionar un lectura y un escribir método.A UDT with a user-defined serialization format must implement the System.Data.IBinarySerialize interface and provide a Read and a Write method.

  • El UDT debe implementar System.Xml.Serialization.IXmlSerializable, o todos los campos públicos y propiedades deben ser de tipos que son serializables con XML o representarse con el XmlIgnore atributo si es necesario invalidar la serialización estándar.The UDT must implement System.Xml.Serialization.IXmlSerializable, or all public fields and properties must be of types that are XML serializable or decorated with the XmlIgnore attribute if overriding standard serialization is required.

  • Solo debe haber una serialización de un objeto UDT.There must be only one serialization of a UDT object. Se produce un error en la validación si las rutinas de serialización o deserialización reconocen más de una representación de un objeto determinado.Validation fails if the serialize or deserialize routines recognize more than one representation of a particular object.

  • SqlUserDefinedTypeAttribute.IsByteOrdered debe ser true para comparar los datos en orden de bytes.SqlUserDefinedTypeAttribute.IsByteOrdered must be true to compare data in byte order. Si no se implementa la interfaz IComparable y SqlUserDefinedTypeAttribute.IsByteOrdered es false, se producirá un error en las comparaciones de orden de bytes.If the IComparable interface is not implemented and SqlUserDefinedTypeAttribute.IsByteOrdered is false, byte order comparisons will fail.

  • Un UDT definido en una clase debe tener un constructor público que no tome ningún argumento.A UDT defined in a class must have a public constructor that takes no arguments. Si lo desea, puede crear otros constructores de clase sobrecargados.You can optionally create additional overloaded class constructors.

  • El UDT debe exponer elementos de datos como procedimientos de propiedad o campos públicos.The UDT must expose data elements as public fields or property procedures.

  • Nombres públicos no puede tener más de 128 caracteres y debe cumplir la SQL ServerSQL Server reglas de nomenclatura para los identificadores tal como se define en identificadores de base de datos.Public names cannot be longer than 128 characters, and must conform to the SQL ServerSQL Server naming rules for identifiers as defined in Database Identifiers.

  • sql_variant columnas no pueden contener instancias de un UDT.sql_variant columns cannot contain instances of a UDT.

  • Los miembros heredados no son accesibles desde Transact-SQLTransact-SQL porque el sistema de tipos SQL ServerSQL Server no es consciente de la jerarquía de herencia entre los UDT.Inherited members are not accessible from Transact-SQLTransact-SQL because the SQL ServerSQL Server type system is not aware of the inheritance hierarchy among UDTs. Sin embargo, puede usar la herencia al estructurar sus clases y puede llamar a dichos métodos en la implementación del código administrado del tipo.However, you can use inheritance when you structure your classes and you can call such methods in the managed code implementation of the type.

  • No es posible sobrecargar los miembros, salvo el constructor de clase.Members cannot be overloaded, except for the class constructor. Si crea un método sobrecargado, no se produce ningún error al registrar el ensamblado o crear el tipo en SQL ServerSQL Server.If you do create an overloaded method, no error is raised when you register the assembly or create the type in SQL ServerSQL Server. La detección del método sobrecargado se produce en tiempo de ejecución, no cuando se crea el tipo.Detection of the overloaded method occurs at run time, not when the type is created. Puede haber métodos sobrecargados en la clase siempre y cuando no se invoquen nunca.Overloaded methods can exist in the class as long as they are never invoked. Al invocar al método sobrecargado se produce un error.Once you invoke the overloaded method, an error is raised.

  • Cualquier estático (o Shared) los miembros deben declararse como constantes o como de solo lectura.Any static (or Shared) members must be declared as constants or as read-only. Los miembros estáticos no pueden ser mutables.Static members cannot be mutable.

  • Si el SqlUserDefinedTypeAttribute.MaxByteSize campo se establece en -1, el UDT serializado puede ser tan grande como el límite de tamaño de objetos grandes (LOB) (actualmente 2 GB).If the SqlUserDefinedTypeAttribute.MaxByteSize field is set to -1, the serialized UDT can be as large as the large object (LOB) size limit (currently 2 GB). El tamaño del UDT no puede superar el valor especificado en el MaxByteSized campo.The size of the UDT cannot exceed the value specified in the MaxByteSized field.

Nota

Aunque no se usa el servidor para realizar comparaciones, también puede implementar la System.IComparable interfaz, que expone un único método, CompareTo.Although it is not used by the server for performing comparisons, you can optionally implement the System.IComparable interface, which exposes a single method, CompareTo. Se usa del lado cliente en situaciones en las que se desean realizar comparaciones precisas u ordenar los valores UDT.This is used on the client side in situations in which it is desirable to accurately compare or order UDT values.

Serialización nativaNative Serialization

La elección de los atributos de serialización correctos para su UDT depende del tipo de UDT que está intentando crear.Choosing the right serialization attributes for your UDT depends on the type of UDT you are trying to create. El nativo formato de serialización usa una estructura muy simple que permite SQL ServerSQL Server para almacenar una representación nativa eficaz del UDT en el disco.The Native serialization format utilizes a very simple structure that enables SQL ServerSQL Server to store an efficient native representation of the UDT on disk. El nativo formato se recomienda si el UDT es simple y solamente contiene campos de los siguientes tipos:The Native format is recommended if the UDT is simple and only contains fields of the following types:

BOOL, bytes, sbyte, corto, ushort, int, uint, largo, ulong, float, doble, SqlByte, SqlInt16, SqlInt32, SqlInt64, SqlDateTime, SqlSingle, SqlDouble, SqlMoney, SqlBooleanbool, byte, sbyte, short, ushort, int, uint, long, ulong, float, double, SqlByte, SqlInt16, SqlInt32, SqlInt64, SqlDateTime, SqlSingle, SqlDouble, SqlMoney, SqlBoolean

Tipos de valor que se componen de campos de los tipos anteriores son buenos candidatos para nativo dar formato, como structs en Visual C# (o estructuras tal como se conocen en Visual Basic).Value types that are composed of fields of the above types are good candidates for Native format, such as structs in Visual C#, (or Structures as they are known in Visual Basic). Por ejemplo, un UDT especificado con el nativo formato de serialización puede contener un campo de otro UDT también especificado con el nativo formato.For example, a UDT specified with the Native serialization format may contain a field of another UDT that was also specified with the Native format. Si la definición UDT es más compleja y contiene tipos de datos no están en la lista anterior, debe especificar el UserDefined en su lugar, el formato de serialización.If the UDT definition is more complex and contains data types not on the above list, you must specify the UserDefined serialization format instead.

El nativo formato tiene los siguientes requisitos:The Native format has the following requirements:

  • El tipo no debe especificar un valor para Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute.MaxByteSize.The type must not specify a value for Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute.MaxByteSize.

  • Todos los campos deben ser serializables.All fields must be serializable.

  • El System.Runtime.InteropServices.StructLayoutAttribute debe especificarse como StructLayout.LayoutKindSequential si el UDT se define en una clase y no en una estructura.The System.Runtime.InteropServices.StructLayoutAttribute must be specified as StructLayout.LayoutKindSequential if the UDT is defined in a class and not a structure. Este atributo controla el diseño físico de los campos de datos y se usa para imponer a los miembros que se coloquen en el orden en que aparecen.This attribute controls the physical layout of the data fields and is used to force the members to be laid out in the order in which they appear. SQL ServerSQL Server usa este atributo para determinar el orden de los campos para los UDT con varios valores.uses this attribute to determine the field order for UDTs with multiple values.

Para obtener un ejemplo de un UDT definido con nativo serialización, vea el UDT Point en codificación de tipos.For an example of a UDT defined with Native serialization, see the Point UDT in Coding User-Defined Types.

Serialización UserDefinedUserDefined Serialization

El UserDefined configuración de formato el Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute proporciona atributo al desarrollador pleno control sobre el formato binario.The UserDefined format setting for the Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute attribute gives the developer full control over the binary format. Al especificar el formato la propiedad de atributo UserDefined, debe hacer lo siguiente en el código:When specifying the Format attribute property as UserDefined, you must do the following in your code:

  • Especifique el valor opcional IsByteOrdered propiedad de atributo.Specify the optional IsByteOrdered attribute property. El valor predeterminado es false.The default value is false.

  • Especifique el MaxByteSize propiedad de la Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute.Specify the MaxByteSize property of the Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute.

  • Escribir código para implementar lectura y escribir métodos para el UDT implementando la System.Data.Sql.IBinarySerialize interfaz.Write code to implement Read and Write methods for the UDT by implementing the System.Data.Sql.IBinarySerialize interface.

Para obtener un ejemplo de un UDT definido con UserDefined serialización, vea el UDT Currency en codificación de tipos.For an example of a UDT defined with UserDefined serialization, see the Currency UDT in Coding User-Defined Types.

Nota

Los campos UDT deben usar la serialización nativa o conservarse para indizarse.UDT fields must use native serialization or be persisted in order to be indexed.

Atributos de serializaciónSerialization Attributes

Los atributos determinan el modo de usar la serialización para construir la representación de almacenamiento de los UDT y para transmitirlos por valor al cliente.Attributes determine how serialization is used to construct the storage representation of UDTs and to transmit UDTs by value to the client. Se debe especificar el Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute al crear el UDT.You are required to specify the Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute when creating the UDT. El Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute atributo indica que la clase es un UDT y especifica el almacenamiento para el UDT.The Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute attribute indicates that the class is a UDT and specifies the storage for the UDT. Opcionalmente, puede especificar el Serializable atributo aunque SQL ServerSQL Server no requiere esto.You can optionally specify the Serializable attribute, although SQL ServerSQL Server does not require this.

El Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute tiene las siguientes propiedades.The Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute has the following properties.

FormatoFormat
Especifica el formato de serialización, que puede ser nativo o UserDefined, en función de los tipos de datos del UDT.Specifies the serialization format, which can be Native or UserDefined, depending on the data types of the UDT.

IsByteOrderedIsByteOrdered
Un booleano valor que determina cómo SQL ServerSQL Server realiza comparaciones binarias en el UDT.A Boolean value that determines how SQL ServerSQL Server performs binary comparisons on the UDT.

IsFixedLengthIsFixedLength
Indica si todas las instancias de este UDT tienen la misma longitud.Indicates whether all instances of this UDT are the same length.

MaxByteSizeMaxByteSize
Tamaño máximo de la instancia, expresado en bytes.The maximum size of the instance, in bytes. Debe especificar MaxByteSize con el UserDefined formato de serialización.You must specify MaxByteSize with the UserDefined serialization format. Para un UDT con serialización definida por el usuario especificado, MaxByteSize se refiere al tamaño total del UDT en su formato serializado, tal como se define por el usuario.For a UDT with user-defined serialization specified, MaxByteSize refers to the total size of the UDT in its serialized form as defined by the user. El valor de MaxByteSize debe estar en el intervalo de 1 a 8000 o se establece en -1 para indicar que el UDT es superior a 8000 bytes (el tamaño total no puede superar el tamaño LOB máximo).The value of MaxByteSize must be in the range of 1 to 8000, or set to -1 to indicate that the UDT is greater than 8000 bytes (the total size cannot exceed the maximum LOB size). Considere la posibilidad de un UDT con una propiedad de una cadena de 10 caracteres (System.Char).Consider a UDT with a property of a string of 10 characters (System.Char). Cuando el UDT se serialice mediante BinaryWriter, el tamaño total de la cadena serializada es 22 bytes: 2 bytes por carácter Unicode UTF-16, multiplicado por el número máximo de caracteres, además de control de 2 bytes de sobrecarga que se produce al serializar un flujo binario.When the UDT is serialized by using a BinaryWriter, the total size of the serialized string is 22 bytes: 2 bytes per Unicode UTF-16 character, multiplied by the maximum number of characters, plus 2 control bytes of overhead incurred from serializing a binary stream. Por lo tanto, al determinar el valor de MaxByteSize, el tamaño total del UDT serializado debe considerarse: el tamaño de los datos serializados en formato binario más la sobrecarga producida por la serialización.Therefore, when determining the value of MaxByteSize, the total size of the serialized UDT must be considered: the size of the data serialized in binary form plus the overhead incurred by serialization.

ValidationMethodNameValidationMethodName
Nombre del método utilizado para validar las instancias del UDT.The name of the method used to validate instances of the UDT.

Valor IsByteOrderedSetting IsByteOrdered

Cuando el Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute.IsByteOrdered propiedad está establecida en true, en realidad lo que garantiza que los datos binarios serializados pueden usarse para semántica clasificación de la información.When the Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute.IsByteOrdered property is set to true, you are in effect guaranteeing that the serialized binary data can be used for semantic ordering of the information. De esta forma, cada instancia de un objeto UDT ordenado por bytes solamente puede tener una representación serializada.Thus, each instance of a byte-ordered UDT object can only have one serialized representation. Cuando se lleva a cabo una operación de comparación en SQL ServerSQL Server en los bytes serializados, los resultados deben ser los mismos que si se hubiese realizado la misma operación de comparación en código administrado.When a comparison operation is performed in SQL ServerSQL Server on the serialized bytes, its results should be the same as if the same comparison operation had taken place in managed code. Las siguientes características están también admiten cuando IsByteOrdered está establecido en true:The following features are also supported when IsByteOrdered is set to true:

  • Funcionalidad para crear los índices de las columnas de este tipo.The ability to create indexes on columns of this type.

  • Funcionalidad para crear las claves principal y externa, así como las restricciones CHECK y UNIQUE en las columnas de este tipo.The ability to create primary and foreign keys as well as CHECK and UNIQUE constraints on columns of this type.

  • Funcionalidad para usar las cláusulas Transact-SQLTransact-SQL ORDER BY, GROUP BY y PARTITION BY.The ability to use Transact-SQLTransact-SQL ORDER BY, GROUP BY, and PARTITION BY clauses. En estos casos, la representación binaria del tipo se usa para determinar el orden.In these cases, the binary representation of the type is used to determine the order.

  • Funcionalidad para usar los operadores de comparación en instrucciones Transact-SQLTransact-SQL.The ability to use comparison operators in Transact-SQLTransact-SQL statements.

  • Funcionalidad para conservar las columnas calculadas de este tipo.The ability to persist computed columns of this type.

Tenga en cuenta que tanto el nativo y UserDefined formatos de serialización admiten los siguientes operadores de comparación cuando IsByteOrdered está establecido en true :Note that both the Native and UserDefined serialization formats support the following comparison operators when IsByteOrdered is set to true:

  • Igual a (=)Equal to (=)

  • Distinto de (!=)Not equal to (!=)

  • Mayor que (>)Greater than (>)

  • Menor que (<)Less than (<)

  • Mayor o igual que (> =)Greater than or equal to (>=)

  • Menor o igual que (< =)Less than or equal to (<=)

Implementar la nulabilidadImplementing Nullability

Además de especificar correctamente los atributos de los ensamblados, la clase también debe admitir la nulabilidad.In addition to specifying the attributes for your assemblies correctly, your class must also support nullability. Los UDT cargados en SQL ServerSQL Server son compatibles con null, pero para el UDT reconozca un valor null, la clase debe implementar la INullable interfaz.UDTs loaded into SQL ServerSQL Server are null-aware, but in order for the UDT to recognize a null value, the class must implement the INullable interface. Para obtener más información y un ejemplo de cómo implementar la nulabilidad en un UDT, vea codificación de tipos.For more information and an example of how to implement nullability in a UDT, see Coding User-Defined Types.

Conversiones de cadenasString Conversions

Para admitir la conversión de cadena a y desde el UDT, debe proporcionar un analizar método y un ToString método en la clase.To support string conversion to and from the UDT, you must provide a Parse method and a ToString method in your class. El analizar método permite una cadena que se va a convertir en un UDT.The Parse method allows a string to be converted into a UDT. Se debe declarar como estático (o Shared en Visual Basic) y tomar un parámetro de tipo System.Data.SqlTypes.SqlString.It must be declared as static (or Shared in Visual Basic), and take a parameter of type System.Data.SqlTypes.SqlString. Para obtener más información y un ejemplo de cómo implementar la analizar y ToString métodos, vea codificación de tipos.For more information and an example of how to implement the Parse and ToString methods, see Coding User-Defined Types.

Serialización XMLXML Serialization

Los UDT deben admitir la conversión a y desde el xml tipo de datos mediante la conformidad con el contrato para la serialización XML.UDTs must support conversion to and from the xml data type by conforming to the contract for XML serialization. El System.Xml.Serialization espacio de nombres contiene clases que se utilizan para serializar objetos en secuencias o documentos con formato XML.The System.Xml.Serialization namespace contains classes that are used to serialize objects into XML format documents or streams. Puede elegir implementar xml serialización mediante el uso de la IXmlSerializable interfaz, que proporciona un formato personalizado para la serialización y deserialización XML.You can choose to implement xml serialization by using the IXmlSerializable interface, which provides custom formatting for XML serialization and deserialization.

Además de realizar conversiones explícitas de UDT a xml, serialización XML le permite:In addition to performing explicit conversions from UDT to xml, XML serialization enables you to:

  • Use Xquery sobre los valores de instancias UDT, tras la conversión a la xml tipo de datos.Use Xquery over values of UDT instances after conversion to the xml data type.

  • Usar los UDT en consultas con parámetros y en métodos web con servicios web XML nativos de SQL ServerSQL Server.Use UDTs in parameterized queries and Web methods with Native XML Web Services in SQL ServerSQL Server.

  • Usar los UDT para recibir una carga masiva de datos XML.Use UDTs to receive a bulk load of XML data.

  • Serializar conjuntos de datos que contengan tablas con columnas UDT.Serialize DataSets that contain tables with UDT columns.

Los UDT no se serializan en consultas FOR XML.UDTs are not serialized in FOR XML queries. Para ejecutar una consulta FOR XML que muestra la serialización XML de los UDT, convierta explícitamente cada columna UDT en el xml tipo de datos en la instrucción SELECT.To execute a FOR XML query that displays the XML serialization of UDTs, explicitly convert each UDT column to the xml data type in the SELECT statement. Las columnas que se puede convertir explícitamente varbinary, varchar, o nvarchar.You can also explicitly convert the columns to varbinary, varchar, or nvarchar.

Vea tambiénSee Also

Crear un tipo definido por el usuarioCreating a User-Defined Type