Implémentation par programme des rappels clients sans publication (postback) dans des pages Web ASP.NET

Article
10/22/2014

Mise à jour : novembre 2007

Dans le modèle de pages Web ASP.NET par défaut, l'utilisateur interagit avec une page et clique sur un bouton ou exécute une autre action, ce qui entraîne une publication. La page et ses contrôles sont recréés, le code de page s'exécute sur le serveur et une nouvelle version de la page est rendue au navigateur. Cependant, dans certaines situations, il est utile d'exécuter le code serveur à partir du client sans effectuer de publication. Si le script client de la page conserve des informations d'état (par exemple, des valeurs de variable locale), le fait de publier la page et d'en obtenir une nouvelle copie détruira cet état. En outre, la publication de la page entraîne des charges mémoire de traitement susceptibles d'amoindrir les performances et de forcer l'utilisateur à attendre que la page soit traitée et recréée.

Pour ne pas perdre l'état client et éviter la charge mémoire de traitement qu'entraînerait un aller-retour serveur, vous pouvez coder une page Web ASP.NET afin qu'elle puisse exécuter des rappels clients. Dans un rappel client, une fonction de script client envoie une requête à une page Web ASP.NET. La page Web exécute une version modifiée de son cycle de vie normal. La page est lancée, ses contrôles et d'autres membres sont créés et une méthode spécialement marquée est appelée. La méthode exécute le traitement que vous avez codé, puis retourne au navigateur une valeur qui peut être lue par une autre fonction de script client. Tout au long de ce processus, la page est active dans le navigateur.

Plusieurs contrôles serveur Web peuvent utiliser des rappels clients. Par exemple, le contrôle TreeView utilise les rappels clients pour implémenter ses fonctionnalités de remplissage à la requête. Pour plus d'informations, consultez Vue d'ensemble du contrôle serveur Web TreeView.

Plusieurs options vous permettent d'automatiser les rappels clients dans une page Web ASP.NET. Les fonctionnalités AJAX d'ASP.NET telles que le contrôle serveur UpdatePanel peuvent automatiser des mises à jour de pages partielles asynchrones pour vous. De plus, la fonctionnalité de communication de service Web peut automatiser des appels de service Web asynchrones.

Pour obtenir une vue d'ensemble des fonctionnalités AJAX d'ASP.NET qui automatisent les rappels clients à votre place, consultez les rubriques suivantes :

Vous pouvez également écrire votre propre script client pour implémenter les rappels clients directement. Cette rubrique explique comment implémenter vos propres rappels clients pour une communication asynchrone entre le client et le serveur.

Composants des rappels clients

La création d'une page ASP.NET qui implémente par programme des rappels clients ressemble à celle des autres pages ASP.NET, à quelques différences près. Le code serveur de la page doit exécuter les tâches suivantes :

Implémentez l'interface ICallbackEventHandler. Vous pouvez ajouter cette déclaration d'interface à n'importe quelle page Web ASP.NET.
Fournissez une implémentation pour la méthode RaiseCallbackEvent. Cette méthode sera appelée pour exécuter le rappel sur le serveur.
Fournissez une implémentation pour la méthode GetCallbackResult. Cette méthode retournera le résultat du rappel au client.

De plus, la page doit contenir trois fonctions de script client qui exécutent les actions suivantes :

Une fonction appelle une méthode d'assistance qui exécute la demande réelle soumise au serveur. Dans cette fonction, vous pouvez commencer par exécuter une logique personnalisée pour préparer les arguments d'événement. Après quoi, vous pouvez envoyer une chaîne qui servira de paramètre au gestionnaire d'événements de rappel côté serveur.
Une autre fonction reçoit (est appelée par) les résultats du code serveur qui a traité l'événement de rappel, en acceptant une chaîne qui représente ces résultats. C'est ce qu'on appelle la « fonction de rappel client ».
Une troisième fonction appelle la fonction d'assistance qui exécute la requête réelle soumise au serveur. Cette fonction est générée automatiquement par ASP.NET lorsque vous créez une référence à cette fonction via la méthode GetCallbackEventReference dans le code serveur.

Les rappels clients et les publications (postback) sont des requêtes pour la page d'origine. Par conséquent, les rappels clients et les publications (postback) sont enregistrés dans des journaux de serveur Web en tant que requête de page.

Implémentation des interfaces requises dans le code serveur

Pour que le code serveur s'exécute à partir du script client sans effectuer de publication (postback), vous devez implémenter plusieurs interfaces dans le code serveur.

Déclaration de l'interface ICallbackEventHandler

Vous pouvez déclarer l'interface ICallbackEventHandler dans le cadre de la déclaration de classe de la page. Si vous créez une page code-behind, vous pouvez déclarer l'interface en utilisant une syntaxe comparable à la suivante.

Partial Class CallBack_DB_aspx
    Inherits System.Web.UI.Page
    Implements System.Web.UI.ICallbackEventHandler

public partial class CallBack_DB_aspx : 
    System.Web.UI.Page, System.Web.UI.ICallbackEventHandler

