Depuração de fluxos de trabalho do SharePoint

Demonstra como o SharePoint agora usa o Gerenciador de Fluxos de Trabalho 1.0 para todo o processamento e gerenciamento de fluxo de trabalho e demonstra opções de depuração.

Fornecido por:Andrew Connell, Voitanos

A equipe de fluxo de trabalho trabalhou com a equipe do Azure para criar um novo produto chamado Gerenciador de Fluxos de Trabalho. O Gerenciador de Fluxos de Trabalho hospeda a versão mais recente do tempo de execução do Windows Workflow Foundation e todos os serviços necessários de uma maneira disponível e escalonável. Ele aproveita o Barramento de Serviço do Microsoft Azure para obter o desempenho e a escalabilidade, e quando implantado, ele executa exatamente o mesmo em uma implantação local, como na nuvem, semelhante ao Office 365. Em seguida, o SharePoint é conectado e configurado para entregar toda a execução do fluxo de trabalho e tarefas relacionadas ao farm do Gerenciador de Fluxos de Trabalho.

Essa mudança na arquitetura exigia algumas alterações nas duas ferramentas de criação de fluxo de trabalho principais (SharePoint Designer 2013 e Visual Studio 2012) que você usou para criar fluxos de trabalho personalizados. No entanto, as técnicas de depuração empregadas pelos desenvolvedores no SharePoint 2007 e no SharePoint 2010 ainda se aplicam. A nova arquitetura permite uma nova opção para os fluxos de trabalho criados usando o SharePoint Designer 2013 ou Visual Studio 2012, em que o Fiddler pode ser usado para monitorar o tráfego entre o SharePoint e o Gerenciador de Fluxos de Trabalho.

Visão geral da depuração de fluxo de trabalho do SharePoint

Os fluxos de trabalho personalizados de depuração criados para o SharePoint se parecem versões anteriores, incluindo o SharePoint 2010 e o SharePoint 2007. Algumas opções de depuração disponíveis dependem da ferramenta usada para criar o fluxo de trabalho (SharePoint Designer 2013 ou Visual Studio 2012) e o tipo de implantação do SharePoint, como local ou no Office 365 (hospedado). Há quatro técnicas de depuração de fluxo de trabalho que podem ser usadas por autores de fluxo de trabalho:

• Registro na lista de histórico do fluxo de trabalho
• Definição de pontos de interrupção
• Enviar mensagens de depuração para o console
• Monitorar o tráfego entre o SharePoint e o Gerenciador de Fluxos de Trabalho com Fiddler

Cada opção apresenta vantagens e desvantagens. Isso ajuda a entender o que é possível ao usar as duas ferramentas de criação de fluxo de trabalho (SharePoint Designer 2013 ou Visual Studio 2012), bem como o tipo de implantação de fluxo de trabalho (local ou Office 365). A tabela a seguir contém uma matriz de ferramentas de criação, destinos de implantação e as opções disponíveis em cada cenário.

Depuração com a lista de histórico do fluxo de trabalho

A única opção de depuração que está disponível em todos os tipos de implantação do SharePoint é a gravação de mensagens de registro na lista do histórico do fluxo de trabalho. Usando esse método, você pode usar a ação Registrar na Lista de Histórico, no SharePoint Designer 2013 ou a atividade WriteToHistory no Visual Studio 2012 para gravar uma mensagem de cadeia de caracteres como um novo item na lista, especificado na associação de fluxo de trabalho, que é o contêiner de todas as mensagens de registro de histórico. Elas podem ser cadeias de caracteres simples ou construídas ao concatenar o conteúdo de variáveis dentro do fluxo de trabalho.

Usar a lista de histórico como uma ferramenta de depuração não é ideal, pois os usuários podem ver as mensagens. Portanto, quando a sessão de depuração estiver concluída e o fluxo de trabalho for usado na produção, o desenvolvedor de fluxo de trabalho desejará remover essas mensagens, criando uma etapa adicional entre depuração e implantação. No entanto, essa é a única opção disponível em qualquer cenário, independentemente de qual ferramenta é usada para criar o fluxo de trabalho ou o tipo de implantação do SharePoint.

