Criar tipos definidos pelo usuário – RequisitosCreating User-Defined Types - Requirements

APLICA-SE A: simSQL Server nãoBanco de Dados SQL do Azure nãoAzure Synapse Analytics (SQL DW) nãoParallel Data Warehouse APPLIES TO: yesSQL Server noAzure SQL Database noAzure Synapse Analytics (SQL DW) noParallel Data Warehouse

Você deve tomar várias decisões de design importantes durante a criação de um tipo definido pelo usuário (UDT) a serem instalados em 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. De uma forma geral, é recomendável criar o UDT como uma estrutura, embora criá-lo como classe também seja uma opção.For most UDTs, creating the UDT as a structure is recommended, although creating it as a class is also an option. A definição do UDT precisa estar de acordo com as especificações para criação de UDTs para que seja registrado com o 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 implementação de UDTsRequirements for Implementing UDTs

Para ser executado no SQL ServerSQL Server, o UDT precisa implementar os seguintes requisitos na definição do UDT:To run in SQL ServerSQL Server, your UDT must implement the following requirements in the UDT definition:

O UDT precisa especificar o Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute.The UDT must specify the Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute. O uso do System.SerializableAttribute é opcional, mas recomendada.The use of the System.SerializableAttribute is optional, but recommended.

  • O UDT precisa implementar o System.Data.SqlTypes.INullable interface na classe ou estrutura criando uma pública estático (compartilhado em MicrosoftMicrosoft Visual Basic) nulo 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. O SQL ServerSQL Server reconhece o valor nulo por padrão.SQL ServerSQL Server is null-aware by default. Isso é necessário para que o código executado no UDT consiga reconhecer um valor nulo.This is necessary for code executing in the UDT to be able to recognize a null value.

  • O UDT precisa conter um público estáticos (ou compartilhado) analisar método que dá suporte à análise de e uma pública ToString método para Convertendo em uma representação de cadeia de caracteres do 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.

  • Um UDT com um formato de serialização definida pelo usuário deve implementar o System.Data.IBinarySerialize interface e fornecer uma leitura e um gravar 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.

  • O UDT precisa implementar System.Xml.Serialization.IXmlSerializable, ou todas as propriedades e campos públicos devem ser de tipos que são serializáveis por XML ou decorados com o XmlIgnore se do atributo é necessário substituir a serialização padrão.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.

  • Deve haver apenas uma serialização de um objeto UDT.There must be only one serialization of a UDT object. Haverá falha na validação se as rotinas de serialização ou desserialização reconhecerem mais de uma representação de um objeto específico.Validation fails if the serialize or deserialize routines recognize more than one representation of a particular object.

  • SqlUserDefinedTypeAttribute.IsByteOrdered deve ser verdadeiro para comparar dados em ordem de byte.SqlUserDefinedTypeAttribute.IsByteOrdered must be true to compare data in byte order. Se a interface IComparable não for implementada e SqlUserDefinedTypeAttribute.IsByteOrdered é falso, comparações de ordem de byte falharão.If the IComparable interface is not implemented and SqlUserDefinedTypeAttribute.IsByteOrdered is false, byte order comparisons will fail.

  • Um UDT definido em uma classe deve ter um construtor público que não leve argumentos.A UDT defined in a class must have a public constructor that takes no arguments. Você tem a opção de criar construtores de classe sobrecarregados adicionais.You can optionally create additional overloaded class constructors.

  • O UDT precisa expor elementos de dados como campos públicos ou procedimentos de propriedade.The UDT must expose data elements as public fields or property procedures.

  • Nomes públicos não pode ter mais de 128 caracteres e deve estar de acordo com o SQL ServerSQL Server regras de nomeação para identificadores conforme definido na identificadores de banco de dados.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 colunas não podem conter instâncias de um UDT.sql_variant columns cannot contain instances of a UDT.

  • Os membros herdados não são acessíveis a partir do Transact-SQLTransact-SQL porque o sistema de tipos do SQL ServerSQL Server não reconhece a hierarquia de herança entre UDTs.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. Entretanto, você pode usar a herança ao estruturar suas classes, além de chamar esses métodos na implementação de código gerenciado do 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.

  • Os membros não podem ficar sobrecarregados, com exceção do construtor de classe.Members cannot be overloaded, except for the class constructor. Se você criar um método sobrecarregado, nenhum erro ocorrerá quando você registrar o assembly ou criar o tipo no 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. A detecção do método sobrecarregado ocorre em tempo de execução, e não quando o tipo é criado.Detection of the overloaded method occurs at run time, not when the type is created. Os métodos sobrecarregados podem existir na classe, contanto que nunca sejam invocados.Overloaded methods can exist in the class as long as they are never invoked. Quando você invoca o método sobrecarregado, ocorre um erro.Once you invoke the overloaded method, an error is raised.

  • Qualquer estáticos (ou compartilhado) membros devem ser declarados como constantes ou somente leitura.Any static (or Shared) members must be declared as constants or as read-only. Membros estáticos não podem ser mutáveis.Static members cannot be mutable.

  • Se o SqlUserDefinedTypeAttribute.MaxByteSize é definido como -1, o UDT serializado poderá ser tão grande quanto o limite de tamanho de objeto grande (LOB) (atualmente 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). O tamanho do UDT não pode exceder o valor especificado na MaxByteSized campo.The size of the UDT cannot exceed the value specified in the MaxByteSized field.