Si vous travaillez dans une page à fichier unique ou un contrôle utilisateur, vous pouvez ajouter la déclaration en utilisant une directive @ Implements à la page, comme dans les exemples suivants :

<%@ Page Language="VB" %>
<%@ Implements Interface="System.Web.UI.ICallbackEventHandler" %>

<%@ Page Language="C#" %>
<%@ Implements Interface="System.Web.UI.ICallbackEventHandler" %>

Remarque :
Le nom de l'interface respecte la casse.

Création d'une méthode de rappel de serveur

Dans le code serveur, vous devez créer une méthode qui implémente la méthode RaiseCallbackEvent et une autre qui implémente la méthode GetCallbackResult. La méthode RaiseCallbackEvent prend un argument de chaîne unique au lieu des deux arguments généralement utilisés avec des gestionnaires d'événements. La méthode pourra en partie ressembler à l'exemple suivant :

Public Sub RaiseCallbackEvent(ByVal eventArgument As String) _
    Implements System.Web.UI.ICallbackEventHandler.RaiseCallbackEvent

End Sub

public void RaiseCallbackEvent(String eventArgument)
{

}

La méthode GetCallbackResult ne prend pas d'arguments et retourne une chaîne. La méthode pourra en partie ressembler à l'exemple suivant :

Public Function GetCallbackResult() As String Implements _
    System.Web.UI.ICallbackEventHandler.GetCallbackResult
    Return aStringValue
End Function

public string GetCallbackResult()
{
    return aStringValue;
}

Création de fonctions de script client

Vous devez ajouter des fonctions de script client à la page pour exécuter deux fonctions : envoyer le rappel à la page serveur et recevoir les résultats. Les fonctions de script client sont toutes deux écrites en ECMAScript (JavaScript).

Envoi du rappel

La fonction d'envoi du rappel est générée dans le code serveur. Le rappel lui-même est exécuté par une fonction de bibliothèque disponible pour toute page qui implémente l'interface ICallbackEventHandler. Vous pouvez obtenir une référence à la fonction de bibliothèque en appelant la méthode GetCallbackEventReference de la page qui est accessible via la propriété ClientScript de la page. Vous devez alors générer dynamiquement une fonction cliente qui inclut un appel à la valeur de retour de la méthode GetCallbackEventReference. Vous passez à cette méthode une référence à la page (this en C# ou Me en Visual Basic), le nom de l'argument que vous allez utiliser pour passer des données, le nom de la fonction de script client qui recevra les données de rappel et un argument qui passe tout le contexte voulu.

Lorsque vous avez généré la fonction, vous l'injectez dans la page en appelant la méthode RegisterClientScriptBlock.

L'exemple suivant montre comment créer dynamiquement une fonction nommée CallServer qui appelle le rappel.

Sub Page_Load(ByVal sender As Object, ByVal e As System.EventArgs) _
    Handles Me.Load
    Dim cm As ClientScriptManager = Page.ClientScript
    Dim cbReference As String
    cbReference = cm.GetCallbackEventReference(Me, "arg", _
        "ReceiveServerData", "")
    Dim callbackScript As String = ""
    callbackScript &= "function CallServer(arg, context)" & _
        "{" & cbReference & "; }"
    cm.RegisterClientScriptBlock(Me.GetType(), _
        "CallServer", callbackScript, True)End Sub

void Page_Load(object sender, EventArgs e)
{
    ClientScriptManager cm = Page.ClientScript;
    String cbReference = cm.GetCallbackEventReference(this, "arg",
        "ReceiveServerData", "");
    String callbackScript = "function CallServer(arg, context) {" +
        cbReference + "; }";
    cm.RegisterClientScriptBlock(this.GetType(),
        "CallServer", callbackScript, true);
}

Les noms des arguments acceptés par la fonction que vous générez doivent correspondre aux noms des valeurs que vous passez à la méthode GetCallbackEventReference.

L'exemple suivant présente un balisage qui peut être utilisé pour appeler le rappel et traiter sa valeur de retour :

<input type="button" value="Callback" 
    onclick="CallServer(1, alert('Callback'))"/>
<br />
<span id="Message"></span>

<input type="button" value="Callback" 
    onclick="CallServer(1, alert('Callback'))"/>
<br />
<span id="Message"></span>

Réception du rappel

Vous pouvez écrire la fonction cliente qui reçoit statiquement les rappels dans la page. La fonction doit être nommée pour correspondre au nom que vous passez dans l'appel à la méthode GetCallbackEventReference. La fonction de réception accepte deux valeurs de chaîne : une pour la valeur de retour et une deuxième valeur facultative pour la valeur de contexte retournée par le serveur.

La fonction peut se présenter comme dans l'exemple suivant :

<script type="text/javascript">
function ReceiveServerData(arg, context)
{
    Message.innerText = 'Processed callback.';
}
</script>

Voir aussi

Concepts

Implémentation de rappel de client (Visual Basic), exemple

Implémentation de rappel de client (C#), exemple

Référence

ClientScriptManager