Microsoft.SqlServer.Server

Provides custom implementation for user-defined type (UDT) and user-defined aggregate serialization and deserialization.

.`Native` or .`UserDefined`. .`Native` allows SQL Server to handle serialization and deserialization automatically, but the format has restrictions on the kind of types it can handle. .`UserDefined` allows user-defined types and aggregates to handle their own serialization. User-defined types and aggregates must be marked with .`UserDefined` in the `SqlUserDefinedType` or `SqlUserDefinedAggregate` attribute, and must implement the interface. Note that even with custom serialization, the total size of each instance must be under the maximum allowed limit, currently 8000 bytes. ]]> The stream from which the object is deserialized.

Generates a user-defined type (UDT) or user-defined aggregate from its binary form.

method must reconstitute your object using the information written by the method. ## Examples The following example shows the implementation of the method of a UDT, which uses a to de-serialize a previously persisted UDT. This example assumes that the UDT has two data properties: `StringValue` and `DoubleValue`. [!code-csharp[IBinarySerialize Samples#1](~/../sqlclient/doc/samples/IBinarySerialize.cs#1)] ]]> The stream to which the UDT or user-defined aggregate is serialized.

Converts a user-defined type (UDT) or user-defined aggregate into its binary format so that it may be persisted.

method to reconstitute your UDT or user-defined aggregate. ## Examples The following example shows the implementation of the method of a UDT, which uses a to serialize the UDT in the user-defined binary format. The purpose of the null character padding is to ensure that the string value is completely separated from the double value, so that one UDT is compared to another in Transact-SQL code, string bytes are compared to string bytes and double bytes are compared to double bytes. [!code-csharp[IBinarySerialize Samples#2](~/../sqlclient/doc/samples/IBinarySerialize.cs#2)] ]]>

Thrown when SQL Server or the ADO.NET provider detects an invalid user-defined type (UDT).

To be added. The object.The object.

Streams all the properties into the class for the given .

class to make the class serializable. ]]> The object.The object that represents a string in string resources. The default value is `SqlUdtReason_NoUdtAttribute` which looks up a localized string similar to "no UDT attribute".

Create a new object.

A new object. [!IMPORTANT] > This function exposes for backward compatibility, and should be used with default value for `resourceReason` parameter. ]]>

Annotates the returned result of a user-defined type (UDT) with additional information that can be used in Transact-SQL.

may only be specified on non-void return values. is used only to derive information about the return type, and is not intended to be a constraint specification on what can be stored in the type. Thus, if a field has a indicating its size to be 2 characters, then the SQL Server type of the field access expression is of size 2, but assignments into the field are not restricted by this facet. The table below captures the matrix of valid values for the various properties for specific field types. In this table, "Y" indicates that the property is valid, and "N" indicates that the property is not valid. The specified must be compatible with the field type. If the property is not valid, type registration will report an error if the user specifies a non-default value for the property. The maximum values for and properties are 38. For the property, the value should be in the range of 1-8000 for binary and non-Unicode data, 1-4000 for Unicode data, or -1. All other values are not valid. |Type|IsFixedLength|MaxSize|Precision|Scale|IsNullable| |----------|-------------------|-------------|---------------|-----------|----------------| ||N|N|N|N|Y| ||N|N|N|N|Y| ||N|N|N|N|Y| ||N|N|N|N|Y| ||N|N|N|N|Y| ||N|N|N|N|Y| ||N|N|N|N|Y| ||N|N|N|N|Y| ||N|N|N|N|Y| ||N|N|N|N|Y| ||N|N|Y|Y|Y| ||Y|Y|N|N|Y| ||Y|Y|N|N|Y| ||N|N|N|N|Y| ||Y|Y|N|N|Y| ||Y|Y|N|N|Y| |Embedded UDTs|N|N|N|N|Y| ||Y|Y|N|N|Y| |Byte[]|Y|Y|N|N|Y| |Char[]|Y|Y|N|N|Y| ||N|N|N|Y¹|N| ||N|N|Y|Y|Y| (1) Specifying the scale on a DateTime type will cause the value to be returned to Transact-SQL as a DateTime2 type with the specified scale. ]]>

An optional attribute on a user-defined type (UDT) return type, used to annotate the returned result with additional information that can be used in Transact-SQL.

To be added.

Indicates whether the return type of the user-defined type is of a fixed length.

if the return type is of a fixed length; otherwise . property is set to 1. The default value is `false`. ]]>

The maximum size, in logical units, of the underlying field type of the user-defined type.

