Delen via

CLR scalaire functies

  • Artikel

van toepassing op:SQL Server-

Een scalaire-waardefunctie (SVF) retourneert één waarde, zoals een tekenreeks, geheel getal of bitwaarde. U kunt door de gebruiker gedefinieerde scalaire functies in beheerde code maken met behulp van een programmeertaal van .NET Framework. Deze functies zijn toegankelijk voor Transact-SQL of andere beheerde code. Zie OVERZICHT van CLR-integratie (CLR) voor informatie over de voordelen van CLR-integratie (Common Language Runtime) en het kiezen tussen beheerde code en Transact-SQL.

Vereisten voor scalaire clr-functies

AVP's van .NET Framework worden geïmplementeerd als methoden voor een klasse in een .NET Framework-assembly. De invoerparameters en het type dat wordt geretourneerd door een SVF, kunnen een van de scalaire gegevenstypen zijn die worden ondersteund door SQL Server. behalve varchar, teken, rowversion, tekst, tekst, afbeelding, tijdstempel, tabelof cursor. AVP's moeten zorgen voor een overeenkomst tussen het SQL Server-gegevenstype en het retourgegevenstype van de implementatiemethode. Zie Kaart CLR-parametergegevensvoor meer informatie over typeconversies.

Wanneer u een .NET Framework SVF in een .NET Framework-taal implementeert, kunt u het aangepaste kenmerk SqlFunction opgeven om aanvullende informatie over de functie op te nemen. Het kenmerk SqlFunction geeft aan of de functie gegevens opent of wijzigt, als deze deterministisch is en of de functie drijvendekommabewerkingen omvat.

Door de gebruiker gedefinieerde scalaire functies kunnen deterministisch of niet-deterministisch zijn. Een deterministische functie retourneert altijd hetzelfde resultaat wanneer deze wordt aangeroepen met een specifieke set invoerparameters. Een niet-deterministische functie kan verschillende resultaten retourneren wanneer deze wordt aangeroepen met een specifieke set invoerparameters.

Notitie

Markeer een functie niet als deterministisch als de functie niet altijd dezelfde uitvoerwaarden produceert, gezien dezelfde invoerwaarden en dezelfde databasestatus. Als u een functie markeert als deterministisch, kan het niet echt deterministisch zijn dat beschadigde geïndexeerde weergaven en berekende kolommen ontstaan. U markeert een functie als deterministisch door de eigenschap IsDeterministic in te stellen op waar.

Parameters met tabelwaarde

Parameters met tabelwaarde (TVP's), door de gebruiker gedefinieerde tabeltypen die worden doorgegeven aan een procedure of functie, bieden een efficiënte manier om meerdere rijen met gegevens door te geven aan de server. TVP's bieden vergelijkbare functionaliteit voor parametermatrices, maar bieden meer flexibiliteit en een betere integratie met Transact-SQL. Ze bieden ook het potentieel voor betere prestaties.

TV's helpen ook het aantal retouren naar de server te verminderen. In plaats van meerdere aanvragen naar de server te verzenden, zoals met een lijst met scalaire parameters, kunnen gegevens als TVP naar de server worden verzonden. Een door de gebruiker gedefinieerd tabeltype kan niet worden doorgegeven als een tabelwaardeparameter aan of worden geretourneerd door een beheerde opgeslagen procedure of functie die wordt uitgevoerd in het SQL Server-proces. Zie Tabelwaardeparameters (Database Engine) gebruikenvoor meer informatie over IP-adressen.

Voorbeeld van een CLR-functie met scalaire waarden

Hier volgt een eenvoudige SVF die toegang heeft tot gegevens en een geheel getal retourneert:

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

De eerste regel codeverwijzingen Microsoft.SqlServer.Server voor toegang tot kenmerken en System.Data.SqlClient voor toegang tot de ADO.NET-naamruimte. (Deze naamruimte bevat SqlClient, de .NET Framework-gegevensprovider voor SQL Server.)

Vervolgens ontvangt de functie het SqlFunction aangepast kenmerk, dat in de Microsoft.SqlServer.Server naamruimte wordt gevonden. Het aangepaste kenmerk geeft aan of de door de gebruiker gedefinieerde functie (UDF) de in-process provider gebruikt om gegevens op de server te lezen. Met SQL Server kunnen UDF's geen gegevens bijwerken, invoegen of verwijderen. SQL Server kan de uitvoering van een UDF optimaliseren die niet gebruikmaakt van de in-process provider. Dit wordt aangegeven door DataAccessKind in te stellen op DataAccessKind.None. Op de volgende regel is de doelmethode een openbare statische methode (gedeeld in Visual Basic .NET).

De SqlContext-klasse, die zich in de Microsoft.SqlServer.Server naamruimte bevindt, heeft vervolgens toegang tot een SqlCommand-object met een verbinding met het SQL Server-exemplaar dat al is ingesteld. Hoewel hier niet wordt gebruikt, is de huidige transactiecontext ook beschikbaar via de System.Transactions APPLICATION Programming Interface (API).

De meeste regels code in de hoofdtekst van de functie moeten er bekend uitzien voor ontwikkelaars die clienttoepassingen schrijven die gebruikmaken van de typen in de System.Data.SqlClient naamruimte.

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

De juiste opdrachttekst wordt opgegeven door het SqlCommand-object te initialiseren. In het vorige voorbeeld wordt het aantal rijen in tabel SalesOrderHeadergeteld. Vervolgens wordt de ExecuteScalar methode van het cmd-object aangeroepen. Hiermee wordt een waarde van het type geretourneerd op basis van de query. Ten slotte wordt het aantal bestellingen geretourneerd naar de beller.

Als deze code wordt opgeslagen in een bestand met de naam FirstUdf.cs, kan deze als volgt als assembly worden gecompileerd:

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

/t:library geeft aan dat een bibliotheek, in plaats van een uitvoerbaar bestand, moet worden geproduceerd. Uitvoerbare bestanden kunnen niet worden geregistreerd in SQL Server.

Visual C++ databaseobjecten die zijn gecompileerd met /clr:pure worden niet ondersteund voor uitvoering op SQL Server. Dergelijke databaseobjecten bevatten bijvoorbeeld scalaire functies.

De Transact-SQL-query en een voorbeeld-aanroep voor het registreren van de assembly en UDF zijn:

CREATE ASSEMBLY FirstUdf
    FROM 'FirstUdf.dll';
GO

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

SELECT dbo.CountSalesOrderHeader();
GO

De functienaam zoals weergegeven in Transact-SQL hoeft niet overeen te komen met de naam van de openbare statische doelmethode.

Verwante inhoud