用户定义类型编码

Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute 将 Point UDT 的存储格式设置为 Native。IsByteOrdered 设置为 true，这样可以保证在 SQL Server 中的比较结果相同，就像在托管代码中进行相同的比较一样。UDT 实现 System.Data.SqlTypes.INullable 接口以使 UDT 能够识别 Null 值。

下面的代码段显示了 Point UDT 的属性。

<Serializable(), SqlUserDefinedTypeAttribute(Format.Native, _
  IsByteOrdered:=True)> _
  Public Structure Point
    Implements INullable

[Serializable]
[Microsoft.SqlServer.Server.SqlUserDefinedType(Format.Native,
  IsByteOrdered=true)]
public struct Point : INullable
{

在下面的示例中，is_Null 变量是私有的并且保存了 UDT 实例的 Null 状态。您的代码必须保留 is_Null 的相应值。UDT 还必须具有一个名为 Null 的静态属性，该属性返回 UDT 的 Null 值实例。这样，如果该实例在数据库中确实为 Null，UDT 便可返回 Null 值。

Private is_Null As Boolean

Public ReadOnly Property IsNull() As Boolean _
   Implements INullable.IsNull
    Get
        Return (is_Null)
    End Get
End Property

Public Shared ReadOnly Property Null() As Point
    Get
        Dim pt As New Point
        pt.is_Null = True
        Return (pt)
    End Get
End Property

private bool is_Null;

public bool IsNull
{
    get
    {
        return (is_Null);
    }
}

public static Point Null
{
    get
    {
        Point pt = new Point();
        pt.is_Null = true;
        return pt;
    }
}

假定有一个表包含架构 Points(id int, location Point)，其中 Point 为 CLR UDT，并且有如下查询：

--Query 1
SELECT ID
FROM Points
WHERE NOT (location IS NULL) -- Or, WHERE location IS NOT NULL

--Query 2:
SELECT ID
FROM Points
WHERE location.IsNull = 0

这两个查询都返回具有非 Null 位置的点的 ID。在 Query 1 中，使用的是正常 Null 处理方法，不需要反序列化 UDT。另一方面，Query 2 必须反序列化每个非 Null 对象并调入 CLR 以获取 IsNull 属性的值。显然，使用 IS NULL 会产生更高的性能，并且始终都不应从 Transact-SQL 代码中读取 UDT 的 IsNull 属性。

那么，IsNull 属性的用途是什么？首先，从 CLR 代码中确定值是否为 Null 时需要它。其次，服务器需要使用一种方法来测试实例是否为 Null，因此服务器会使用该属性。服务器确定该实例为 Null 之后，便可以使用其本机 Null 处理方法对该实例进行处理。

下面的代码段显示了 Point 类的声明，该声明指定了 ValidatePoint 的 ValidationMethodName。

<Serializable(), SqlUserDefinedTypeAttribute(Format.Native, _
  IsByteOrdered:=True, _
  ValidationMethodName:="ValidatePoint")> _
  Public Structure Point

[Serializable]
[Microsoft.SqlServer.Server.SqlUserDefinedType(Format.Native,
  IsByteOrdered=true, 
  ValidationMethodName = "ValidatePoint")]
public struct Point : INullable
{

如果指定了验证方法，则必须具有如下面的代码段所示的签名。

Private Function ValidationFunction() As Boolean
    If (validation logic here) Then
        Return True
    Else
        Return False
    End If
End Function
private bool ValidationFunction()
{
    if (validation logic here)
    {
        return true;
    }
    else
    {
        return false;
    }
}

验证方法可具有任意作用域，如果值有效，它应返回 true，否则应返回 false。如果此方法返回 false 或引发异常，则该值将被视为无效并且会出现错误。

在下面的示例中，代码仅允许零值或大于 X 和 Y 坐标的值。

Private Function ValidatePoint() As Boolean
    If (_x >= 0) And (_y >= 0) Then
        Return True
    Else
        Return False
    End If
End Function

private bool ValidatePoint()
{
    if ((_x >= 0) && (_y >= 0))
    {
        return true;
    }
    else
    {
        return false;
    }
}

服务器是在执行转换时调用验证方法，而不是在通过设置个别属性插入数据时或在使用 Transact-SQL INSERT 语句插入数据时调用验证方法。

如果希望在所有情况下都执行验证方法，则您必须从属性 setter 中显式调用该验证方法，并且须调用 Parse 方法。并不要求这样做，在某些情况下可能甚至不需要这样做。

为确保在 Point 类中调用了 ValidatePoint 方法，您必须从 Parse 方法中以及设置 X 和 Y 坐标值的属性过程中调用它。下面的代码段显示了如何从 Parse 函数中调用 ValidatePoint 验证方法。

<SqlMethod(OnNullCall:=False)> _
Public Shared Function Parse(ByVal s As SqlString) As Point
    If s.IsNull Then
        Return Null
    End If