Observação

Embora não seja usada pelo servidor para realizar comparações, você pode, opcionalmente, implemente a System. IComparable interface, que expõe um ú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. Isso é usado no lado do cliente em situações nas quais é desejável comparar ou ordenar valores UDT com precisão.This is used on the client side in situations in which it is desirable to accurately compare or order UDT values.

Serialização nativaNative Serialization

A escolha dos atributos de serialização adequados para o UDT depende do tipo de UDT que você está tentando criar.Choosing the right serialization attributes for your UDT depends on the type of UDT you are trying to create. O nativos utiliza uma estrutura muito simples que permite que o formato de serialização SQL ServerSQL Server armazene uma representação nativa eficiente do UDT em 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. O nativo formato é recomendado se o UDT for simple e contiver somente campos dos tipos a seguir:The Native format is recommended if the UDT is simple and only contains fields of the following types:

bool, byte, sbyte, short, ushort, int, uint, long, ulong, float, double, 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 são compostos de campos dos tipos acima são bons candidatos para nativos Formatar, como structs no Visual c# (ou estruturas conforme eles são conhecidos no 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 exemplo, um UDT especificado com o nativos formato de serialização pode conter um campo de outro UDT que também foi especificado com o 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. Se a definição de UDT é mais complexa e contém os tipos de dados na lista acima, você deve especificar o UserDefined formato de serialização.If the UDT definition is more complex and contains data types not on the above list, you must specify the UserDefined serialization format instead.

O nativo formato tem os seguintes requisitos:The Native format has the following requirements:

  • O tipo não deve especificar um valor para Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute.MaxByteSize.The type must not specify a value for Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute.MaxByteSize.

  • Todos os campos precisam ser serializáveis.All fields must be serializable.

  • O StructLayoutAttribute deve ser especificado como LayoutKindSequential se o UDT é definido em uma classe e não em uma estrutura.The System.Runtime.InteropServices.StructLayoutAttribute must be specified as StructLayout.LayoutKindSequential if the UDT is defined in a class and not a structure. Esse atributo controla o layout físico dos campos de dados e é usado para obrigar os membros a ser dispostos na ordem em que aparecem.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. O SQL ServerSQL Server usa esse atributo para determinar a ordem dos campos para UDTs com vários valores.SQL ServerSQL Server uses this attribute to determine the field order for UDTs with multiple values.

Para obter um exemplo de um UDT definido com nativos serialização, consulte o UDT Point em Codificando tipos.For an example of a UDT defined with Native serialization, see the Point UDT in Coding User-Defined Types.

Serialização UserDefinedUserDefined Serialization

O UserDefined formato de configuração para o Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute fornece atributo ao desenvolvedor total controle sobre o formato binário.The UserDefined format setting for the Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute attribute gives the developer full control over the binary format. Ao especificar o formato propriedade como de atributo UserDefined, você deve fazer o seguinte em seu código:When specifying the Format attribute property as UserDefined, you must do the following in your code:

  • Especifique o valor opcional IsByteOrdered propriedade de atributo.Specify the optional IsByteOrdered attribute property. O valor padrão é false.The default value is false.

  • Especifique o MaxByteSize propriedade da Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute.Specify the MaxByteSize property of the Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute.

  • Escrever código para implementar leitura e escrever métodos para o UDT Implementando a System.Data.Sql.IBinarySerialize interface.Write code to implement Read and Write methods for the UDT by implementing the System.Data.Sql.IBinarySerialize interface.

