Разработка кода для определяемых пользователем типов

Метод Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute задает для определяемого пользователем типа Point формат хранения Native. Свойству IsByteOrdered присваивается значение true, а это гарантирует, что результаты сравнения в SQL Server будут такими же, как если бы сравнение проводилось в управляемом коде. Определяемый пользователем тип реализует интерфейс System.Data.SqlTypes.INullable, чтобы определяемый пользователем тип мог работать со значениями NULL.

В следующем фрагменте кода показаны атрибуты определяемого пользователем типа Point.

<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 является закрытой и хранит состояние NULL экземпляра определяемого пользователем типа. В программном коде должно поддерживаться соответствующее значение переменной is_Null. Определяемый пользователем тип должен также иметь статическое свойство с именем Null, возвращающее экземпляр определяемого пользователем типа со значением (равным NULL). Это позволяет возвращать значение NULL в определяемом пользователем типе, если экземпляр в базе данных действительно равен 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, и следующие запросы:

--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. В запросе 1 используется нормальная обработка значений NULL, а десериализация определяемых пользователем типов не требуется. С другой стороны, в запросе 2 приходится обеспечивать десериализацию каждого объекта, отличного от Null, и вызывать среду CLR для получения значения свойства IsNull. Очевидно, что использование IS NULL позволяет достичь более высокой производительности, поэтому нет никакого смысла прибегать к чтению значения свойства IsNull определяемого пользователем типа из кода Transact-SQL.

Так для чего же используется свойство IsNull? Во-первых, для определения того, получено ли значение Null из кода CLR. Во-вторых, серверу требуется способ проверки того, имеет ли экземпляр значение Null, поэтому это свойство также используется сервером. После определения, что экземпляр действительно равен Null, сервер может использовать собственные методы работы со значениями NULL.

В следующем фрагменте кода для класса Point показана декларация, которая задает свойство ValidationMethodName метода ValidatePoint.

<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.

Если требуется, чтобы метод задания свойства вызывался во всех ситуациях, необходимо явным образом вызывать его из методов, присваивающих значение свойству, и метода Parse. Это не является требованием и в некоторых случаях даже нежелательно.

Чтобы гарантировать вызов метода ValidatePoint в классе Point, следует вызывать его из метода Parse и процедур свойств, которые задают значения координат X и Y. В следующем фрагменте кода показан вызов метода проверки ValidatePoint из функции Parse.

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

В следующем фрагменте кода показан вызов метода проверки ValidatePoint из процедур свойств, задающих значения координат X и Y.

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 наследует поля FillRowMethodName и TableDefinition от класса SqlFunctionAttribute. Это подразумевает, что существует возможность написать возвращающий табличное значение метод, который не является вариантом. Метод компилируется, и сборка развертывается, но во время выполнения будет вызвана ошибка типа IEnumerable и выдано следующее сообщение: «Метод, свойство или поле "<имя>" класса "<класс>" в сборке "<сборка>" имеет недопустимый возвращаемый тип».

В следующей таблице рассматриваются некоторые важные свойства класса Microsoft.SqlServer.Server.SqlMethodAttribute, которые можно использовать для методов определяемого пользователем типа, и перечисляются их значения по умолчанию.

• DataAccess
  Указывает, что функция производит доступ к пользовательским данным, хранимым в локальном экземпляре SQL Server. Значение по умолчанию — DataAccessKind.None.

• IsDeterministic
  Указывает, производит ли функция одни и те же выходные значения при одинаковых наборах входных значений и одинаковых состояниях базы данных. Значение по умолчанию — false.

• IsMutator
  Указывает, вызывает ли метод изменение состояния экземпляра определяемого пользователем типа. Значение по умолчанию — false.

• IsPrecise
  Указывает, содержит ли функция вычисления с потерей точности (например, операции с плавающей запятой). Значение по умолчанию — false.

• OnNullCall
  Указывает, вызывается ли метод, если в качестве ссылки на входные аргументы заданы значения NULL. Значение по умолчанию — true.

Свойство Microsoft.SqlServer.Server.SqlMethodAttribute.IsMutator позволяет указать, что метод производит изменение состояния экземпляра определяемого пользователем типа. Язык Transact-SQL не позволяет задать два свойства определяемого пользователем типа в предложении SET одной инструкции UPDATE. Однако можно создать метод-мутатор, изменяющий два члена определяемого пользователем типа сразу.

Примечание
Методы-мутаторы в запросах не допускаются. Их можно вызывать только в инструкциях присваивания или изменения данных. Если метод, помеченный как мутатор, не возвращает void (или в языке Visual Basic не представляет собой Sub), то выполнение инструкции CREATE TYPE завершится с ошибкой.

Следующая инструкция подразумевает наличие определяемого пользователем типа Triangles, имеющего метод Rotate. В следующей инструкции изменения данных языка Transact-SQL вызывается метод Rotate:

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

Метод Rotate обозначается атрибутом SqlMethod со свойством IsMutator (равным true), так что SQL Server может пометить этот метод как мутатор. Кроме того, в данном коде для атрибута OnNullCall задается значение false, а это служит для сервера указанием, что метод возвращает ссылку, равную NULL (в языке Visual Basic — Nothing), если любой из входных параметров представляет собой ссылку, равную NULL.

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

Определяемый пользователем тип Currency входит в число образцов CLR, которые можно установить вместе с SQL Server (начиная с версии SQL Server 2005). Сведения об установке образцов CLR см. в разделе Вопросы установки образцов кода и образцов баз данных SQL Server.

Определяемый пользователем тип Currency поддерживает работу с денежными суммами в денежной системе конкретной культуры. Требуется указать два значения: значение типа string для поля CultureInfo, задающее источник определения валюты (например, en-us), и значение типа decimal для поля CurrencyValue, представляющего денежные суммы.

Определяемый пользователем тип Currency реализует интерфейс System.IComparable, предоставляющий единственный метод System.IComparable.CompareTo, хотя сервер не использует этот метод для операций сравнения. Он используется на клиенте в ситуациях, когда необходимо провести точное сравнение или сортировку значений денежных сумм внутри культур.

Код, работающий в среде CLR, сравнивает культуры отдельно от значений суммы. Для кода на языке Transact-SQL сравнение определяется следующими действиями.

1. Для атрибута IsByteOrdered задается значение true, а это служит для SQL Server указанием, что для сравнения необходимо использовать сохраненные на диске двоичные представления.

2. С помощью метода Write определяемого пользователем типа Currency определяется, как сохраняется значение данного типа на диске и, следовательно, как проводятся сравнение и сортировка данного типа в операциях языка Transact-SQL.

3. Значения определяемого пользователем типа Currency нужно сохранять в следующем двоичном формате.

   1. Культура сохраняется в виде строки в кодировке UTF-16 для байтов 0-19 с дополнением нулевыми символами справа.

   2. Байты с 20 и выше используются для сохранения десятичного значения денежной суммы.

Дополнение нужно для того, чтобы гарантировать полное отделение значения культуры от значения суммы. Тогда при сравнении одного значения определяемого пользователем типа с другим в коде Transact-SQL значение одной культуры можно будет побайтно сравнить со значением другой культуры, а значения байтов одной денежной суммы — со значениями байтов другой денежной суммы.

Для получения полного кода определяемого пользователем типа Currency выполните инструкции по установке образцов CLR, содержащиеся в разделе Вопросы установки образцов кода и образцов баз данных SQL Server.

Определяемый пользователем тип Currency содержит следующие атрибуты.

<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
    {