SqlPipe-Objekt

Artikel
05/07/2013

In früheren Versionen von SQL Server war es üblich, eine gespeicherte Prozedur (oder eine erweiterte gespeicherte Prozedur) zu schreiben, die Ergebnisse oder Ausgabeparameter an den aufrufenden Client sendet.

In einer Transact-SQL gespeicherten Prozedur sendet jede SELECT-Anweisung, die NULL oder mehr Zeilen zurückgibt, die Ergebnisse an die "Pipe" des verbundenen Aufrufers.

Für CLR-Datenbankobjekte (Common Language Runtime), die in SQL Server ausgeführt werden, können Sie die Ergebnisse mit der Send-Methode des SqlPipe-Objekts an die verbundene Pipe senden. Greifen Sie auf die Pipe-Eigenschaft des SqlContext-Objekts zu, um das SqlPipe-Objekt abzurufen. Die SqlPipe-Klasse gleicht konzeptionell der Response-Klasse in ASP.NET. Weitere Informationen finden Sie in der Referenzdokumentation zur SqlPipe-Klasse im .NET Framework Software Development Kit.

Zurückgeben von Tabellenergebnissen und Meldungen

SqlPipe verfügt über eine Send-Methode, die drei Überladungen besitzt. Die Überladungen sind:

void Send(string message)
void Send(SqlDataReader reader)
void Send(SqlDataRecord record)

Die Send-Methode sendet Daten direkt an den Client oder Aufrufer. Normalerweise verwendet der Client die Ausgabe der SqlPipe-Methode, im Fall von geschachtelten gespeicherten CLR-Prozeduren kann es sich beim Consumer der Ausgabe jedoch auch um eine gespeicherte Prozedur handeln. Beispiel: Procedure1 ruft SqlCommand.ExecuteReader() mit dem Befehlstext "EXEC Procedure2" auf. Bei Procedure2 handelt es sich ebenfalls um eine verwaltete gespeicherte Prozedur. Wenn Procedure2 jetzt SqlPipe.Send( SqlDataRecord ) aufruft, wird die Zeile an den Reader von Procedure1 und nicht an den Client gesendet.

Die Send-Methode sendet eine Zeichenfolgenmeldung, die auf dem Client als Informationsmeldung ähnlich wie PRINT in Transact-SQL erscheint. Die Methode kann mit SqlDataRecord auch ein einzeiliges Resultset oder mit SqlDataReader ein mehrzeiliges Resultset senden.

Das SqlPipe-Objekt stellt außerdem eine ExecuteAndSend-Methode bereit. Mit dieser Methode kann ein Befehl (der als SqlCommand-Objekt übergeben wird) ausgeführt und Ergebnisse direkt zurück an den Aufrufer gesendet werden. Wenn im übermittelten Befehl Fehler vorhanden sind, werden Ausnahmen an die Pipe gesendet. Es wird jedoch auch eine Kopie an den aufrufenden verwalteten Code gesendet. Wenn der aufrufende Code die Ausnahme nicht abfängt, wird sie in der Liste aufwärts weitergeleitet an den Transact-SQL-Code und dann zweimal in der Ausgabe angezeigt. Wenn der aufrufende Code die Ausnahme abfängt, wird dem Client der Fehler angezeigt, es gibt jedoch keinen doppelten Fehler.

Es kann nur ein SqlCommand-Befehl, der mit der kontextabhängigen Verbindung verknüpft ist, akzeptiert werden. Ein Befehl, der mit der nicht kontextabhängigen Verbindung verknüpft ist, kann nicht akzeptiert werden.

Zurückgeben von benutzerdefinierten Resultsets

Verwaltete gespeicherte Prozeduren können Resultsets senden, die nicht von einem SqlDataReader stammen. Die SendResultsStart-Methode ermöglicht es gespeicherten Prozeduren zusammen mit SendResultsRow und SendResultsEnd, benutzerdefinierte Resultsets an den Client zu senden.

SendResultsStart akzeptiert einen SqlDataRecord als Eingabe. Die Methode kennzeichnet den Anfang eines Resultsets und erstellt mithilfe der Datensatzmetadaten die Metadaten zur Beschreibung des Resultsets. Der Wert des Datensatzes wird nicht mit SendResultsStart gesendet. Alle nachfolgenden Zeilen, die mit der SendResultsRow-Methode gesendet werden, müssen dieser Metadatendefinition entsprechen.

Hinweis
Nach dem Aufruf der SendResultsStart-Methode können nur SendResultsRow und SendResultsEnd aufgerufen werden. Ein Aufruf einer beliebigen anderen Methode in der gleichen Instanz von SqlPipe verursacht eine InvalidOperationException. SendResultsEnd setzt SqlPipe auf den Ausgangszustand zurück, in dem andere Methoden aufgerufen werden können.

Beispiel

Die gespeicherte uspGetProductLine-Prozedur gibt den Namen, die Produktnummer, die Farbe und den Listenpreis aller Produkte innerhalb einer bestimmten Produktlinie zurück. Diese gespeicherte Prozedur nimmt genaue Übereinstimmungen für prodLine an.

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

public partial class StoredProcedures
{
[Microsoft.SqlServer.Server.SqlProcedure]
public static void uspGetProductLine(SqlString prodLine)
{
    // Connect through the context connection.
    using (SqlConnection connection = new SqlConnection("context connection=true"))
    {
        connection.Open();

        SqlCommand command = new SqlCommand(
            "SELECT Name, ProductNumber, Color, ListPrice " +
            "FROM Production.Product " + 
            "WHERE ProductLine = @prodLine;", connection);

        command.Parameters.AddWithValue("@prodLine", prodLine);

        try
        {
            // Execute the command and send the results to the caller.
            SqlContext.Pipe.ExecuteAndSend(command);
        }
        catch (System.Data.SqlClient.SqlException ex)
        {
            // An error occurred executing the SQL command.
        }
     }
}
};

Visual Basic

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

Partial Public Class StoredProcedures
<Microsoft.SqlServer.Server.SqlProcedure()> _
Public Shared Sub uspGetProductLine(ByVal prodLine As SqlString)
    Dim command As SqlCommand

    ' Connect through the context connection.
    Using connection As New SqlConnection("context connection=true")
        connection.Open()

        command = New SqlCommand( _
        "SELECT Name, ProductNumber, Color, ListPrice " & _
        "FROM Production.Product " & _
        "WHERE ProductLine = @prodLine;", connection)
        command.Parameters.AddWithValue("@prodLine", prodLine)

        Try
            ' Execute the command and send the results 
            ' directly to the caller.
            SqlContext.Pipe.ExecuteAndSend(command)
        Catch ex As System.Data.SqlClient.SqlException
            ' An error occurred executing the SQL command.
        End Try
    End Using
End Sub
End Class

Die folgende Transact-SQL-Anweisung führt die uspGetProduct-Prozedur aus, die eine Liste mit Touringräderprodukten zurückgibt.

EXEC uspGetProductLineVB 'T';

Siehe auch

Konzepte

SqlDataRecord-Objekt

CLR-gespeicherte Prozeduren

Von SQL Server verwendete prozessinterne spezifische Erweiterungen für ADO.NET

Freigeben über