Para obter um exemplo de um UDT definido com UserDefined serialização, consulte o UDT Currency em Codificando tipos.For an example of a UDT defined with UserDefined serialization, see the Currency UDT in Coding User-Defined Types.

Observação

Os campos UDT precisam usar serialização nativa ou serem persistidos para serem indexados.UDT fields must use native serialization or be persisted in order to be indexed.

Atributos de serializaçãoSerialization Attributes

Os atributos determinam como a serialização é usada para construir a representação de armazenamento de UDTs e transmiti-los por valor para o cliente.Attributes determine how serialization is used to construct the storage representation of UDTs and to transmit UDTs by value to the client. Você deve especificar o Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute ao criar o UDT.You are required to specify the Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute when creating the UDT. O Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute atributo indica que a classe é um UDT e especifica o armazenamento para o UDT.The Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute attribute indicates that the class is a UDT and specifies the storage for the UDT. Opcionalmente, você pode especificar o Serializable do atributo, embora SQL ServerSQL Server não requer isso.You can optionally specify the Serializable attribute, although SQL ServerSQL Server does not require this.

O Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute tem as seguintes propriedades.The Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute has the following properties.

FormatarFormat
Especifica o formato de serialização, que pode ser nativos ou UserDefined, dependendo dos tipos de dados do UDT.Specifies the serialization format, which can be Native or UserDefined, depending on the data types of the UDT.

IsByteOrderedIsByteOrdered
Um Boolean valor que determina como SQL ServerSQL Server executa comparações binárias no UDT.A Boolean value that determines how SQL ServerSQL Server performs binary comparisons on the UDT.

IsFixedLengthIsFixedLength
Indica se todas as instâncias desse UDT têm a mesma extensão.Indicates whether all instances of this UDT are the same length.