An representing the maximum size, in logical units, of the underlying field type.

The precision of the return type of the user-defined type.

An representing the precision of the return type. property is valid only for numeric types. The property must also be specified when setting the property. The maximum value of the property is 38; the default value is 38. ]]>

The scale of the return type of the user-defined type.

An representing the scale of the return type. property is valid only for decimal types. The property must also be specified when setting the property. The maximum value of the property is 38; the default value is 0. ]]>

Indicates whether the return type of the user-defined type can be .

if the return type of the user-defined type can be ; otherwise .

Describes the type of access to user data for a user-defined method or function.

and to indicate whether the method or function uses ADO.NET to connect back to the database using the "context connection." Note that methods and functions are not allowed to make changes to the database, so the options for this enumeration are `None` (meaning no data-access performed by the method or function) and `Read` (meaning that the method or function perform read-only data-access operations, such as executing SELECT statements). ]]>

The method or function does not access user data.

The method or function reads user data.

Describes the type of access to system data for a user-defined method or function.

and to indicate what type of access to system data the method or function has. Note that methods and functions are not allowed to make changes to the database, so the options for this enumeration are `None` (meaning no data-access performed by the method or function) and `Read` (meaning that the method or function performs read-only data-access operations, such as executing SELECT statements). ]]>

The method or function does not access system data.

The method or function reads system data.

Used to mark a method definition of a user-defined aggregate as a function in SQL Server. The properties on the attribute reflect the physical characteristics used when the type is registered with SQL Server.

An optional attribute on a user-defined aggregate, used to indicate that the method should be registered in SQL Server as a function. Also used to set the , , , , , , and properties of the function attribute.

To be added.

Indicates whether the user-defined function is deterministic.

if the function is deterministic; otherwise . property is also useful for indexing the result of the function in the form of indexed computed columns and indexed views. If this property is not specified, the function is assumed to be non-deterministic. Functions that access local data can be deterministic. The data access characteristic is captured separately by the and properties. Note that data access to remote servers (for example, using a to connect to another SQL Server instance) is available in user-defined functions. However, you must still honor the declaration. If the common language runtime (CLR) function is marked as deterministic, it should not cause side-effects in the remote server. While side-effects against the context connection are restricted, SQL Server will not enforce the restriction for side-effects over remote connections. The default value of this attribute is `false`. Do not mark a function as deterministic if the function does not always produce the same output values, given the same input values and the same database state. Marking a function as deterministic when the function is not truly deterministic can result in corrupted indexed views and computed columns. ]]>

Indicates whether the function involves access to user data stored in the local instance of SQL Server.

.: Does not access data. .: Only reads user data. . is also required when connecting to remote servers if transactions integration is required (the default). If a Transact-SQL query is executed from inside a table-valued function (TVF), the property should be set. ]]>

Indicates whether the function requires access to data stored in the system catalogs or virtual system tables of SQL Server.

.: Does not access system data. .: Only reads system data. . ]]>

Indicates whether the function involves imprecise computations, such as floating point operations.

if the function involves precise computations; otherwise .

The name under which the function should be registered in SQL Server.

A value representing the name under which the function should be registered.

A string that represents the table definition of the results, if the method is used as a table-valued function (TVF).

A value representing the table definition of the results.

The name of a method in the same class which is used to fill a row of data in the table returned by the table-valued function.

A value representing the name of a method in the same class which is used to fill a row of data in the table returned by the table-valued function.

Indicates the determinism and data access properties of a method or property on a user-defined type (UDT). The properties on the attribute reflect the physical characteristics that are used when the type is registered with SQL Server.

should be used on the setter or the getter directly. inherits from a , so inherits the `FillRowMethodName` and `TableDefinition` fields from . Note that it is not possible to write a table-valued method, although the names of these fields might suggest that it is possible. ## Examples The following example shows a UDT method that is attributed to indicate that the method will not be invoked on null instances of the type, that the method will not change the state of the type, and that the method will not be called when `null` parameters are supplied to the method invocation. [!code-csharp[SqlMethod Sample#1](~/../sqlclient/doc/samples/SqlMethod.cs#1)] ]]>

An attribute on a user-defined type (UDT), used to indicate the determinism and data access properties of a method or a property on a UDT.

To be added.

Indicates whether the method on a user-defined type (UDT) is called when input arguments are specified in the method invocation.

if the method is called when input arguments are specified in the method invocation; if the method returns a value when any of its input parameters are . If the method cannot be invoked (because of an attribute on the method), the SQL Server is returned. property is `true`. ]]>

