Codifica dei tipi definiti dall'utente

Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute imposta il formato di archiviazione per il tipo definito dall'utente Point su Native. IsByteOrdered viene impostato su true e garantisce che i risultati dei confronti siano uguali in SQL Server, come se nel codice gestito fosse stato effettuato lo stesso confronto. Il tipo definito dall'utente implementa l'interfaccia System.Data.SqlTypes.INullable che fornisce il supporto dei valori Null.

Nel frammento di codice seguente sono mostrati gli attributi per il tipo definito dall'utente 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
{

Nell'esempio seguente la variabile is_Null è privata e mantiene lo stato Null per l'istanza del tipo definito dall'utente. Il codice deve gestire un valore appropriato per is_Null. Il tipo definito dall'utente deve anche disporre di una proprietà statica denominata Null che restituisce un'istanza con valore Null del tipo definito dall'utente. In questo modo il tipo definito dall'utente può restituire un valore Null se l'istanza è Null nel database.

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

Si consideri una tabella contenente lo schema Points(id int, location Point), dove Point è un tipo CLR definito dall'utente, e le query seguenti:

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

Entrambe le query restituiscono gli ID dei punti con posizioni non Null. Nella Query 1 viene utilizzata la normale gestione dei valori Null e non è necessaria la deserializzazione dei tipi definiti dall'utente. Nella Query 2, d'altra parte, è necessario deserializzare tutti gli oggetti non Null ed effettuare una chiamata in CLR per ottenere il valore della proprietà IsNull. Chiaramente, IS NULL offrirà prestazioni migliori e pertanto non dovrebbe esistere alcun motivo per leggere la proprietà IsNull di un tipo definito dall'utente dal codice Transact-SQL.

L'utilizzo della proprietà IsNull è innanzitutto necessario per determinare se un valore è Null dal codice CLR. In secondo luogo, questa proprietà viene utilizzata dal server per verificare se un'istanza è Null. Una volta stabilito che è Null, il server sarà in grado di utilizzare la relativa funzionalità di gestione nativa dei valori Null per gestirla.

Nel frammento di codice seguente è riportata la dichiarazione per la classe Point che specifica ValidationMethodName di 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
{

Se si specifica un metodo di convalida, è necessario che includa una firma simile al frammento di codice seguente:

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

Il metodo di convalida può disporre di qualsiasi ambito e deve restituire true se il valore è valido e false in caso contrario. Se il metodo restituisce false o genera un'eccezione, il valore viene considerato non valido e viene generato un errore.

Nell'esempio riportato di seguito il codice accetta solo valori pari a zero o superiori per le coordinate X e 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;
    }
}

Il server chiama il metodo di convalida durante l'esecuzione delle conversioni e non quando i dati vengono inseriti impostando singole proprietà o utilizzando un'istruzione INSERT Transact-SQL.

Se si desidera che il metodo di convalida venga eseguito in tutte le situazioni, è necessario chiamarlo in modo esplicito dai metodi per l'impostazione delle proprietà e dal metodo Parse. Questa operazione non è obbligatoria e in alcuni casi può essere anche sconsigliata.

Per assicurarsi che il metodo ValidatePoint venga richiamato nella classe Point, è necessario chiamarlo dal metodo Parse e dalle routine delle proprietà che impostano i valori delle coordinate X e Y. Nel frammento di codice seguente viene illustrato come chiamare il metodo di convalida ValidatePoint dalla funzione 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;
}

Nel frammento di codice seguente viene illustrato come chiamare il metodo di convalida ValidatePoint dalle routine delle proprietà che impostano le coordinate X e 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.");
        }
    }
}

La classe Point contiene tre metodi semplici per il calcolo della distanza, ovvero Distance, DistanceFrom e DistanceFromXY. Ognuno di essi restituisce un valore double che calcola la distanza da Point a zero, la distanza da un punto specificato a Point e la distanza dalle coordinate X e Y specificate a Point. I metodi Distance e DistanceFrom chiamano ognuno DistanceFromXY e dimostrano in che modo utilizzare i diversi argomenti per ogni metodo.

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

La classe Microsoft.SqlServer.Server.SqlMethodAttribute fornisce attributi personalizzati che possono essere utilizzati per contrassegnare le definizioni di metodo allo scopo di specificare il determinismo, il comportamento in caso di chiamate Null e per indicare se un metodo è di tipo mutatore. Per queste proprietà si presuppone l'uso dei valori predefiniti e l'attributo personalizzato viene utilizzato solo quando è necessario un valore non predefinito.