MaxByteSizeMaxByteSize
O tamanho máximo da instância, em bytes.The maximum size of the instance, in bytes. Você deve especificar MaxByteSize com o UserDefined formato de serialização.You must specify MaxByteSize with the UserDefined serialization format. Para um UDT com serialização definida pelo usuário especificado, MaxByteSize refere-se ao tamanho total do UDT em sua forma serializada conforme definido pelo usuário.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. O valor de MaxByteSize deve estar no intervalo de 1 a 8000 ou definido como -1 para indicar que o UDT é maior que 8000 bytes (o tamanho total não pode exceder o tamanho 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 um UDT com uma propriedade de uma cadeia de caracteres de 10 caracteres (System. Char).Consider a UDT with a property of a string of 10 characters (System.Char). Quando o UDT é serializado usando um BinaryWriter, o tamanho total da cadeia de caracteres serializada é de 22 bytes: 2 bytes por caractere Unicode UTF-16, multiplicado pelo número máximo de caracteres, além de controle de 2 bytes de sobrecarga ocasionada pela serialização de um fluxo binário.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. Portanto, ao determinar o valor de MaxByteSize, deve ser considerado o tamanho total do UDT serializado: o tamanho dos dados serializados em formato binário mais a sobrecarga ocasionada pela serialização.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
O nome do método usado para validar instâncias do UDT.The name of the method used to validate instances of the UDT.

Definindo IsByteOrderedSetting IsByteOrdered

Quando o Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute.IsByteOrdered estiver definida como verdadeiro, você está garantindo que os dados binários serializados podem ser usados para semântica ordenação das informações.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. Assim, cada instância de um objeto UDT ordenado por byte pode ter somente uma representação serializada.Thus, each instance of a byte-ordered UDT object can only have one serialized representation. Quando é executada uma operação de comparação no SQL ServerSQL Server nos bytes serializados, os resultados devem ser os mesmos de quando a operação de comparação ocorre em código gerenciado.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. Os recursos a seguir também são suportados quando IsByteOrdered é definido como verdadeiro:The following features are also supported when IsByteOrdered is set to true:

  • A capacidade de criar índices em colunas desse tipo.The ability to create indexes on columns of this type.

  • A capacidade de criar chaves primárias e estrangeiras, além de restrições CHECK e UNIQUE em colunas desse tipo.The ability to create primary and foreign keys as well as CHECK and UNIQUE constraints on columns of this type.

  • A capacidade de usar as cláusulas Transact-SQLTransact-SQL ORDER BY, GROUP BY e PARTITION BY.The ability to use Transact-SQLTransact-SQL ORDER BY, GROUP BY, and PARTITION BY clauses. Nesses casos, a representação binária do tipo é usada para determinar a ordem.In these cases, the binary representation of the type is used to determine the order.

  • A capacidade de usar operadores de comparação em instruções Transact-SQLTransact-SQL.The ability to use comparison operators in Transact-SQLTransact-SQL statements.

  • A capacidade de persistir colunas computadas desse tipo.The ability to persist computed columns of this type.

Observe que tanto a nativos e UserDefined formatos de serialização suportam os seguintes operadores de comparação quando IsByteOrdered é definido como 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 (=)

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

  • Maior que (>)Greater than (>)

  • Menor que (<)Less than (<)

  • Maior que ou igual a (> =)Greater than or equal to (>=)

  • Menor ou igual a (< =)Less than or equal to (<=)

Implementando a nulidadeImplementing Nullability

Além de especificar corretamente os atributos dos assemblies, sua classe também precisa suportar a nulidade.In addition to specifying the attributes for your assemblies correctly, your class must also support nullability. Os UDTs carregados no SQL ServerSQL Server reconhecem nulos, mas para o UDT reconheça um valor nulo, a classe deve implementar a INullable interface.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 obter mais informações e um exemplo de como implementar a nulidade em um UDT, consulte Codificando tipos.For more information and an example of how to implement nullability in a UDT, see Coding User-Defined Types.

Conversões de cadeia de caracteresString Conversions

Para dar suporte à conversão de cadeia de caracteres de e para o UDT, você deve fornecer um analisar método e uma ToString método em sua classe.To support string conversion to and from the UDT, you must provide a Parse method and a ToString method in your class. O analisar método permite que uma cadeia de caracteres a ser convertido em um UDT.The Parse method allows a string to be converted into a UDT. Ele deve ser declarado como estáticos (ou compartilhado no Visual Basic) e usar um 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 obter mais informações e um exemplo de como implementar o analisar e ToString métodos, consulte Codificando tipos.For more information and an example of how to implement the Parse and ToString methods, see Coding User-Defined Types.

Serialização XMLXML Serialization

Os UDTs precisam suportar a conversão de e para o xml tipo de dados por estar em conformidade com o contrato para serialização de XML.UDTs must support conversion to and from the xml data type by conforming to the contract for XML serialization. O Serialization namespace contém classes que são usadas para serializar objetos em fluxos ou documentos de formato XML.The System.Xml.Serialization namespace contains classes that are used to serialize objects into XML format documents or streams. Você pode optar por implementar xml serialização usando o IXmlSerializable interface, que oferece formatação personalizada para serialização e desserialização XML.You can choose to implement xml serialization by using the IXmlSerializable interface, which provides custom formatting for XML serialization and deserialization.

Além de realizar conversões explícitas de UDT xml, a serialização XML permite que você:In addition to performing explicit conversions from UDT to xml, XML serialization enables you to:

  • Use Xquery sobre os valores de instâncias UDT após a conversão para o xml tipo de dados.Use Xquery over values of UDT instances after conversion to the xml data type.

  • Usar UDTs em consultas parametrizadas e métodos de Web com XML Web Services Nativos no SQL ServerSQL Server.Use UDTs in parameterized queries and Web methods with Native XML Web Services in SQL ServerSQL Server.

  • Usar UDTs para receber um carregamento em massa de dados XML.Use UDTs to receive a bulk load of XML data.

  • Serializar DataSets que contêm tabelas com colunas de UDT.Serialize DataSets that contain tables with UDT columns.

Os UDTs não são serializados em consultas FOR XML.UDTs are not serialized in FOR XML queries. Para executar uma consulta FOR XML que exibe a serialização XML dos UDTs, converta explicitamente cada coluna UDT para o xml tipo de dados na instrução 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. Você também pode converter explicitamente as colunas a serem varbinary, varchar, ou nvarchar.You can also explicitly convert the columns to varbinary, varchar, or nvarchar.

Consulte tambémSee Also

Criando um tipo definido pelo usuárioCreating a User-Defined Type