Kit de integração de Declarações, Azure e SharePoint parte 4
Kit de integração de Declarações, Azure e SharePoint parte 4
Esta é a parte 4 de uma série de cinco partes sobre o Kit CASI (Integração de Declarações, Azure e SharePoint). A Parte 1 foi uma visão geral introdutória sobre a estrutura e a solução completas e descreveu o que a série tentará abordar. A Parte 2 abordou a orientação para a criação de aplicativos WCF, a transformação deles em aplicativos com reconhecimento de declaração e sua adaptação para uso no Windows Azure. A Parte 3 mostrou a criação da classe base que você usará para conectar seu site do SharePoint aos dados do Azure, adicionando um novo controle personalizado a uma página do diretório _layouts. Nesta postagem, abordarei a Web Part incluída como parte desta estrutura. Ela foi criada especificamente para trabalhar com o controle personalizado criado e adicionado à página de layouts na Parte 3.
Usando a Web Part
Antes de começar a usar a Web Part, supõe-se que você, obviamente, a) possui um serviço WCF em funcionamento hospedado no Windows Azure e b) criou um controle personalizado e o adicionou à página de layouts, como descrito na Parte 3 desta série. Suponho também que você implantou o assembly da classe base do Kit CASI e o seu assembly de controle personalizado no GAC em todos os servidores do farm do SharePoint. Além disso, também acredito que a sua página aspx personalizada que hospeda o seu controle personalizado foi implantada no diretório de layouts em todos os servidores Web de front-end no farm. Para descrever como usar a Web Part, usarei o projeto de exemplo AzureWcfPage que carreguei e anexei à postagem da Parte 3. Dessa forma, vamos mostrar como você junta essas duas partes para renderizar dados do Azure em um site do SharePoint.
OBSERVAÇÃO: Embora não seja um requisito, normalmente será muito mais fácil usar a Web Part se os métodos WCF chamados retornarem HTML, pois assim ela poderá ser exibida diretamente na página sem processamento adicional.
A primeira etapa é implantar a solução AzureRender.wsp no farm; o wsp foi incluído no arquivo zip anexado a esta postagem. Ele contém o recurso que implanta a Web Part DataView do Azure, além do jQuery 1.4.2, no diretório de layouts. Depois que a solução for implantada e o recurso ativado para um conjunto de sites, você poderá adicionar a Web Part a uma página. Nesse ponto, você estará quase pronto para começar a renderizar os dados do Azure, mas será preciso definir pelo menos uma propriedade. Dessa forma, vamos ver que propriedade é essa e quais são as outras que se destinam à Web Part.
Propriedades da Web Part
Todas as propriedades da Web Part estão na seção Propriedades da Conexão. No mínimo, será preciso definir a propriedade Data Page para as páginas de layout criadas e implantadas. Por exemplo, /_layouts/AzureData.aspx. Se a marca do servidor para o controle personalizado definiu pelo menos as propriedades WcfUrl e MethodName, isso será tudo o que você precisará fazer. Se você não fizer mais nada, a Web Part chamará a página e usará o ponto de extremidade WCF e o método configurado na página, além de obter todos os dados retornados pelo método (ostensivamente, ele os retorna em formato HTML) e os renderizar na Web Part. Na maioria dos casos, será melhor usar algumas das propriedades da Web Part para obter flexibilidade máxima, então vamos dar uma olhada em cada uma delas:
· Nome do método* – o nome do método no aplicativo WCF que deve ser chamado. Se for necessário chamar a página de layouts com sua própria função javascript, o parâmetro da cadeia de caracteres de consulta para essa propriedade será “methodname”.
· Parameter List* – uma lista de parâmetros delimitada por ponto-e-vírgula para o método WCF. Como observado nas Partes 2 e 3 desta série, somente os tipos de dados básicos têm suporte – string, int, bool, long e datetime. Se você precisar de um tipo de dados mais complexo, desserialize-o primeiro em uma cadeia de caracteres, em seguida, chame o método e serialize o tipo de dados novamente para um tipo complexo no ponto de extremidade WCF. Se for necessário chamar a página de layouts com sua própria função javascript, o parâmetro de cadeia de caracteres de consulta para essa propriedade será “methodparams”.
· Success Callback Address – a função javascript chamada de volta depois que a solicitação jQuery para a página de layouts é concluída com êxito. Por padrão, esta propriedade usa a função javascript que vem com a Web Part. Se você usar a sua própria função, a assinatura da função será assim: function nomedaSuaFunção(dadosdeResultado, códigodeResultado, objetodaConsulta). Para obter mais detalhes, consulte a documentação do jQuery AJAX em https://api.jquery.com/jQuery.ajax/.
· Error Callback Address – a função javascript chamada de volta caso a solicitação jQuery para a página de layouts encontre um erro. Por padrão, esta propriedade usa a função javascript que vem com a Web Part. Se você usar a sua própria função, a assinatura da função será assim: function nomedaSuaFunção(SolicitaçãoHttpXML, statusdoTexto, erroLançado). Para obter mais detalhes, consulte a documentação do jQuery AJAX em https://api.jquery.com/jQuery.ajax/.
· Standard Error Message – a mensagem que será exibida na Web part caso seja encontrado um erro durante o processamento no servidor da Web Part. Isso significa que ela NÃO inclui cenários onde os dados estão sendo realmente buscados no Azure.
· Access Denied Message* – é a mensagem de erro Acesso Negado que deverá ser exibida caso o acesso seja negado ao usuário para um método em particular. Por exemplo, como explicado na Parte 2 desta série, uma vez que estivermos passando o token do usuário para a chamada WCF, poderemos decorar qualquer um dos métodos com uma demanda PrincipalPermission, como “este usuário deve fazer parte do grupo Gerentes de Vendas”. Se um usuário não atender à demanda PrincipalPermission, a chamada do WCF falhará com um erro de acesso negado. Nesse caso, a Web Part exibirá a Mensagem de Acesso Negado, seja ela qual for. Observe que você pode usar a formatação em RTF nesta mensagem, para fazer coisas como definir a fonte como negrito ou vermelha usando marcas HTML (isto é, <font color='red'>Você não tem acesso; entre em contato com o administrador</font>). Se for necessário chamar a página de layouts com sua própria função javascript, o parâmetro de cadeia de caracteres de consulta para essa propriedade será “accessdenied”.
· Timeout Message* – é a mensagem que será exibida se houver um erro de tempo limite durante a tentativa de execução da chamada ao método WCF. Também oferece suporte à formatação em RTF, como a definição da fonte como negrito, vermelha etc. Se for necessário chamar a página de layouts com sua própria função javascript, o parâmetro da cadeia de caracteres de consulta para essa propriedade será “timeout”.
· Show Refresh Link – marque essa caixa para renderizar um ícone de atualização acima dos resultados dos dados do Azure. Se o ícone for clicado, ele executará novamente o método WCF para obter os dados mais recentes.
· Refresh Style – permite que você adicione outros atributos de estilo ao atributo Style principal a marca IMG usada para mostrar o link de atualização. Por exemplo, você poderia adicionar “float:right;” usando essa propriedade para fazer com que a imagem de atualização seja alinhada à direita.
· Cache Results – marque essa caixa para fazer com que a biblioteca do jQuery armazene os resultados da consulta em cache. Isso significa que sempre que a página for carregada, usará uma versão em cache dos resultados da consulta. Isso economizará viagens de ida e volta até o Azure e resultará em desempenho mais rápido para usuários finais. Se os dados que estiverem sendo recuperados não mudarem com frequência, o armazenamento dos resultados será uma boa opção.
· Decode Results* – marque essa caixa caso o aplicativo WCF retorne resultados que sejam HtmlEncoded. Se você definir esta propriedade como verdadeira, HtmlDecoding será aplicado aos resultados. Na maioria dos casos, isso não será necessário. Se for necessário chamar a página de layouts com sua própria função javascript, o parâmetro da cadeia de caracteres de consulta para essa propriedade será “encode”.
* – essas propriedades serão ignoradas caso a propriedade AllowQueryStringOverride do controle personalizado seja definida como falsa.
Caso de uso típico
Supondo que o método WCF retorne HTML, na maioria dos casos será melhor adicionar a Web Part a uma página e definir duas ou três propriedades: Data Page, Method Name e, possivelmente, Parameter List.
Se você tiver requisitos de exibição ou de processamento mais avançados para os dados retornados pelo Azure, talvez seja melhor usar uma função javascript personalizada para isso. Nesse caso, você deve adicionar o seu javascript à página e definir a propriedade Success Callback Address ao nome da sua função javascript. Se a sua Web Part exigir postagens adicionais no aplicativo WCF, para ações como adições, atualizações ou exclusões, adicione-as às suas próprias funções javascript e chame a página de layouts personalizada com os valores de Method Name e Parameter List apropriados; os nomes de variável da cadeia de caracteres de consulta a serem usados estão documentadas acima. Ao chamar o método ajax no jQuery para chamar a página de layouts, você deverá ser capaz de usar uma abordagem semelhante à usada pela Web Part. A convenção de chamada usada baseia-se na função de script a seguir; observe que, provavelmente, você vai preferir continuar a usar a propriedade dataFilter mostrada porque ela retira a saída de página que NÃO pertence ao método WCF:
$.ajax({
type: "GET",
url: "/_layouts/SomePage.aspx",
dataType: "text",
data: "methodname=GetCustomerByEmail&methodparams=steve@contoso.local",
dataFilter: AZUREWCF_azureFilterResults,
success: yourSuccessCallback,
error: yourErrorCallback
});
Experimente!
Agora você tem todas as peças para tentar encerrar a solução final. Anexado a esta postagem, você encontrará um arquivo zip que inclui a solução da Web Part. Na próxima e última postagem desta série, descreverei como você também pode usar o controle personalizado desenvolvido na Parte 2 para recuperar dados do Azure e usá-lo no cache ASP.NET com outros controles e como usá-lo em tarefas do SharePoint – nesse caso, um trabalho de timer personalizado do SharePoint.
Esta é uma postagem de blog traduzida. Consulte o artigo original The Claims, Azure and SharePoint Integration Toolkit Part 4