Indicates whether a method on a user-defined type (UDT) is a mutator.

if the method is a mutator; otherwise . property is set to `true` and the return type of the method is `void`, SQL Server marks the method as a mutator. A mutator method is one that causes a state change in the UDT instance. Mutator methods can be called in assignment statements or data modification statements, but cannot be used in queries. If a method is marked as a mutator but does not return void, then CREATE TYPE does not fail with an error. Even though a returned value other than `void` does not raise an error, the returned value is not accessible and cannot be used. The default value of the property is `false`. A property can be a mutator if is used on the setter and is set to `true`. However, a property setter is implicitly treated as a mutator, so it is not necessary to set the property of the to `true`. ]]>

Indicates whether SQL Server should invoke the method on null instances.

if SQL Server should invoke the method on null instances; otherwise, . If the method cannot be invoked (because of an attribute on the method), the SQL Server is returned.

Indicates that the type should be registered as a user-defined aggregate. The properties on the attribute reflect the physical attributes used when the type is registered with SQL Server. This class cannot be inherited.

custom attribute. Every user-defined aggregate must be annotated with this attribute. See "CLR User-Defined Aggregates" in SQL Server 2005 Books Online for more information on user-defined aggregates and examples. ## Examples The following example shows the attribute for a user-defined aggregate. The aggregate uses custom serialization, has a maximum size of 8000 bytes when serialized, and is invariant to nulls, duplicates, and order. [!code-csharp[SqlUserDefinedAggregate Sample#1](~/../sqlclient/doc/samples/SqlUserDefinedAggregate.cs#1)] ]]>

The maximum size, in bytes, required to store the state of this aggregate instance during computation.

value representing the maximum size of the aggregate instance. ]]> One of the values representing the serialization format of the aggregate.

A required attribute on a user-defined aggregate, used to indicate that the given type is a user-defined aggregate and the storage format of the user-defined aggregate.

The maximum size, in bytes, of the aggregate instance.

An value representing the maximum size of the aggregate instance. property with the UserDefined serialization . The maximum allowed value for this property is specified by the field. The maximum size allowed is 2 gigabytes (GB). You can specify a number from 1 to 8000 bytes, or -1 to represent a value larger than 8000 bytes, up to 2 gigabytes. For an aggregate with user-defined serialization specified, refers to the total size of the serialized data. Consider an aggregate serializing a string of 10 characters (). When the string is serialized using a , 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. So, when determining the value of , the total size of the serialized data must be considered: the size of the data serialized in binary form plus the overhead incurred by serialization. ]]>

Indicates whether the aggregate is invariant to duplicates.

if the aggregate is invariant to duplicates; otherwise .

Indicates whether the aggregate is invariant to nulls.

if the aggregate is invariant to nulls; otherwise .

Indicates whether the aggregate is invariant to order.

if the aggregate is invariant to order; otherwise .

Indicates whether the aggregate returns if no values have been accumulated.

if the aggregate returns if no values have been accumulated; otherwise .

The serialization format as a .

A representing the serialization format.

The name of the aggregate.

A value representing the name of the aggregate.

Used by and to indicate the serialization format of a user-defined type (UDT) or aggregate.

and to indicate the serialization format of a user-defined type (UDT) or aggregate. Use of the `Native` and `UserDefined` enumeration members has special requirements. - `Format.Native` The requirements for the `Format.Native` format are: - The with a property value of must be applied to the aggregate or UDT if it is defined in a class and not a structure. This controls the physical layout of the data fields and is used to force the members to be laid out sequentially in the order they appear. SQL Server uses this attribute to determine the field order for UDTs with multiple fields. - The type must contain at least one member (serialized values cannot be zero bytes in size). - All the fields of the aggregate must be *blittable*; that is, they must have a common representation in both managed and unmanaged memory and not require special handling by the interop marshaler. - All the fields of the UDT should be of one of the following types that can be serialized: `bool`, `byte`, `sbyte`, `short`, `ushort`, `int`, `uint`, `long`, `ulong`, `float`, `double`, , , , , , , , , or other value types defined by the user that contain fields of one of these types. - The aggregate must not specify a value for `MaxByteSize`. - The aggregate must not have any [NonSerialized] fields. - Fields must not be marked as an explicit layout (with a of ). - `Format.UserDefined` The requirements for the `Format.UserDefined` format are: - The aggregate must specify a value for `MaxByteSize`. - Specify the attribute property. The default value is `false`. - If you omit any field in the or methods, the state of that field is not serialized. ## Examples The following example shows the `UserDefinedType` attribute of the Point UDT. The UDT is byte-ordered, is named "Point", has a validation method named "ValidatePoint", and uses the native serialization format. [!code-csharp[SqlUserDefinedType Example#1](~/../sqlclient/doc/samples/SqlUserDefinedType.cs#1)] ]]>