Depuração usando pontos de interrupção de Visual Studio 2012

Outra opção de depuração é aproveitar os pontos de interrupção. Os pontos de interrupção estão disponíveis apenas para os fluxos de trabalho criados usando o Visual Studio 2012, uma vez que o SharePoint Designer 2013 não tem capacidade de definir pontos de interrupção ou anexar um depurador ao processo em execução. Esses recursos estão disponíveis tanto no SharePoint local e nas implantações hospedadas, como o Office 365. Neste cenário, você definiria um ponto de interrupção em uma atividade dentro do fluxo de trabalho e, em seguida, iniciaria o fluxo de trabalho no modo de depuração.

Figura 1. Iniciar o fluxo de trabalho

O Visual Studio implantará o fluxo de trabalho no ambiente do SharePoint de destino e anexará um depurador. Quando o processo de fluxo de trabalho atinge a atividade em que o ponto de interrupção está definido, o Visual Studio recupera o foco e permite que você examine os valores das variáveis de fluxo de trabalho e percorra todas as atividades do Visual Studio 2012, conforme mostrado na figura a seguir.

Figura 2. Ponto de interrupção do fluxo de trabalho

Depurando fluxos de trabalho usando mensagens de depuração e o host de serviço de teste

A introdução do Gerenciador de Fluxos de Trabalho para a história de fluxo de trabalho do SharePoint introduz duas novas oportunidades de depuração disponíveis quando você cria fluxos de trabalho personalizados usando o Visual Studio 2012 e os testa em uma implantação local. O Visual Studio 2012 inclui uma atividade WriteLineque aceita uma única mensagem baseada em uma cadeia de caracteres como uma entrada.

Figura 3. Atividade WriteLine

Essa atividade escreverá uma mensagem semelhante ao método System.Diagnostics.Debug.WriteLine() em um aplicativo de console padrão do Windows. A ferramenta de desenvolvimento do Gerenciador de Fluxos de Trabalho 1.0 inclui um utilitário de console chamado de Host de Serviço de Teste que o Visual Studio 2012 abrirá quando uma nova sessão de depuração for iniciada e durante o teste com uma implantação do SharePoint local. Este utilitário de consola, Microsoft.Workflow.TestServiceHost.exe encontrado em C:\Program Files (x86)\Gerenciador de Fluxos de Trabalho Tools\1.0, anexa à instância Gerenciador de Fluxos de Trabalho registada e escuta mensagens escritas com a atividade WriteLine, conforme mostrado na figura seguinte.

Figura 4. Mensagens da atividade WriteLine

Essas mensagens são parecidas com comentários de código ou mensagens de depuração em um aplicativo de console. Ao contrário da gravação na lista de histórico do fluxo de trabalho, você não precisa removê-los antes de implantar o fluxo de trabalho na produção. A menos que o utilitário de Host de Serviço de Teste esteja conectado ao Gerenciador de Fluxos de Trabalho, as mensagens são inofensivas.

Esta opção de depuração não está disponível para fluxos de trabalho criados usando o SharePoint Designer 2013, porque não há nenhuma ação que mapeie para a atividade WriteLine. Infelizmente, esta opção de depuração está disponível apenas para instalações do SharePoint local, uma vez que a porta usada pelo utilitário de Host de Serviço de Teste não costuma ser acessada publicamente fora de uma rede local. Esse problema também se aplica ao Office 365. As portas que o SharePoint usa para se conectar ao Gerenciador de Fluxos de Trabalho são as mesmas usadas pelo Host de Serviço de Teste, e elas só são acessíveis dentro da rede confiável. No entanto, isso não significa que você precisa alterar os fluxos de trabalho para remover todas as atividades WriteLine antes da implantação do Office 365. Essas atividades podem ser deixadas no fluxo de trabalho, pois não serão vistas, a menos que o Host de Serviço de Teste esteja conectado ao Gerenciador de Fluxos de Trabalho.

Depuração usando Fiddler para monitorar o tráfego HTTP

