Implementando Callbacks cliente sem Postbacks em páginas da Web

No modelo padrão para páginas da Web do ASP.NET, o usuário interage com uma página e clica em um botão ou executa alguma outra ação que resulta em um novo postback. A página e seus controles são recriados, o código de página é executado no servidor, e uma nova versão da página é processada para o navegador. Entretanto, em algumas situações, é útil executar código de servidor a partir do cliente sem executar um novo postback. Se o script cliente na página estiver mantendo algumas informações de estado (por exemplo, valores de variáveis locais), postar a página e obter uma nova cópia dela destrói esse estado. Além disso, postbacks de página introduzem sobrecarga de processamento que pode diminuir o desempenho e forçar o usuário a aguardar a página ser processada e recriada.

Para evitar a perda do estado do cliente e não gerar a sobrecarga do processamento de uma resposta do servidor, você pode codificar uma página da Web do ASP.NET para que ele possa fazer chamadas de retorno cliente. Em uma chamada de retorno cliente, uma função script cliente envia uma solicitação para uma página da Web do ASP.NET. A página da Web executa uma versão modificada do seu ciclo normal de vida — a página é iniciada e seus controles e outros membros são criados, e então um método especialmente marcado é chamado. O método executa o processamento que você codificou e então retorna um valor para o navegador que pode ser lido por outra função script cliente. Em todo esse processo, a página está ativa no navegador.

Vários controles do servidor Web utilizam chamadas de retorno cliente. Por exemplo, o controle TreeView utiliza chamadas de retorno cliente para implementar sua funcionalidade de preenchimento por demanda. Para obter mais informações consulte Visão geral sobre controle TreeView do Servidor Web.

Componentes de Chamadas de Retorno Cliente

Criar uma página ASP.NET que implementa chamadas de retorno é similar à criar qualquer página ASP.NET, com pequenas diferenças. O código do servidor da página deve:

• Implementar a interface ICallbackEventHandler. Você pode adicionar essa declaração de interface para qualquer página da Web do ASP.NET.

• Um método que implementa a interface RaiseCallbackEvent. Esse método será chamado para executar a chamada de retorno a partir do servidor.

Além disso, a página pode conter três funções script cliente que executam as seguintes ações:

• Uma função chama um método auxiliar que realiza a solicitação real para o servidor. Nessa função, você pode executar lógica personalizada para preparar os argumentos do evento primeiro, em seguida, você pode enviar uma seqüência de caracteres como um parâmetro para o manipulador de eventos de chamada de retorno do lado do servidor.

• Outra função recebe (é chamado por) o resultado do código do servidor que processou o evento de chamada de retorno, aceitando uma seqüência de caracteres que representa os resultados. Ela é chamada de função de chamada de retorno cliente.

• Uma terceira função é a função auxiliar que realiza a solicitação real para o servidor, a qual é gerada automaticamente pelo ASP.NET quando você gera uma referência a essa função utilizando o método GetCallbackEventReference no código do servidor.

Ambos, chamadas de retorno e postbacks, são solicitações para a página de origem, assim, chamadas de retorno cliente e postbacks são armazenados em logs de servidores Web como uma solicitação de página.

Implementando a Interface Apropriada no Código do Servidor

Para executar com êxito o código do servidor a partir do cliente sem executar um postback, você deve implementar as interfaces apropriadas no código do servidor.

Declarando a interface ICallbackEventHandler

Você pode declarar a interface ICallbackEventHandler como parte da declaração de classe para a página. Se você estiver criando uma página code-behind, você pode declarar a interface utilizando sintaxe como demonstrado a seguir.

Visual Basic

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

C#

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

Se você estiver trabalhando em uma página de um único arquivo ou controle de usuário, você pode adicionar a declaração utilizando uma diretiva @ Implements na página, como nos exemplos de código a seguir:

Visual Basic

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

C#

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

Observação
O nome interface diferencia maiúsculas de minúsculas.

Criando um Método Callback de Servidor

No código do servidor, você deve criar um método que implementa o método RaiseCallbackEvent e um método que implementa o método GetCallbackResult. O método RaiseCallbackEvent aceita uma única seqüência de caracteres como argumento, em vez dos dois argumentos que são normalmente utilizados com manipuladores de eventos normal. Uma parte do método pode parecer com o exemplo de código a seguir.

Visual Basic

Public Sub RaiseCallbackEvent(ByVal eventArgument As String) _
    Implements System.Web.UI.ICallbackEventHandler.RaiseCallbackEvent
    Return eventArgument & " new value"
End Sub 

C#

public void RaiseCallbackEvent(String eventArgument)
{
    return eventArgument + " new value";
}

O método GetCallbackResult não recebe argumentos e retorna uma seqüência de caracteres. Uma parte do método pode parecer com o exemplo de código a seguir.

Visual Basic

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

C#

public string GetCallbackResult()
{
    return aStringValue;
}

Criando Funções Scripts Cliente

Você deve adicionar funções script cliente à página para executar duas funções: enviar a chamada de retorno para a página do servidor e receber os resultados. As duas funções script cliente são gravadas no ECMAScript (JavaScript).

Enviando a Chamada de Retorno

A função para enviar a chamada de retorno é gerada no código do servidor. A chamada de retorno real é executada por uma função de biblioteca que está disponível para qualquer página que implementa a interface ICallbackEventHandler. Você pode obter uma referência para a função de biblioteca chamando o método GetCallbackEventReference da página, que pode ser acessado através da propriedade ClientScript da página. Você então compila uma função cliente dinamicamente que inclui uma chamada para o valor de retorno do método GetCallbackEventReference. Você passa para esse método uma referência para a página (this no C# ou Me no Visual Basic), o nome do argumento pelo qual você irá passar dados, o nome da função script cliente que receberá os dados da chamada de retorno, e um argumento que passa qualquer contexto que você desejar.

Quando você tiver compilado a função, você a insere dentro da página através da chamada do método RegisterClientScriptBlock.

O exemplo de código a seguir mostra como criar dinamicamente uma função denominada CallServer que chama a chamada de retorno.

Visual Basic

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 

C#

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

Os nomes dos argumentos que são aceitos pela função que você está gerando devem corresponder aos nomes dos valores que você passa para o método GetCallbackEventReference.

O exemplo de código a seguir mostra algumas marcações que podem ser utilizadas para chamar a chamada de retorno e processar seu valor de retorno:

Visual Basic

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

C#

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

Recebendo a Chamada de Retorno

Você pode escrever a função cliente que recebe chamadas de retorno estaticamente na página. A função deve ser nomeada de modo a corresponder ao nome que você passa na chamada para o método GetCallbackEventReference. A função receptora aceita dois valores de seqüência de caracteres: um para o valor de retorno e um segundo valor, opcional, para o valor de contexto que é passado de volta através do servidor.

A função pode ser semelhante ao exemplo de código a seguir:

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