CLR skaláris értékű függvények

A következőkre vonatkozik:SQL Server

A skaláris értékű függvények (SVF) egyetlen értéket ad vissza, például egy sztringet, egész számot vagy bitértéket. A felügyelt kódban skaláris értékű, felhasználó által definiált függvényeket bármely .NET-keretrendszer programozási nyelv használatával létrehozhat. Ezek a függvények Transact-SQL vagy más felügyelt kód számára érhetők el. A közös nyelvi futtatókörnyezet (CLR) integrációjának előnyeiről, valamint a felügyelt kód és a Transact-SQL közötti választásról további információt CLR-integráció áttekintése.

A CLR skaláris értékű függvényeinek követelményei

A .NET-keretrendszer SVF-jei metódusként vannak implementálva egy osztályon egy .NET-keretrendszer-szerelvényben. A bemeneti paraméterek és az SVF-ből visszaadott típus az SQL Server által támogatott skaláris adattípusok bármelyike lehet, kivéve varchar, karakter, sorfordítási, szöveg, ntext, kép, időbélyeg, táblázatvagy kurzor. Az SVF-eknek biztosítaniuk kell az SQL Server adattípusának és a végrehajtási módszer visszatérési adattípusának egyezését. A típuskonvertálásokról további információt CLR-paraméteradatok leképezésecímű témakörben talál.

Ha .NET-keretrendszer SVF-et implementál egy .NET-keretrendszer nyelvén, megadhatja a SqlFunction egyéni attribútumot, amely további információkat tartalmaz a függvényről. A SqlFunction attribútum azt jelzi, hogy a függvény hozzáfér vagy módosítja-e az adatokat, ha determinisztikus, és hogy a függvény lebegőpontos műveleteket tartalmaz-e.

A skaláris értékű, felhasználó által definiált függvények determinisztikusak vagy nem determinisztikusak lehetnek. A determinisztikus függvények mindig ugyanazt az eredményt adják vissza, amikor egy adott bemeneti paraméterkészlettel hívják meg. A nem determinisztikus függvények eltérő eredményeket adhatnak vissza, ha egy adott bemeneti paraméterkészlettel hívják meg.

Jegyzet

Ne jelöljön meg egy függvényt determinisztikusként, ha a függvény nem mindig ugyanazokat a kimeneti értékeket állítja elő ugyanazokkal a bemeneti értékekkel és ugyanazzal az adatbázisállapotsal. A függvény determinisztikusként való megjelölése, ha a függvény nem igazán determinisztikus, sérült indexelt nézeteket és számított oszlopokat eredményezhet. Egy függvényt determinisztikusként jelölhet meg a IsDeterministic tulajdonság igaz értékre állításával.

Táblaértékkel megadott paraméterek

Az eljárásba vagy függvénybe átadott, felhasználó által definiált táblatípusok (TVP-k) hatékony módot biztosítanak több adatsor kiszolgálónak való átadására. A TVP-k hasonló funkciókat biztosítanak a paramétertömbökhöz, de nagyobb rugalmasságot és szorosabb integrációt biztosítanak a Transact-SQL-vel. Emellett a jobb teljesítmény lehetőségét is biztosítják.

A TVP-k emellett a kiszolgálóra történő oda-vissza utazások számának csökkentésében is segítenek. Ahelyett, hogy több kérést küldene a kiszolgálónak, például a skaláris paraméterek listájával, az adatokat tvP-ként is elküldheti a kiszolgálónak. A felhasználó által definiált táblatípus nem adható át táblaértékkel rendelkező paraméterként egy felügyelt tárolt eljárásnak vagy függvénynek, amely az SQL Server-folyamatban fut. További információ a TVP-kkel kapcsolatban: Táblaértékű paraméterek (adatbázismotor) használata.

Példa EGY CLR skaláris értékű függvényre

Íme egy egyszerű SVF, amely hozzáfér az adatokhoz, és egész számot ad vissza:

C#

using Microsoft.SqlServer.Server;
using System.Data.SqlClient;

public class T
{
    [SqlFunction(DataAccess = DataAccessKind.Read)]
    public static int ReturnOrderCount()
    {
        using (SqlConnection conn
            = new SqlConnection("context connection=true"))
        {
            conn.Open();
            SqlCommand cmd = new SqlCommand(
                "SELECT COUNT(*) AS 'Order Count' FROM SalesOrderHeader", conn);
            return (int)cmd.ExecuteScalar();
        }
    }
}

Visual Basic .NET-

Imports Microsoft.SqlServer.Server
Imports System.Data.SqlClient

