Programmieren benutzerdefinierter Typen

Mit dem Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute-Attribut wird das Speicherformat für den Point-UDT auf Native festgelegt. IsByteOrdered wird auf true festgelegt, womit garantiert ist, dass Vergleiche in SQL Server zu denselben Resultaten führen wie entsprechende Vergleiche in verwaltetem Code. Der UDT implementiert die System.Data.SqlTypes.INullable-Schnittstelle, damit der UDT NULL erkennt.

Das folgende Codefragment zeigt die Attribute für den 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
{

Im folgenden Beispiel ist die is_Null-Variable privat und enthält für die Instanz des UDT den Status NULL. Im Code muss ein entsprechender Wert für is_Null verwaltet werden. Der UDT muss auch über eine statische Eigenschaft namens Null verfügen, welche die NULL-Wertinstanz des UDTs zurückgibt. Dadurch kann der UDT einen NULL-Wert zurückgeben, wenn die Instanz auch in der Datenbank tatsächlich NULL ist.

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

Betrachten Sie eine Tabelle, die das Schema Points(id int, location Point), wobeiPoint ein CLR UDT ist, und die folgenden Abfragen enthält:

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

Beide Abfragen geben die IDs von Punkten mit Positionen ungleich Null zurück. In Abfrage 1 wird die normale NULL-Behandlung verwendet, und dort ist keine Deserialisierung von UDTs erforderlich. In Abfrage 2 dagegen muss jedes Objekt, das nicht Null ist, deserialisiert und die CLR aufgerufen werden, um den Wert der IsNull-Eigenschaft zu erhalten. Der Einsatz von IS NULL zeigt eindeutig ein besseres Leistungsverhalten, und es sollte nie notwendig sein, die IsNull-Eigenschaft eines UDT über Transact-SQL-Code abzurufen.

Wozu dient also die IsNull-Eigenschaft? Erstens wird sie benötigt, damit im CLR-Code bestimmt werden kann, ob ein Wert Null ist. Zweitens muss der Server prüfen können, ob eine Instanz Null ist, und hierzu wird diese Eigenschaft vom Server verwendet. Sobald der Server bestimmt hat, dass die Instanz UDT Null ist, kann er seine systemeigene NULL-Behandlung verwenden.

Das folgende Codefragment zeigt die Deklaration für die Point-Klasse, die mit ValidationMethodName als Validierungsmethode ValidatePoint angibt.

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

Wenn eine Validierungsmethode angegeben wird, muss diese eine Signatur aufweisen, die etwa folgendem Codefragment entspricht:

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

Die Validierungsmethode kann einen beliebigen Gültigkeitsbereich haben und sollte true zurückgeben, wenn der Wert zulässig ist, und andernfalls false. Wenn die Methode false zurückgibt oder eine Ausnahme auslöst, wird der Wert als nicht zulässig behandelt, und es wird ein Fehler generiert.

Im nachstehenden Beispiel lässt der Code für die X- und Y-Koordinaten nur Werte zu, die größer oder gleich Null sind.

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

Der Server ruft die Validierungsmethode auf, wenn er Konvertierungen durchführt, nicht wenn Daten durch das Festlegen einzelner Eigenschaften oder mithilfe der Transact-SQL-Anweisung INSERT eingefügt werden.

Sie müssen die Validierungsmethode explizit innerhalb der Methoden zum Festlegen von Eigenschaften und der Parse-Methode aufrufen, wenn diese Methode alle Werte überprüfen soll. Dies ist keine Voraussetzung, und in einigen Fällen ist es möglicherweise nicht einmal wünschenswert.

Um sicherzustellen, dass die ValidatePoint-Methode in der Point-Klasse aufgerufen wird, muss sie innerhalb der Parse-Methode und den Eigenschaftenprozeduren, mit denen die X- und X-Koordinatenwerte festgelegt werden, aufgerufen werden. Das folgende Codefragment zeigt, wie die Validierungsmethode ValidatePoint von der Parse-Funktion aufgerufen wird.

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

Das folgende Codefragment zeigt, wie die Validierungsmethode ValidatePoint von den Eigenschaftenprozeduren aufgerufen wird, mit denen die X- und Y-Koordinaten festgelegt werden.

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

Die Point-Klasse enthält drei einfache Methoden zum Berechnen von Entfernung: Distance, DistanceFrom und DistanceFromXY. Jede dieser Methoden gibt einen Wert vom Typ double zurück, wobei die Entfernung von Point zum Nullpunkt, die Entfernung von einem angegebenen Punkt zu Pointund die Entfernung von den angegebenen X- und Y-Koordinaten zu Point berechnet wird Distance und DistanceFrom rufen jeweils DistanceFromXY auf und veranschaulichen, wie für jede Methode andere Argumente verwendet werden.

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

Die Microsoft.SqlServer.Server.SqlMethodAttribute-Klasse stellt benutzerdefinierte Attribute zur Verfügung, mit denen Methodendefinitionen markiert werden können, um einen Determinismus anzugeben, das Verhalten beim Aufruf für NULL-Werte festzulegen und anzugeben, ob eine Methode eine Mutatormethode ist. Bei diesen Eigenschaften werden die Standardwerte vorausgesetzt, und das benutzerdefinierte Attribut wird nur verwendet, wenn ein anderer Wert als der Standardwert erforderlich ist.

Hinweis

Die SqlMethodAttribute-Klasse erbt von der SqlFunctionAttribute-Klasse, daher erbt die SqlMethodAttribute-Klasse die Felder FillRowMethodName und TableDefinition von SqlFunctionAttribute. Dies impliziert, dass es möglich ist, eine Tabellenwertmethode zu schreiben. Dies ist jedoch nicht der Fall. Die Methode wird kompiliert und die Assembly wird verteilt, aber zur Laufzeit wird ein Fehler zum IEnumerable-Rückgabetyp erzeugt, der folgende Fehlermeldung enthält: "Die Methode, die Eigenschaft oder das Feld '<name>' in der '<class>'-Klasse in der '<assembly>'-Assembly weist einen ungültigen Rückgabetyp auf."

In der folgenden Tabelle werden einige der relevanten Microsoft.SqlServer.Server.SqlMethodAttribute-Eigenschaften beschrieben, die in UDT-Methoden verwendet werden können, und die zugehörigen Standardwerte aufgeführt.

• DataAccess
  Gibt an, ob die Funktion auf die in der lokalen Instanz von SQL Server gespeicherten Benutzerdaten zugreift. Der Standardwert lautet DataAccessKind.None.

• IsDeterministic
  Gibt an, ob die Funktion bei denselben Eingabewerten und demselben Datenbankzustand auch immer dieselben Ausgabewerte erzeugt. Der Standardwert lautet false.

• IsMutator
  Gibt an, ob die Methode eine Statusänderung in der UDT-Instanz verursacht. Der Standardwert lautet false.

• IsPrecise
  Gibt an, ob die Funktion ungenaue Berechnungen beeinhaltet, z. B. Gleitkommaoperationen. Der Standardwert lautet false.

• OnNullCall
  Gibt an, ob die Methode aufgerufen wird, wenn als Eingabeargumente NULL-Verweise angegeben werden. Der Standardwert lautet true.

Mithilfe der Microsoft.SqlServer.Server.SqlMethodAttribute.IsMutator-Eigenschaft können Sie eine Methode markieren, die bei einer Instanz eines UDTs eine Statusänderung zulässt. Transact-SQL lässt nicht zu, dass zwei UDT-Eigenschaften in der SET-Klausel einer UPDATE-Anweisung festgelegt werden. Sie können jedoch eine Methode als Mutator markieren, die zwei Elemente ändert.

Hinweis
In Abfragen sind Mutatormethoden nicht zulässig. Sie können nur in Zuweisungsanweisungen oder Datenänderungsanweisungen aufgerufen werden. Wenn eine als Mutatormethode gekennzeichnete Methode nicht void zurückgibt (oder kein Sub in Visual Basic ist), führt CREATE TYPE zu einem Fehler.

Die folgende Anweisung setzt die Existenz des UDTs Triangles voraus, der über die Rotate-Methode verfügt. In der folgenden Transact-SQL-Anweisung UPDATE wird die Rotate-Methode aufgerufen:

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

Die Rotate-Methode ist mit dem SqlMethod-Attribut ausgezeichnet, mit dem IsMutator auf true festgelegt wird, sodass SQL Server die Methode als Mutatormethode markieren kann. Im Code wird zudem OnNullCall auf false festgelegt. Dem Server wird damit angegeben, dass die Methode einen NULL-Verweis (Nothing in Visual Basic) zurückgibt, wenn einer der Eingabeparameter einen NULL-Verweis enthält.

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

Der UDT Currency ist seit SQL Server 2005 in den CLR-Beispielen enthalten, die zusammen mit SQL Server installiert werden können. Informationen zur Installation der CLR-Beispiele finden Sie unter Überlegungen zum Installieren der SQL Server-Beispiele und -Beispieldatenbanken.

Der UDT Currency kann Währungsbeträge im Währungssystem eines bestimmten Lands handhaben. Sie müssen zwei Felder definieren: ein string-Feld für CultureInfo, das angibt, welches Land die Währung ausgegeben hat (beispielsweise en-us) und ein decimal-Feld für CurrencyValue, den Währungsbetrag.

Obwohl sie vom Server nicht um Durchführen von Vergleichen verwendet wird, implementiert der UDT Currency die System.IComparable-Schnittstelle, die nur eine Methode namens System.IComparable.CompareTo bereitstellt. Diese Methode wird auf Clientseite in Situationen verwendet, in denen Currency-Werte genau verglichen oder geordnet werden sollen.

Im Code, der in der CLR ausgeführt wird, wird die Länderangabe getrennt vom Währungswert verglichen. Im Transact-SQL-Code bestimmen die folgenden Aktionen den Vergleich:

1. Legen Sie das IsByteOrdered-Attribut auf true fest, um SQL Server anzuweisen, die auf dem Datenträger gespeicherte binäre Darstellung für Vergleiche zu verwenden.

2. Bestimmen Sie mithilfe der Write-Methode für den UDT Currency, wie der UDT auf dem Datenträger gespeichert wird und wie die UDT-Werte infolgedessen in Transact-SQL-Vorgängen verglichen und angeordnet werden.

3. Speichern Sie den UDT Currency im folgenden binären Format:

   1. Speichern Sie die Länderangabe als UTF-16-codierte Zeichenfolge für die Bytes 0 bis 19, wobei die Zeichenfolge rechts mit NULL-Zeichen aufgefüllt werden soll.

   2. Verwenden Sie Bytes 20 und nachfolgende Bytes zum Speichern des Dezimalwerts der Währungsbetrags.

Durch das Auffüllen mit NULL-Zeichen wird gewährleistet, dass die Länderangabe vollständig vom Währungsbetrag getrennt ist, sodass beim Vergleich zweier UDT-Werte im Transact-SQL-Code jeweils die Bytes mit den Länderangaben und die Bytes mit den Währungsbeträgen miteinander verglichen.

Sie erhalten den vollständigen Code für den UDT Currency, wenn Sie die Anleitungen zur Installation der CLR-Beispiele in Überlegungen zum Installieren der SQL Server-Beispiele und -Beispieldatenbanken befolgen.

Der UDT Currency wurde mit den folgenden Attributen definiert.

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