    ' Parse input string here to separate out points.
    Dim pt As New Point()
    Dim xy() As String = s.Value.Split(",".ToCharArray())
    pt.X = Int32.Parse(xy(0))
    pt.Y = Int32.Parse(xy(1))

    ' Call ValidatePoint to enforce validation
    ' for string conversions.
    If Not pt.ValidatePoint() Then
        Throw New ArgumentException("Invalid XY coordinate values.")
    End If
    Return pt
End Function

[SqlMethod(OnNullCall = false)]
public static Point Parse(SqlString s)
{
    if (s.IsNull)
        return Null;

    // Parse input string to separate out points.
    Point pt = new Point();
    string[] xy = s.Value.Split(",".ToCharArray());
    pt.X = Int32.Parse(xy[0]);
    pt.Y = Int32.Parse(xy[1]);

    // Call ValidatePoint to enforce validation
    // for string conversions.
    if (!pt.ValidatePoint()) 
        throw new ArgumentException("Invalid XY coordinate values.");
    return pt;
}

下面的代码段显示了如何从设置 X 和 Y 坐标的属性过程中调用 ValidatePoint 验证方法。

Public Property X() As Int32
    Get
        Return (Me._x)
    End Get

    Set(ByVal Value As Int32)
        Dim temp As Int32 = _x
        _x = Value
        If Not ValidatePoint() Then
            _x = temp
            Throw New ArgumentException("Invalid X coordinate value.")
        End If
    End Set
End Property

Public Property Y() As Int32
    Get
        Return (Me._y)
    End Get

    Set(ByVal Value As Int32)
        Dim temp As Int32 = _y
        _y = Value
        If Not ValidatePoint() Then
            _y = temp
            Throw New ArgumentException("Invalid Y coordinate value.")
        End If
    End Set
End Property

