Bagikan melalui

Fungsi Bernilai Skalar CLR

  • Artikel

Berlaku untuk: SQL Server

Fungsi bernilai skalar (SVF) mengembalikan nilai tunggal, seperti string, bilangan bulat, atau nilai bit. Anda dapat membuat fungsi yang ditentukan pengguna bernilai skalar dalam kode terkelola menggunakan bahasa pemrograman .NET Framework apa pun. Fungsi-fungsi ini dapat diakses oleh Transact-SQL atau kode terkelola lainnya. Untuk informasi tentang keuntungan integrasi CLR dan memilih antara kode terkelola dan Transact-SQL, lihat Gambaran Umum Integrasi CLR.

Persyaratan untuk Fungsi Bernilai Skalar CLR

.NET Framework SVF diimplementasikan sebagai metode pada kelas dalam rakitan .NET Framework. Parameter input dan jenis yang dikembalikan dari SVF dapat berupa salah satu jenis data skalar yang didukung oleh SQL Server, kecuali varchar, karakter, rowversion, teks, ntext, gambar, tanda waktu, tabel, atau kursor. SVF harus memastikan kecocokan antara jenis data SQL Server dan jenis data pengembalian metode implementasi. Untuk informasi selengkapnya tentang konversi jenis, lihat Memetakan Data Parameter CLR.

Saat menerapkan .NET Framework SVF dalam bahasa .NET Framework, atribut kustom SqlFunction dapat ditentukan untuk menyertakan informasi tambahan tentang fungsi tersebut. Atribut SqlFunction menunjukkan apakah fungsi mengakses atau memodifikasi data, jika deterministik, dan jika fungsi melibatkan operasi floating point.

Fungsi yang ditentukan pengguna bernilai skalar mungkin deterministik atau tidak deterministik. Fungsi deterministik selalu mengembalikan hasil yang sama ketika dipanggil dengan sekumpulan parameter input tertentu. Fungsi non-deterministik dapat mengembalikan hasil yang berbeda ketika dipanggil dengan sekumpulan parameter input tertentu.

Catatan

Jangan menandai fungsi sebagai deterministik jika fungsi tidak selalu menghasilkan nilai output yang sama, mengingat nilai input yang sama dan status database yang sama. Menandai fungsi sebagai deterministik, ketika fungsi tidak benar-benar deterministik dapat mengakibatkan tampilan terindeks yang rusak dan kolom komputasi. Anda menandai fungsi sebagai deterministik dengan mengatur properti IsDeterministic ke true.

parameter bernilai tabel

Parameter bernilai tabel (TVP), jenis tabel yang ditentukan pengguna yang diteruskan ke prosedur atau fungsi, menyediakan cara yang efisien untuk meneruskan beberapa baris data ke server. TVP menyediakan fungsionalitas serupa dengan array parameter, tetapi menawarkan fleksibilitas yang lebih besar dan integrasi yang lebih dekat dengan Transact-SQL. Mereka juga memberikan potensi performa yang lebih baik. TVP juga membantu mengurangi jumlah perjalanan pulang pergi ke server. Alih-alih mengirim beberapa permintaan ke server, seperti dengan daftar parameter skalar, data dapat dikirim ke server sebagai TVP. Jenis tabel yang ditentukan pengguna tidak dapat diteruskan sebagai parameter bernilai tabel ke, atau dikembalikan dari, prosedur tersimpan terkelola atau fungsi yang dijalankan dalam proses SQL Server. Untuk informasi selengkapnya tentang TVP, lihat Menggunakan Parameter Bernilai Tabel (Mesin Database).

Contoh Fungsi Bernilai Skalar CLR

Berikut adalah SVF sederhana yang mengakses data dan mengembalikan nilai bilangan bulat:

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

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

Baris pertama kode mereferensikan Microsoft.SqlServer.Server untuk mengakses atribut dan System.Data.SqlClient untuk mengakses namespace ADO.NET. (Namespace ini berisi SqlClient, Penyedia Data .NET Framework untuk SQL Server.)

Selanjutnya, fungsi menerima atribut kustom SqlFunction , yang ditemukan di namespace Microsoft.SqlServer.Server . Atribut kustom menunjukkan apakah fungsi yang ditentukan pengguna (UDF) menggunakan penyedia dalam proses atau tidak untuk membaca data di server. SQL Server tidak mengizinkan UDF memperbarui, menyisipkan, atau menghapus data. SQL Server dapat mengoptimalkan eksekusi UDF yang tidak menggunakan penyedia dalam proses. Ini ditunjukkan dengan mengatur DataAccessKind ke DataAccessKind.None. Pada baris berikutnya, metode target adalah statis publik (dibagikan dalam Visual Basic .NET).

Kelas SqlContext , yang terletak di namespace Microsoft.SqlServer.Server , kemudian dapat mengakses objek SqlCommand dengan koneksi ke instans SQL Server yang sudah disiapkan. Meskipun tidak digunakan di sini, konteks transaksi saat ini juga tersedia melalui antarmuka pemrograman aplikasi System.Transactions (API).

Sebagian besar baris kode dalam isi fungsi harus terlihat akrab bagi pengembang yang telah menulis aplikasi klien yang menggunakan jenis yang ditemukan di namespace System.Data.SqlClient .

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

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

Teks perintah yang sesuai ditentukan dengan menginisialisasi objek SqlCommand . Contoh sebelumnya menghitung jumlah baris dalam tabel SalesOrderHeader. Selanjutnya, metode ExecuteScalar dari objek cmd dipanggil. Ini mengembalikan nilai tipe int berdasarkan kueri. Akhirnya, jumlah pesanan dikembalikan ke pemanggil.

Jika kode ini disimpan dalam file yang disebut FirstUdf.cs, kode ini dapat dikompilasi ke dalam assembly sebagai berikut:

[C#]

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

[Visual Basic]

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

Catatan

/t:library menunjukkan bahwa pustaka, daripada yang dapat dieksekusi, harus diproduksi. Executable tidak dapat didaftarkan di SQL Server.

Catatan

Objek database Visual C++ yang dikompilasi dengan /clr:pure tidak didukung untuk eksekusi di SQL Server. Misalnya, objek database tersebut menyertakan fungsi bernilai skalar.

Kueri Transact-SQL dan pemanggilan sampel untuk mendaftarkan assembly dan UDF adalah:

CREATE ASSEMBLY FirstUdf FROM 'FirstUdf.dll';  
GO  
  
CREATE FUNCTION CountSalesOrderHeader() RETURNS INT   
AS EXTERNAL NAME FirstUdf.T.ReturnOrderCount;   
GO  
  
SELECT dbo.CountSalesOrderHeader();  
GO

Perhatikan bahwa nama fungsi seperti yang diekspos dalam Transact-SQL tidak perlu cocok dengan nama metode statis publik target.

Lihat Juga

Memetakan Data Parameter CLR
Gambaran Umum Atribut Kustom Integrasi CLR
Fungsi yang Ditentukan Pengguna
Akses Data dari Objek Database CLR