Public Class T
    <SqlFunction(DataAccess:=DataAccessKind.Read)> _
    Public Shared Function ReturnOrderCount() As Integer
        Using conn As New SqlConnection("context connection=true")
            conn.Open()
            Dim cmd As New SqlCommand("SELECT COUNT(*) AS 'Order Count' FROM SalesOrderHeader", conn)
            Return CType(cmd.ExecuteScalar(), Integer)
        End Using
    End Function
End Class

Az első kódsor az attribútumok elérésére Microsoft.SqlServer.Server hivatkozik, és System.Data.SqlClient hozzáférni a ADO.NET névtérhez. (Ez a névtér SqlClient, az SQL Server .NET-keretrendszer adatszolgáltatóját tartalmazza.)

Ezután a függvény megkapja az SqlFunction egyéni attribútumot, amely a Microsoft.SqlServer.Server névtérben található. Az egyéni attribútum azt jelzi, hogy a felhasználó által definiált függvény (UDF) a folyamatban lévő szolgáltatót használja-e az adatok olvasására a kiszolgálón. Az SQL Server nem engedélyezi az UDF-ek számára az adatok frissítését, beszúrását és törlését. Az SQL Server optimalizálhatja a folyamaton belüli szolgáltatót nem használó UDF végrehajtását. Ezt a DataAccessKindDataAccessKind.Noneértékre állításával jelezzük. A következő sorban a célmetódus egy nyilvános statikus (a Visual Basic .NET-ben megosztva).

A Microsoft.SqlServer.Server névtérben található SqlContext osztály ezután hozzáférhet egy SqlCommand objektumhoz, amely már be van állítva az SQL Server-példányhoz való kapcsolattal. Bár itt nincs használatban, az aktuális tranzakciós környezet az System.Transactions alkalmazásprogramozási felületen (API) keresztül is elérhető.

A függvény törzsének legtöbb kódsorának ismerősnek kell lennie azoknak a fejlesztőknek, akik olyan ügyfélalkalmazásokat írnak, amelyek a System.Data.SqlClient névtérben található típusokat használják.

C#

using(SqlConnection conn = new SqlConnection("context connection=true"))
{
   conn.Open();
   SqlCommand cmd = new SqlCommand(
        "SELECT COUNT(*) AS 'Order Count' FROM SalesOrderHeader", conn);
   return (int) cmd.ExecuteScalar();
}

Visual Basic .NET-

Using conn As New SqlConnection("context connection=true")
   conn.Open()
   Dim cmd As New SqlCommand( _
        "SELECT COUNT(*) AS 'Order Count' FROM SalesOrderHeader", conn)
   Return CType(cmd.ExecuteScalar(), Integer)
End Using

A megfelelő parancsszöveg a SqlCommand objektum inicializálásával van megadva. Az előző példa megszámolja a SalesOrderHeadertábla sorainak számát. Ezután a cmd objektum ExecuteScalar metódusa lesz meghívva. Ez a lekérdezés alapján int típusú értéket ad vissza. Végül a rendelésszám vissza lesz adva a hívónak.

Ha a kód egy FirstUdf.cs nevű fájlba van mentve, az alábbi szerelvényként fordítható össze:

C#

csc.exe /t:library /out:FirstUdf.dll FirstUdf.cs

Visual Basic .NET-

vbc.exe /t:library /out:FirstUdf.dll FirstUdf.vb

/t:library azt jelzi, hogy végrehajtható helyett tárat kell létrehozni. A végrehajtható elemek nem regisztrálhatók az SQL Serveren.

A /clr:pure lefordított Visual C++ adatbázis-objektumok nem támogatottak az SQL Serveren való végrehajtáshoz. Az ilyen adatbázis-objektumok például skaláris értékű függvényeket tartalmaznak.

A szerelvény és az UDF regisztrálásához szükséges Transact-SQL lekérdezés és mintakérés a következő:

CREATE ASSEMBLY FirstUdf
    FROM 'FirstUdf.dll';
GO

CREATE FUNCTION CountSalesOrderHeader()
RETURNS INT
AS EXTERNAL NAME FirstUdf.T.ReturnOrderCount;
GO

SELECT dbo.CountSalesOrderHeader();
GO

A Transact-SQL közzétett függvénynévnek nem kell egyeznie a cél nyilvános statikus metódus nevével.

Kapcsolódó tartalom

• CLR-paraméteradatok leképezése
• CLR-integráció: a CLR-rutinok egyéni attribútumai
• felhasználó által definiált függvények
• CLR-adatbázisobjektumokból való adathozzáférés