The serialization format is unknown.

This serialization format uses a very simple algorithm that enables SQL Server to store an efficient representation of the UDT on disk. Types marked for serialization can only have value types (structs in Microsoft Visual C# and structures in Microsoft Visual Basic .NET) as members. Members of reference types (such as classes in Visual C# and Visual Basic), either user-defined or those existing in .NET class libraries (such as ), are not supported.

This serialization format gives the developer full control over the binary format through the and methods.

Used to mark a type definition in an assembly as a user-defined type (UDT) in SQL Server. The properties on the attribute reflect the physical characteristics used when the type is registered with SQL Server. This class cannot be inherited.

custom attribute. Every UDT must be annotated with this attribute. See [CLR User-Defined Types](https://go.microsoft.com/fwlink/?LinkId=128028) for more information about UDTs, including an example of a UDT. ## Examples The following example shows the `UserDefinedType` attribute of the Point UDT. The UDT is byte-ordered, is named "Point", has a validation method named "ValidatePoint", and uses the native serialization format. [!code-csharp[SqlUserDefinedType Example#1](~/../sqlclient/doc/samples/SqlUserDefinedType.cs#1)] ]]> One of the values representing the serialization format of the type.

A required attribute on a user-defined type (UDT), used to confirm that the given type is a UDT and to indicate the storage format of the UDT.

The maximum size of the instance, in bytes.

An value representing the maximum size of the instance. property with the `UserDefined` serialization . When connecting to SQL Server 2005 or earlier, must be between 1 and 8000. When connecting to SQL Server 2008 or later, set between 1 and 8000, for a type whose instances are always 8,000 bytes or less. For types that can have instances larger than 8000, specify -1. For a UDT with user-defined serialization specified, refers to the total size of the UDT in its serialized form as defined by the user. Consider a UDT with a property of a string of 10 characters (). When the UDT is serialized using a , 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. So, when determining the value of , 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. This property should not be used with `Native` serialization . ]]>

Indicates whether all instances of this user-defined type are the same length.

if all instances of this type are the same length; otherwise . . This attribute is only relevant for UDTs with `UserDefined` serialization . ]]>

Indicates whether the user-defined type is byte ordered.

if the user-defined type is byte ordered; otherwise . property in effect guarantees that the serialized binary data can be used for semantic ordering of the information. Thus, each instance of a byte-ordered UDT object can only have one serialized representation. When a comparison operation is performed in SQL Server on the serialized bytes, its results should be the same as if the same comparison operation had taken place in managed code. The following features are supported when is set to `true`: - The ability to create indexes on columns of this type. - The ability to create primary and foreign keys as well as CHECK and UNIQUE constraints on columns of this type. - The ability to use Transact-SQL ORDER BY, GROUP BY, and PARTITION BY clauses. In these cases, the binary representation of the type is used to determine the order. - The ability to use comparison operators in Transact-SQL statements. - The ability to persist computed columns of this type. Note that both the `Native` and `UserDefined` serialization formats support the following comparison operators when is set to `true`: - Equal to (=) - Not equal to (!=) - Greater than (>) - Less than (\<) - Greater than or equal to (>=) - Less than or equal to (<=) ]]>

The serialization format as a .

A value representing the serialization format.

The name of the method used to validate instances of the user-defined type.

A representing the name of the method used to validate instances of the user-defined type.

The SQL Server name of the user-defined type.

A value representing the SQL Server name of the user-defined type. property is not used within SQL Server, but is used by the Microsoft Visual Studio .NET Integrated Development Environment (IDE). ]]>

A strongly-typed resource class, for looking up localized strings, etc.

Returns the cached ResourceManager instance used by this class.

Overrides the current thread's CurrentUICulture property for all resource lookups using this strongly typed resource class.

Looks up a localized string similar to The {0} enumeration value, {1}, is invalid..

Looks up a localized string similar to The {0} enumeration value, {1}, is not supported by the {2} method..

Looks up a localized string similar to '{0}' is an invalid user defined type, reason: {1}..

Looks up a localized string similar to range: 0-8000.

Looks up a localized string similar to no UDT attribute.