Nella tabella seguente sono descritte alcune delle proprietà Microsoft.SqlServer.Server.SqlMethodAttribute rilevanti che possono essere utilizzate nei metodi UDT con i relativi valori predefiniti.

• DataAccess
  Indica se la funzione comporta l'accesso ai dati dell'utente archiviati nell'istanza locale di SQL Server. Il valore predefinito è DataAccessKind.None.

• IsDeterministic
  Indica se la funzione produce gli stessi valori di output quando vengono specificati gli stessi valori di input e lo stesso stato del database. Il valore predefinito è false.

• IsMutator
  Indica se il metodo causa una modifica dello stato dell'istanza UDT. Il valore predefinito è false.

• IsPrecise
  Indica se la funzione comporta calcoli imprecisi, quali operazioni a virgola mobile. Il valore predefinito è false.

• OnNullCall
  Indica se il metodo viene chiamato quando vengono specificati argomenti di input con riferimento Null. Il valore predefinito è true.

La proprietà Microsoft.SqlServer.Server.SqlMethodAttribute.IsMutator consente di contrassegnare un metodo che supporta le modifiche allo stato di un'istanza di un tipo definito dall'utente. Transact-SQL non consente di impostare due proprietà UDT nella clausola SET di un'istruzione UPDATE. È tuttavia possibile contrassegnare un metodo come mutatore che modifica i due membri.

Nell'istruzione seguente si presuppone l'esistenza di un tipo definito dall'utente Triangles con un metodo Rotate. Nell'istruzione di aggiornamento Transact-SQL seguente viene richiamato il metodo Rotate:

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

Il metodo Rotate è decorato con l'impostazione dell'attributo SqlMethodIsMutator su true in modo che SQL Server possa contrassegnare il metodo come metodo mutatore. Il codice imposta anche OnNullCall su falseche indica al server che il metodo restituisce un riferimento Null (Nothing in Visual Basic) se uno dei parametri di input è un riferimento 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);
}

Il tipo definito dall'utente Currency è incluso negli esempi CLR che possono essere installati con SQL Server a partire da SQL Server 2005. Per informazioni sull'installazione degli esempi CLR, vedere Considerazioni per l'installazione di esempi e di database di esempio di SQL Server.

Il tipo definito dall'utente Currency supporta la gestione degli importi nel sistema monetario di specifiche impostazioni cultura. È necessario definire due campi, ovvero un campo string per l'oggetto CultureInfo che specifica il paese che ha emesso la valuta, ad esempio it-it, e un campo decimal per l'oggetto CurrencyValue che indica l'importo.

Anche se non utilizzato dal server per i confronti, il tipo definito dall'utente Currency implementa l'interfaccia System.IComparable che espone un singolo metodo, System.IComparable.CompareTo. Tale metodo viene utilizzato sul lato client nelle situazioni in cui è consigliabile confrontare o ordinare i valori relativi alla valuta in modo accurato all'interno delle diverse impostazioni cultura.

Il codice eseguito in CLR confronta le impostazioni cultura separatamente dal valore della valuta. Per il codice Transact-SQL, il confronto viene determinato dalle azioni seguenti:

1. Impostare l'attributo IsByteOrdered su True per indicare a SQL Server di utilizzare la rappresentazione binaria persistente su disco per i confronti.

2. Utilizzare il metodo Write per il tipo definito dall'utente Currency per stabilire in che modo rendere tale tipo persistente su disco e confrontarne e ordinarne i valori per le operazioni Transact-SQL.

3. Salvare il tipo definito dall'utente Currency utilizzando il formato binario seguente:

   1. Salvare le impostazioni cultura come stringa codificata UTF-16 per i byte 0-19 con riempimento a destra con caratteri Null.

   2. Utilizzare i byte 20 e successivi per contenere il valore decimale della valuta.

Lo scopo del riempimento è assicurare che le impostazioni cultura vengano separate completamente dal valore di valuta, in modo che quando un tipo definito dall'utente viene confrontato con un altro tipo nel codice Transact-SQL, i byte delle impostazioni cultura vengono confrontati con i byte delle impostazioni cultura e i valori dei byte della valuta vengono confrontati con i valori dei byte della valuta.

Per il listato di codice completo per l'UDT Currency, seguire le istruzioni per l'installazione degli esempi CLR in Considerazioni per l'installazione di esempi e di database di esempio di SQL Server.

L'UDT Currency viene definito con gli attributi seguenti:

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