A última opção de depuração para fluxos de trabalho do SharePoint é uma nova inclusão para os desenvolvedores de fluxo de trabalho devido à mudança na maneira como os fluxos de trabalho são tratados na plataforma atual. Lembre-se de que, no SharePoint, todo o processamento do fluxo de trabalho é enviado para um produto externo, o Gerenciador de Fluxos de Trabalho 1.0. Quando um fluxo de trabalho tem que se comunicar com o SharePoint, por exemplo, para atualizar o estado atual do fluxo de trabalho, coletar dados de itens ou usuários em um site do SharePoint ou ao trabalhar com tarefas, as atividades do Gerenciador de Fluxos de Trabalho aproveitam a API REST do SharePoint para executar essas operações. O SharePoint se comunica com o Gerenciador de Fluxos de Trabalho usando uma biblioteca de cliente que funciona como um proxy para serviços REST expostos pelo Gerenciador de Fluxos de Trabalho. O SharePoint e o Gerenciador de Fluxos de Trabalho se comunicam entre si usando os protocolos HTTP e HTTPS padrão.

Essa arquitetura gera uma nova opção de depuração para autores de fluxo de trabalho. Usando a ferramenta de depuração de proxy Fiddler você pode monitorar todas as solicitações e respostas correspondentes entre os dois produtos. Além disso, todos os serviços personalizados chamados pelos fluxos de trabalho personalizados usando a atividade HttpSend no Visual Studio 2012 ou a ação Chamar o serviço Web HTTP no SharePoint Designer 2013 também podem ser monitoradas e inspecionadas pelo Fiddler. Esse modelo de depuração também está disponível, independentemente da ferramenta que você usa para criar fluxos de trabalho personalizados (SharePoint Designer 2013 ou Visual Studio 2012).

Essa opção só não está disponível quando você está testando fluxos de trabalho usando uma implantação do Office 365 do SharePoint. Como todo o tráfego entre o SharePoint e o Gerenciador de Fluxos de Trabalho acontece no lado do servidor, não é possível conectar-se a um dos servidores do Office 365 e iniciar o Fiddler no console.

Essa nova opção traz transparência e ideias para o mecanismo de fluxo de trabalho que não eram possíveis ao desenvolver fluxos de trabalho em versões anteriores do SharePoint antes do SharePoint.

Por exemplo, você pode ver as respostas brutas voltadas do Gerenciador de Fluxos de Trabalho ou do SharePoint em uma chamada de serviço web. Às vezes, o Gerenciador de Fluxos de Trabalho pode responder com uma mensagem de erro específica. O SharePoint inclui mensagens de erro amigáveis, mas isso pode não ser suficiente. Usando o Fiddler, você pode ver a mensagem de erro exata retornada para ajudar a solucionar o problema.

Outro caso de uso é examinar a resposta de uma chamada bem-sucedida do serviço web. Ao trabalhar com serviços web em fluxos de trabalho, independentemente da ferramenta de criação, você precisa saber o nome exato da propriedade (e o caminho, se for uma resposta complexa) para um valor contido em uma resposta. Usando o Fiddler, você pode ver os dados de respostas completas.

Entendendo o SharePoint e o Gerenciador de Fluxos de Trabalho para depuração com o Fiddler

Para depurar fluxos de trabalho no SharePoint e no Gerenciador de Fluxos de Trabalho 1.0 com o Fiddler, algumas etapas de configuração e instalação devem ser executadas em um ambiente de desenvolvedor antes da depuração. Antes de concluir as etapas, é importante compreender como o Fiddler funciona e como os fluxos de trabalho funcionam no SharePoint.

O Fiddler só pode inspecionar o tráfego do servidor local

O único tráfego que o Fiddler, pode interceptar e inspecionar são solicitações provenientes do servidor local onde o Fiddler foi iniciado. Isso pode se tornar um desafio quando o Fiddler for usado como uma ferramenta de depuração para fluxos de trabalho do SharePoint.

