Sdílet prostřednictvím

Skalární funkce CLR

  • Článek

platí pro:SQL Server

Skalární funkce (SVF) vrátí jednu hodnotu, například řetězec, celé číslo nebo bitovou hodnotu. Skalární uživatelem definované funkce ve spravovaném kódu můžete vytvářet pomocí libovolného programovacího jazyka .NET Framework. Tyto funkce jsou přístupné pro Transact-SQL nebo jiný spravovaný kód. Informace o výhodách integrace modulu CLR (Common Language Runtime) a výběru mezi spravovaným kódem a jazykem Transact-SQL najdete v tématu přehled integrace CLR.

Požadavky na skalární funkce CLR

SVF rozhraní .NET Framework jsou implementovány jako metody třídy v sestavení .NET Framework. Vstupní parametry a typ vrácený ze souboru SVF mohou být libovolnými skalárními datovými typy podporovanými SQL Serverem. kromě varchar, znak, textu, ntext, obrázku, časové razítko, tabulky nebo kurzoru. SVF musí zajistit shodu mezi datovým typem SQL Serveru a návratovým datovým typem metody implementace. Další informace o převodech typů naleznete v tématu Map CLR parametr data.

Při implementaci SVF rozhraní .NET Framework v jazyce rozhraní .NET Framework můžete zadat SqlFunction vlastní atribut, který bude obsahovat další informace o funkci. Atribut SqlFunction označuje, zda funkce přistupuje k datům nebo je upravuje, pokud je deterministická, a pokud funkce zahrnuje operace s plovoucí desetinnou čárkou.

Skalární funkce definované uživatelem můžou být deterministické nebo nedeterministické. Deterministické funkce vždy vrátí stejný výsledek, když je volána s konkrétní sadou vstupních parametrů. Ne deterministické funkce může vracet různé výsledky, když je volána s konkrétní sadou vstupních parametrů.

Poznámka

Neoznamujte funkci jako deterministiku, pokud funkce vždy nevygeneruje stejné výstupní hodnoty vzhledem ke stejným vstupním hodnotám a stejnému stavu databáze. Označení funkce jako deterministické, pokud funkce není skutečně deterministická, může vést k poškozeným indexovaným zobrazením a vypočítaným sloupcům. Funkci označíte jako deterministický nastavením vlastnosti IsDeterministic na true.

Parametry s hodnotami tabulky

Parametry s hodnotou tabulky (TVP), uživatelem definované typy tabulek, které se předávají do procedury nebo funkce, poskytují efektivní způsob předávání více řádků dat na server. TVP poskytují podobné funkce jako pole parametrů, ale nabízejí větší flexibilitu a užší integraci s Jazykem Transact-SQL. Poskytují také potenciál pro lepší výkon.

Poskytovatelé televizních služeb také pomáhají snížit počet odezvy na server. Místo odesílání více požadavků na server, například se seznamem skalárních parametrů, je možné data odeslat na server jako TVP. Uživatelem definovaný typ tabulky nelze předat jako parametr s hodnotou tabulky nebo ho vrátit ze spravované uložené procedury nebo funkce spuštěné v procesu SQL Serveru. Další informace o TVP naleznete v tématu Použití parametrů s hodnotou tabulky (databázový stroj).

Příklad skalární funkce CLR s hodnotou

Tady je jednoduchý formát SVF, který přistupuje k datům a vrací celočíselnou hodnotu:

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

První řádek kódu odkazuje Microsoft.SqlServer.Server pro přístup k atributům a System.Data.SqlClient pro přístup k ADO.NET oboru názvů. (Tento obor názvů obsahuje SqlClient, zprostředkovatele dat rozhraní .NET Framework pro SQL Server.)

Dále funkce obdrží SqlFunction vlastní atribut, který se nachází v oboru názvů Microsoft.SqlServer.Server. Vlastní atribut označuje, jestli uživatelem definovaná funkce (UDF) používá zprostředkovatele v procesu ke čtení dat na serveru. SQL Server neumožňuje, aby uživatelem definované funkce aktualizovaly, vkládaly nebo odstraňovaly data. SQL Server může optimalizovat provádění uživatelem definovaného uživatelem, který nepoužívá zprostředkovatele v procesu. To je indikováno nastavením DataAccessKind na DataAccessKind.None. Na dalším řádku je cílová metoda veřejnou statickou (sdílenou v jazyce Visual Basic .NET).

Třída SqlContext umístěná v oboru názvů Microsoft.SqlServer.Server pak může přistupovat k objektu SqlCommand s připojením k instanci SYSTÉMU SQL Server, která je již nastavena. I když se zde nepoužívá, aktuální kontext transakce je také k dispozici prostřednictvím System.Transactions aplikačního programovacího rozhraní (API).

Většina řádků kódu v těle funkce by měla vypadat dobře vývojářům, kteří píší klientské aplikace, které používají typy nalezené v System.Data.SqlClient oboru názvů.

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

Odpovídající text příkazu je určen inicializací SqlCommand objektu. Předchozí příklad spočítá počet řádků v tabulce SalesOrderHeader. Dále je volána ExecuteScalar metoda cmd objektu. Vrátí hodnotu typu int na základě dotazu. Nakonec se volajícímu vrátí počet objednávek.

Pokud je tento kód uložen v souboru s názvem FirstUdf.cs, může být zkompilován jako sestavení následujícím způsobem:

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

/t:library označuje, že se má vytvořit knihovna, nikoli spustitelný soubor. Spustitelné soubory nejde zaregistrovat na SQL Serveru.

Databázové objekty Visual C++ kompilované pomocí /clr:pure nejsou podporovány pro spouštění na SQL Serveru. Takové databázové objekty například zahrnují skalární funkce s hodnotou.

Dotaz Transact-SQL a ukázkové vyvolání pro registraci sestavení a funkce definované uživatelem jsou:

CREATE ASSEMBLY FirstUdf
    FROM 'FirstUdf.dll';
GO

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

SELECT dbo.CountSalesOrderHeader();
GO

Název funkce, který je vystavený v Transact-SQL, nemusí odpovídat názvu cílové veřejné statické metody.

Související obsah