    public Int32 X
{
    get
    {
        return this._x;
    }
    // Call ValidatePoint to ensure valid range of Point values.
    set 
    {
        Int32 temp = _x;
        _x = value;
        if (!ValidatePoint())
        {
            _x = temp;
            throw new ArgumentException("Invalid X coordinate value.");
        }
    }
}

public Int32 Y
{
    get
    {
        return this._y;
    }
    set
    {
        Int32 temp = _y;
        _y = value;
        if (!ValidatePoint())
        {
            _y = temp;
            throw new ArgumentException("Invalid Y coordinate value.");
        }
    }
}

Point 类包含三个用于计算距离的简单方法：Distance、DistanceFrom 和 DistanceFromXY。每个方法均返回一个 double，分别计算的是从 Point 到零的距离，从指定点到 Point 的距离，以及从指定的 X 和 Y 坐标到 Point 的距离。Distance 和 DistanceFrom 均调用 DistanceFromXY，并演示如何对每个方法使用不同的参数。

' Distance from 0 to Point.
<SqlMethod(OnNullCall:=False)> _
Public Function Distance() As Double
    Return DistanceFromXY(0, 0)
End Function

' Distance from Point to the specified point.
<SqlMethod(OnNullCall:=False)> _
Public Function DistanceFrom(ByVal pFrom As Point) As Double
    Return DistanceFromXY(pFrom.X, pFrom.Y)
End Function

' Distance from Point to the specified x and y values.
<SqlMethod(OnNullCall:=False)> _
Public Function DistanceFromXY(ByVal ix As Int32, ByVal iy As Int32) _
    As Double
    Return Math.Sqrt(Math.Pow(ix - _x, 2.0) + Math.Pow(iy - _y, 2.0))
End Function

// Distance from 0 to Point.
[SqlMethod(OnNullCall = false)]
public Double Distance()
{
    return DistanceFromXY(0, 0);
}

// Distance from Point to the specified point.
[SqlMethod(OnNullCall = false)]
public Double DistanceFrom(Point pFrom)
{
    return DistanceFromXY(pFrom.X, pFrom.Y);
}

// Distance from Point to the specified x and y values.
[SqlMethod(OnNullCall = false)]
public Double DistanceFromXY(Int32 iX, Int32 iY)
{
    return Math.Sqrt(Math.Pow(iX - _x, 2.0) + Math.Pow(iY - _y, 2.0));
}

Microsoft.SqlServer.Server.SqlMethodAttribute 类提供了一些自定义属性，这些属性可用于标记方法定义以便指定 Null 调用行为的确定性以及指定方法是否为赋值函数。使用的是这些属性的默认值，仅在需要非默认值时才使用自定义特性。

注意
SqlMethodAttribute 类继承自 SqlFunctionAttribute 类，因此 SqlMethodAttribute 继承了 SqlFunctionAttribute 中的 FillRowMethodName 和 TableDefinition 字段。这意味着可以编写一个不属于此情况的表值方法。该方法能够编译并且程序集也能够部署，但在运行时将出现与 IEnumerable 返回类型有关的错误，错误消息为：“程序集 '<assembly>' 中类 '<class>' 的方法、属性或字段 '<name>' 具有无效的返回类型”。

下表说明了可以在 UDT 方法中使用的部分相关 Microsoft.SqlServer.Server.SqlMethodAttribute 属性，并列出了其默认值。

• DataAccess
  指示函数是否需要访问存储在 SQL Server 的本地实例中的用户数据。默认值为 DataAccessKind.None。

• IsDeterministic
  指示在输入值相同且数据库状态相同的情况下函数是否会生成相同的输出值。默认值为 false。

• IsMutator
  指示方法是否在 UDT 实例中引起状态变化。默认值为 false。

• IsPrecise
  指示函数是否涉及不精确的计算，如浮点运算。默认值为 false。

• OnNullCall
  指示在指定 Null 引用输入参数时是否调用此方法。默认值为 true。

使用 Microsoft.SqlServer.Server.SqlMethodAttribute.IsMutator 属性可以标记允许 UDT 实例状态改变的方法。Transact-SQL 不允许在一个 UPDATE 语句的 SET 子句中设置两个 UDT 属性。然而，您可以将一个方法标记为更改两个成员的赋值函数。

注意
在查询中不允许使用赋值函数方法。这些方法只能在赋值语句或数据修改语句中调用。如果标记为赋值函数的方法不返回 void（在 Visual Basic 中则是不为 Sub），则 CREATE TYPE 将失败并出错。

下面的语句假定存在一个具有 Rotate 方法的 Triangles UDT。下面的 Transact-SQL 更新语句调用该 Rotate 方法：

UPDATE Triangles SET t.RotateY(0.6) WHERE id=5

Rotate 方法是使用将 IsMutator 设置为 true 的 SqlMethod 属性来修饰的，因此 SQL Server 可以将该方法标记为赋值函数方法。该代码还将 OnNullCall 设置为 false，这将向服务器指示，如果任何输入参数为 Null 引用，该方法将返回 Null 引用（在 Visual Basic 中为 Nothing）。

<SqlMethod(IsMutator:=True, OnNullCall:=False)> _
Public Sub Rotate(ByVal anglex as Double, _
  ByVal angley as Double, ByVal anglez As Double) 
   RotateX(anglex)
   RotateY(angley)
   RotateZ(anglez)
End Sub

[SqlMethod(IsMutator = true, OnNullCall = false)]
public void Rotate(double anglex, double angley, double anglez) 
{
   RotateX(anglex);
   RotateY(angley);
   RotateZ(anglez);
}

从 SQL Server 2005 开始，随 SQL Server 安装的 CLR 示例附带了 Currency UDT。有关如何安装 CLR 示例的信息，请参阅安装 SQL Server 示例和示例数据库的注意事项。

Currency UDT 支持采用特定区域性的货币体系来处理货币金额。您必须定义两个字段：一个表示 CultureInfo 的 string，用于指定货币的发行者（例如 en-us）；一个表示 CurrencyValue 的 decimal，即货币金额。

尽管服务器并不使用它来执行比较，但 Currency UDT 实现了 System.IComparable 接口，该接口公开了一个方法 System.IComparable.CompareTo。在需要精确比较或排序区域性中的货币值的情况下，在客户端会使用此方法。

在 CLR 中运行的代码将区域性与货币值分开比较。对于 Transact-SQL 代码，通过执行下列操作来确定如何比较：

1. 将 IsByteOrdered 属性设置为 True，它指示 SQL Server 使用磁盘上的持久化二进制表示形式进行比较。

2. 使用 Currency UDT 的 Write 方法确定 UDT 在磁盘上的保留方式，从而确定 Transact-SQL 运算如何比较和排序 UDT 值。

3. 采用以下二进制格式保存 Currency UDT：

   1. 将区域性另存为 UTF-16 编码的字符串并用第 0-19 个字节表示，右侧以 Null 字符填充。

   2. 使用第 20 个字节及以后的字节包含货币的十进制值。

填充的目的是为了确保区域性与货币值完全分开，以便在 Transact-SQL 代码中将一个 UDT 与另一个 UDT 进行比较时，区域性字节与区域性字节相比较，货币字节值与货币字节值相比较。

如需 Currency UDT 的完整代码列表，请按照安装 SQL Server 示例和示例数据库的注意事项中有关安装 CLR 示例的说明进行操作。

Currency UDT 定义有以下属性。

<Serializable(), Microsoft.SqlServer.Server.SqlUserDefinedType( _
    Microsoft.SqlServer.Server.Format.UserDefined, _
    IsByteOrdered:=True, MaxByteSize:=32), _
    CLSCompliant(False)> _
Public Structure Currency
Implements INullable, IComparable, _
Microsoft.SqlServer.Server.IBinarySerialize

[Serializable]
[SqlUserDefinedType(Format.UserDefined, 
    IsByteOrdered = true, MaxByteSize = 32)]
    [CLSCompliant(false)]
    public struct Currency : INullable, IComparable, IBinarySerialize
    {