Se o SharePoint e o Gerenciador de Fluxos de Trabalho 1.0 estiverem instalados em servidores diferentes e se o Fiddler for iniciado a partir do Servidor do SharePoint, o único tráfego que o Fiddler exibirá será o tráfego de origem da solicitação do SharePoint. Nenhum tráfego originário do Gerenciador de Fluxos de Trabalho 1.0, mesmo que seja direcionado ao Servidor do SharePoint, será interceptado.

Portanto, ao desenvolver fluxos de trabalho, é mais fácil depurá-los se o SharePoint e o Gerenciador de Fluxos de Trabalho 1.0 estiverem instalados no mesmo servidor. Observe que isso não é obrigatório. Você pode iniciar o Fiddler nos servidores do Servidor do SharePoint e no Gerenciador de Fluxos de Trabalho, apesar de ser mais complexo monitorar duas instâncias em dois servidores para o mesmo processo de fluxo de trabalho.

O Fiddler só pode inspecionar o tráfego do usuário conectado no momento

O Fiddler só pode interceptar e inspecionar o tráfego do usuário conectado no momento. Para exibir o tráfego originado no SharePoint, você deve fazer logon no Servidor do SharePoint usando a conta do Windows que está configurada como a identidade do pool de aplicativos que hospeda o aplicativo web do site do SharePoint para iniciar o fluxo de trabalho.

O mesmo vale para o Gerenciador de Fluxos de Trabalho. Para interceptar e inspecionar o tráfego originado no Gerenciador de Fluxos de Trabalho, você deve fazer logon no servidor usando a identidade do Windows configurada durante a configuração do farm do Gerenciador de Fluxos de Trabalho como a conta do serviço do Gerenciador de Fluxos de Trabalho.

Ao usar o Fiddler para depurar fluxos de trabalho, é mais fácil depurá-los se o Gerenciador de Fluxos de Trabalho e o SharePoint não estiverem apenas instalados e configurados no mesmo servidor, mas também usando a mesma identidade do Windows que a conta de serviço. Todo o tráfego do Gerenciador de Fluxos de Trabalho e do SharePoint pode ser interceptado e inspecionado pelo Fiddler.

O SharePoint deve confiar no certificado do Fiddler

Antes de usar o Fiddler para depurar fluxos de trabalho do SharePoint, você precisa entender como o tráfego criptografado é manipulado. O tráfego criptografado no HTTP, conhecido como HTTPS, é implementado usando uma chave privada do certificado para criptografar alguns dados e enviá-los para outro destinatário. O destinatário tem a chave pública do certificado que está emparelhada com a chave privada. Quando uma solicitação é recebida pelo destinatário, o destinatário pode validar que a solicitação veio do remetente porque a assinatura do conteúdo criptografado corresponde à chave pública, que só pode ser verdadeira se foi criptografada com a chave privada do certificado.

O Fiddler pode interceptar o tráfego HTTPS e ser configurado para descriptografá-lo, para que ele fique em um formato legível para inspeção na ferramenta. Depois de exibir a solicitação, o Fiddler usa seu próprio certificado para criptografar novamente o tráfego e enviá-lo para o destinatário. No entanto, isso pode causar um problema, pois agora o destinatário recebeu a resposta original, mas ela não está protegida usando o certificado do remetente original. Isso pode ser um problema ao depurar fluxos de trabalho do SharePoint porque o certificado do Fiddler não é confiável para o SharePoint. Portanto, para usar o Fiddler para interceptar e inspecionar o tráfego HTTPS entre o SharePoint e o Gerenciador de Fluxos de Trabalho, o certificado Fiddler deve ser confiável para o SharePoint.

Configurar o SharePoint e o Gerenciador de Fluxos de Trabalho 1.0

As seções a seguir explicam como configurar o Fiddler e o SharePoint para depurar o fluxo de trabalho.

Configurar a configuração de proxy padrão do .NET Framework

A primeira etapa é definir primeiro a configuração de proxy padrão para o .NET Framework. Essas alterações permitem que o Fiddler Intercepte o tráfego vindo do SharePoint e do Gerenciador de Fluxos de Trabalho. Abra o arquivo machine.config em ambos os locais:

• %systemdrive%\\Windows\\Microsoft.NET\\Framework\\v4.0.30319\\Config\\machine.config
• %systemdrive%\\Windows\\Microsoft.NET\\Framework64\\v4.0.30319\\Config\\machine.config

Em seguida, adicione a seguinte marcação à parte inferior de cada ficheiro, imediatamente antes do elemento de configuração> de fecho<:

<system.net>
  <defaultProxy enabled="true">
    <proxy bypassonlocal="false" usesystemdefault="true" />
  </defaultProxy>
</system.net>

Salve as alterações e feche os arquivos.

Configurar o Fiddler para interceptar e inspecionar o tráfego HTTPS

A próxima etapa é configurar o Fiddler para interceptar o tráfego criptografado e descriptografá-lo para a configuração.

1. Inicie o Fiddler.
2. Se estiver a utilizar o ficheiro HOSTS local, certifique-se de que as entradas estão incluídas no Fiddler ao selecionar a opção de menu Ferramentas –> ANFITRIÕES .
3. Marqu Habilitar o remapeamento de solicitações de um host para um host ou IP diferente, substituindo o DNS.
4. Clique noImportar Arquivos de Hosts do Windows e, em seguida, clique no botão Salvar.

Figura 5. Remapeamento de Host

Em seguida, configure as opções de conexão do Fiddler.

1. Selecione a opção de menu Ferramentas -> Opções do Fiddler .

2. Clique na guia Conexões.

3. Desmarque a seleção Cadeia de proxy de upstream gateway.

4. Selecione as opções Agir como proxy do sistema na inicialização e Monitorar todas as conexões, conforme mostrado na figura a seguir.

   

5. Selecione a guia HTTPS, na caixa de diálogo Opções de Fiddler.

6. Marque Capturar CONEXÕES HTTPS.

7. Selecione Descriptografar o tráfego HTTPS.

8. Selecionar ??? de todos os processos.

9. Marque Ignorar erros de certificado do servidor.

10. Clique no botão Exportar certificado raiz para o desktop.

11. Quando receber uma mensagem de aviso, clique em Sim para Confiar no certificado Raiz do Fiddler.

Esse processo vai configurar o Windows para confiar no certificado, apesar de o SharePoint não confiar ainda.

Figura 7. Guia HTTPS

Configurar o SharePoint para confiar no certificado

A última etapa é configurar o SharePoint para confiar no certificado Fiddler que foi exportado na etapa anterior.

1. Faça logon como administrador do farm do SharePoint.

2. Inicie o Shell de Gerenciamento do SharePoint.

3. Carregar o Snap-In do SharePoint.

   Add-PSSnapIn Microsoft.SharePoint.PowerShell
   

4. Use o utilitário de certificado para instalar o certificado Fiddler.

   $fidderCertificatePath = [full path to exported FiddlerRoot.cer certificate file]
   certutil.exe -addstore -enterprise -f -v root $fidderCertificatePath
   $fiddlerCertificate = Get-PfxCertificate -FilePath $fidderCertificatePath
   New-SPTrustedRootAuthority -Name "Fiddler" -Certificate $fiddlerCertificate
   

5. Execute IISRESET para verificar se o SharePoint seleciona a alteração de confiança de certificado.

Passo a passo: depurando um fluxo de trabalho do Microsoft Office SharePoint Online com o Fiddler

Este passo a passo simples demonstra o uso do Fiddler para depurar um fluxo de trabalho do Microsoft Office SharePoint Online criado com o Visual Studio 2012. Quando o fluxo de trabalho é iniciado, ele recupera um ID do cliente de um campo em uma lista personalizada. Este ID do cliente é usado para consultar um serviço acessível publicamente para recuperar detalhes adicionais sobre o cliente. Em seguida, ele usa esses valores para atualizar o item de lista original. O fluxo de trabalho pode ser encontrado no seguinte exemplo de código do MSDN: fluxo de trabalho do Microsoft Office SharePoint Online: chame um Serviço da Web Externo.

Esse passo a passo tem os seguintes pré-requisitos:

• O SharePoint e o Gerenciador de Fluxos de Trabalho 1.0 devem estar instalados no mesmo servidor.

• A identidade do Windows CONTOSO\SP_Content está configurada para a identidade do conjunto aplicacional que aloja a aplicação Web que serve o site do SharePoint que inicia o fluxo de trabalho.

• O site do SharePoint usado para iniciar o fluxo de trabalho deve ser http://intranet.contoso.com

• O ponto de extremidade do farm do Gerenciador de Fluxos de Trabalho 1.0 é w15sp.contoso.com.

• O SharePoint e o Gerenciador de Fluxos de Trabalho 1.0 estão configurados para permitir o OAuth sobre HTTP.

  Cuidado

  Isso nunca deve ser feito no servidor de produção, mas apenas para teste e depuração.

1. Faça logon no servidor em que o Gerenciador de Fluxos de Trabalho e o SharePoint estão instalados com a identidade do Windows configurada como a conta do farm do Gerenciador de Fluxos de Trabalho 1.0 e a identidade do pool de aplicativos do SharePoint.

2. Inicie o Fiddler. Embora agora o Fiddler agora intercepte o tráfego do usuário atual, se houver alguma conexão ou processo existente em execução, o Fiddler poderá perder o que não estava sendo executado quando as conexões foram inicialmente estabelecidas. Para forçar o Gerenciador de Fluxos de Trabalho e o Servidor do SharePoint a reciclar e ter o tráfego de cada um deles interceptado pelo Fiddler, reutilize o SharePoint executando um IISRESET e o Gerenciador de Fluxos de Trabalho, interrompendo e inicializando o serviço Windows Back-end do Gerenciador de Fluxos de Trabalho. Isso pode ser feito com dois comandos a seguir em um prompt de comando administrativo.

   IISRESET
   net stop WorkflowServiceBackend
   net start WorkflowServiceBackend
   

3. Iniciar o fluxo de trabalho.

Na figura a seguir, observe que as sessões #18-36 são originárias do SharePoint e as sessões #37-43 são originadas no Gerenciador de Fluxos de Trabalho.

Figura 8. Iniciando o fluxo de trabalho

Observe que, na sessão #36, o SharePoint está solicitando que o Gerenciador de Fluxos de Trabalho inicie um fluxo de trabalho (indicado como [A] na figura), e o Gerenciador de Fluxos de Trabalho responde (indicado como [B] na figura) com uma mensagem de "Êxito":

Figura 9. Resposta de mensagem "sucesso"

A sessão #40 é onde o Gerenciador de Fluxos de Trabalho recupera o ID do item de lista e o GUID do SharePoint.

Figura 10. Recuperando ID do item e GUID

A sessão #43 é onde o Gerenciador de Fluxos de Trabalho está atualizando o item de lista no SharePoint com um novo valor para o campo de Corpo do item, passando um objeto JSON (JavaScript Object Notation) (indicado como [A] na figura) junto como o conteúdo. O SharePoint responde com o status HTTP 204. Isso indica que ele processou com êxito a solicitação, mas não há nenhuma mensagem na resposta.

Figura 11. Atualizando o item de lista

Conclusão

O histórico do fluxo de trabalho na versão do SharePoint introduziu uma nova camada de abstração, o Gerenciador de Fluxos de Trabalho 1.0. Essa nova arquitetura alterou a forma como os fluxos de trabalho são processados. Agora, o SharePoint conta com o Gerenciador de Fluxos de Trabalho 1.0 para todo o processamento e gerenciamento de fluxo de trabalho.

Uma tarefa que você precisa realizar durante a criação de aplicativos personalizados e processos de negócios em fluxos de trabalho é depurar o seu trabalho. A nova arquitetura de fluxo de trabalho do SharePoint oferece as mesmas opções de depuração existentes nas versões anteriores do SharePoint. No entanto, a nova arquitetura oferece duas novas opções durante a criação de fluxos de trabalho personalizados usando a nova arquitetura. Este artigo explicou as opções de depuração herdadas, bem como as novas opções, usando a atividade WriteLine e o uso do Fiddler para interceptar e inspecionar o tráfego entre o SharePoint e o Gerenciador de Fluxos de Trabalho 1.0.

Confira também

• Fiddler