Adicionar as operações de gravação do SharePoint ao suplemento hospedado pelo provedor

Artigo
04/08/2023

Este é o quinto de uma série de artigos sobre os conceitos básicos do desenvolvimento de suplementos do SharePoint hospedados pelo provedor. Primeiro, você deve estar familiarizado com suplementos do SharePoint e os artigos anteriores desta série, que podem ser encontrados em Introdução à criação de suplementos do SharePoint hospedados pelo provedor.

Observação

Se você trabalhou com esta série sobre suplementos hospedados pelo provedor, você terá uma solução do Visual Studio que pode ser usada para continuar com este tópico. Você também pode baixar o repositório em SharePoint_Provider-hosted_Add-Ins_Tutorials e abrir o arquivo BeforeSharePointWriteOps.sln.

Neste artigo, voltamos à codificação adicionando algumas funções que gravam dados no Suplemento do SharePoint da Chain Store.

Alterar um valor de coluna em um item de lista do SharePoint

Nosso suplemento tem um botão de faixa de opções personalizado que adiciona um funcionário da lista Funcionários Locais da loja de Hong Kong ao banco de dados corporativo. Mas o usuário precisa lembrar de alterar manualmente o valor do campo Adicionado ao DB Corporativo para Sim. Vamos adicionar código para fazer isso automaticamente.

Observação

As configurações de Projetos de Inicialização no Visual Studio tendem a reverter para padrões sempre que a solução é reaberta. Sempre siga estas etapas imediatamente após a reabertura da solução de exemplo nesta série de artigos:

Clique com botão direito do mouse no nó da solução na parte superior do Gerenciador de Soluções e então selecione Definir Projetos de Inicialização.
Verifique se todos os três projetos estão definidos como Iniciar na coluna Ação.

Em Gerenciador de Soluções, abra o arquivo EmployeeAdder.aspx.cs.
Adicione a linha a seguir ao método Page_Load entre a chamada de AddLocalEmployeeToCorpDB e a chamada de Response.Redirect. Na próxima etapa, você cria o método SetLocalEmployeeSyncStatus .
```
   // Write to SharePoint
 SetLocalEmployeeSyncStatus();
```
Adicione o novo método a seguir à EmployeeAdder classe.
```
   private void SetLocalEmployeeSyncStatus()
 {
     using (var clientContext = spContext.CreateUserClientContextForSPHost())
     {
         List localEmployeesList = clientContext.Web.Lists.GetByTitle("Local Employees");
         ListItem selectedLocalEmployee = localEmployeesList.GetItemById(listItemID);
         selectedLocalEmployee["Added_x0020_to_x0020_Corporate_x"] = true;
         selectedLocalEmployee.Update();
         clientContext.ExecuteQuery();
     }
 }
```
Observe o seguinte sobre este código:
- O nome interno do campo Adicionado ao BD Corporativo é de aparência estranha. Os nomes de campo internos não podem conter espaços, portanto, quando um usuário cria um campo com espaços em seu nome de exibição, o SharePoint substitui a cadeia de caracteres "x0020" por cada espaço quando define o nome interno. Isso transforma "Adicionado ao Employee DB" em "Added_x0020_to_x0020_Corporate_x0020_DB". Os nomes internos não podem ter mais de 32 caracteres, portanto, o nome é truncado para apenas "Added_x0020_to_x0020_Corporate_x".
- Embora a coluna Adicionada ao BD Corporativo seja chamada de campo Sim/Não na interface do usuário do SharePoint, ela é realmente um booliano, portanto, seu valor é definido como verdadeiro, não Sim.
- O método Update da classe ListItem deve ser chamado para confirmar as alterações no banco de dados de conteúdo do SharePoint. É uma regra geral, mas não muito universal, que quando você altera um valor de propriedade de um objeto armazenado nos bancos de dados do SharePoint, você deve chamar o método Update do objeto.

Solicitar permissão para gravar na lista da Web do host

Como o suplemento agora está gravando na lista, bem como lendo-a, precisamos escalar as permissões que o suplemento solicita de Leitura para Gravação. Siga estas etapas.

Em Gerenciador de Soluções, abra o arquivo AppManifest.xml no projeto ChainStore.
Abra a guia Permissões e, no campo Permissão , selecione Gravar na lista suspensa.
Salve o arquivo.

Execute o suplemento e teste o botão

Use a tecla F5 para implantar e executar o suplemento. O Visual Studio hospeda o aplicativo Web remoto no IIS Express e hospeda o banco de dados SQL no SQL Express. Ele também faz uma instalação temporária do suplemento em seu site de teste do SharePoint e executa imediatamente o suplemento. Você é solicitado a conceder permissões ao suplemento antes que sua página inicial seja aberta.
No formulário de permissão, selecione Funcionários Locais na lista e selecione Confiar nele.
Quando a página inicial do suplemento for aberta, clique em Voltar para Site no controle cromado na parte superior.
Na página inicial do site, acesse Site Contents>Local Employees. A página de exibição de lista é aberta.
Se não houver funcionários na lista com Não na coluna Adicionado ao DB Corporativo , adicione um funcionário à lista e não selecione a caixa de seleção Adicionado ao BD Corporativo .
Na faixa de opções, abra a guia Itens . Na seção Ações da guia está o botão personalizado Adicionar ao DB Corporativo.
Selecione um funcionário na lista que tem Não na coluna Adicionado ao BD Corporativo .
Selecione o botão Adicionar ao BD Corporativo . (Você deve selecionar um item primeiro.)
A página parece recarregar porque o método Page_Load da página EmployeeAdder redireciona de volta para ela. O valor do campo Adicionado ao BD Corporativo para as alterações do funcionário em Sim.

Observação

O que impede que um usuário altere manualmente o valor adicionado ao BD Corporativo de uma forma que torne a lista e o banco de dados corporativo inconsistentes? Nada faz no momento. Você obterá a solução para esse problema em um artigo posterior desta série.

1.To encerrar a sessão de depuração, feche a janela do navegador ou pare de depurar no Visual Studio. Sempre que você seleciona F5, o Visual Studio retrai a versão anterior do suplemento e instala a mais recente. 1.Clique com o botão direito do mouse no projeto em Gerenciador de Soluções e selecione Retrair.

Criar uma nova lista personalizada no site do host

O próximo aprimoramento para o suplemento Chain Store é criar novos itens em uma lista, em vez de simplesmente alterar um campo em um item existente. Especificamente, quando um novo pedido é colocado no nível corporativo, um item é criado automaticamente em uma lista do SharePoint que alerta os funcionários locais para esperar uma remessa. A lista é chamada de Remessas Esperadas e você a cria com as etapas a seguir. Em um artigo posterior nesta série, você aprenderá a adicionar programaticamente uma lista personalizada a um site de host, mas por enquanto você adicionará essa manualmente.

Na página inicial da Fabrikam Hong Kong Store, acesse Conteúdo do SiteAdicionar umalista personalizadade> suplementos>.
Na caixa de diálogo Adicionar Lista Personalizada , especifique Remessas Esperadas como o nome e selecione Criar.
Na página Conteúdo do Site , abra a lista Remessas Esperadas .
Na guia Lista na faixa de opções, selecione Configurações de Lista.
Na seção Colunas da página Configurações de Lista , selecione a coluna Título .
No formulário Editar Coluna , altere o nome da coluna de Título para Produto e selecione OK.
Na página Configurações , selecione Criar coluna.

Em um artigo anterior desta série, você aprendeu a criar colunas personalizadas para uma lista. Para a lista Remessas Esperadas , adicione quatro colunas usando os valores na tabela a seguir. Deixe todas as outras configurações em seus padrões.

Nome da coluna	Tipo	Obrigatório?	Valor padrão
Fornecedor	Texto com uma linha	Não é necessário	Nenhum
Quantidade	Número	Obrigatório	1
Chegou	Yes/No	Não é necessário	Não
Adicionado ao Inventário	Yes/No	Não é necessário	Não

Depois de criar as colunas, na página de configurações de lista, selecione Conteúdo do Site para abrir a página Conteúdo do Site . Abra a lista Remessas Esperadas .
Selecione novo item. O formulário de criação do item deve se parecer exatamente com o seguinte, incluindo os dois asteriscos que indicam campos necessários.

Figura 1. Formulário de criação de item para a lista Remessas Esperadas
Não queremos criar itens manualmente nesta lista, portanto, clique em Cancelar.

Inserir um item em uma lista do SharePoint

Agora você adiciona uma função ao suplemento que cria um item na lista Remessas Esperadas sempre que um pedido para a loja de Hong Kong é colocado no nível corporativo.

Em Gerenciador de Soluções, abra o arquivo OrderForm.aspx.cs.
Adicione uma instrução de uso para Microsoft.SharePoint.Client à parte superior do arquivo.
No método btnCreateOrder_Click , adicione a linha a seguir logo abaixo da chamada a CreateOrder. Você criará o método CreateExpectedShipment na próxima etapa.
```
  CreateExpectedShipment(txtBoxSupplier.Text, txtBoxItemName.Text, quantity);
```
Adicione o método a seguir à classe OrderForm.
```
private void CreateExpectedShipment(string supplier, string product, UInt16 quantity)
{
  using (var clientContext = spContext.CreateUserClientContextForSPHost())
  {
    List expectedShipmentsList = clientContext.Web.Lists.GetByTitle("Expected Shipments");
    ListItemCreationInformation itemCreateInfo = new ListItemCreationInformation();
    ListItem newItem = expectedShipmentsList.AddItem(itemCreateInfo);
    newItem["Title"] = product;
    newItem["Supplier"] = supplier;
    newItem["Quantity"] = quantity;
    newItem.Update();
    clientContext.ExecuteQuery();
  }
}
```
Observe o seguinte sobre este código:
- Um objeto ListItem não é criado com um construtor. Isso é por motivos de desempenho. Um objeto ListItem tem muitas propriedades (com valores padrão). Se um construtor for usado, todo o objeto será incluído na mensagem XML que o método ExecuteQuery envia para o servidor.
- O objeto ListItemCreationInformation é um objeto leve que contém apenas os valores mínimos não padrão que o servidor precisa para criar um objeto ListItem . Pode parecer que há uma linha que cria um objeto ListItem, mas lembre-se de que essa linha só adiciona alguma marcação XML a uma mensagem enviada ao servidor. O objeto ListItem é criado lá no servidor.
- Não há necessidade de trazer o objeto ListItem de volta para o cliente, portanto, não há nenhuma chamada para o método ClientContext.Load .
- O código não precisa definir explicitamente os campos Arrived ou Added to Inventory porque eles têm valores padrão de No, que é o que queremos.

Verificar se há componentes excluídos

Qualquer pessoa com privilégios de proprietário de lista para uma lista do SharePoint pode excluir a lista. E se a lista for implantada na Web do host por um suplemento, o proprietário do site da Web do host poderá excluí-la. Isso pode acontecer se o proprietário decidir fazer sem a funcionalidade fornecida pela lista. (Ele pode ser restaurado da Lixeira do SharePoint se o proprietário mudar de ideia.)

O método CreateExpectedShipment depende da existência da lista Remessas Esperadas . Suponha que um proprietário do site decidiu excluir a lista. Posteriormente, quando um pedido é adicionado com o Formulário de Ordem do suplemento, o método CreateExpectedShipment é chamado e gera uma exceção cuja mensagem diz que não há nenhuma lista de Remessas Esperadas no site do SharePoint.

Talvez você queira que o método verifique a expectedShipmentsList nulidade antes que ele faça qualquer coisa com ele. Quando você está trabalhando com o CSOM, não é possível fazer essa verificação com uma estrutura simples como esta:

if (expectedShipmentsList != null) { ... }

Em vez disso, você precisa usar uma classe CSOM especial chamada ConditionalScope. Os motivos para isso estão conectados ao sistema de lotes do CSOM, que foi mencionado no artigo anterior desta série (confira Runtime e lote do lado do cliente). CondicionalScope e o sistema de lote são tópicos avançados que estão fora do escopo desta série de introdução, mas você deve ver a documentação do MSDN sobre eles depois de concluir esta série de tutoriais.

Uma maneira alternativa de verificar a existência de uma lista é a seguinte: em vez de usar o método GetByTitle para obter uma referência à lista, você pode verificar se uma lista com o nome especificado está na "lista de listas" do site com código como o seguinte.

var query = from list in clientContext.Web.Lists 
             where list.Title == "Expected Shipments" 
             select list; 
IEnumerable<List> matchingLists = clientContext.LoadQuery(query); 
clientContext.ExecuteQuery(); 
if (matchingLists.Count() != 0) 
{ 
  List expectedShipmentsList = matchingLists.Single(); 
  // Do something with the list. 
}
clientContext.ExecuteQuery();

O código anterior tem a vantagem de permitir que você evite as complicações da classe ConditionalScope e usamos exatamente esse código em outros lugares nesta série de artigos. Mas há uma desvantagem também: esse código requer uma chamada extra de ExecuteQuery apenas para obter o valor que você deseja verificar na instrução if .

Se usarmos essa técnica no método CreateExpectedShipment para verificar a existência da lista, esse método terá duas chamadas de ExecuteQuery, cada uma das quais faz uma solicitação HTTP do servidor Web remoto para o SharePoint. Essas solicitações são a parte mais demorada de qualquer método CSOM, portanto, geralmente é uma boa prática minimizá-las.

Deixaremos o método CreateExpectedShipment como está, mas em um suplemento de produção, você precisará pensar em como seu código funcionará se um componente que ele referencia for excluído. Restaurar programaticamente a lista da Lixeira é uma opção, mas isso incomodaria os usuários que intencionalmente decidiram excluir a lista.

Você também deve considerar que não fazer nada para impedir a exceção pode ser a melhor escolha. Uma exceção do SharePoint alertaria os usuários de que a exclusão da lista quebrou parte do suplemento, que é algo que a pessoa que a excluiu pode não ter percebido. Em seguida, um usuário pode decidir se deve restaurar a lista da Lixeira ou fazer sem a parte da funcionalidade de suplemento que não funciona mais.

Solicitar permissão para gerenciar o site

Lembre-se de que quando um suplemento solicita permissão leitura ou gravação com o escopo de List, o SharePoint solicita que o usuário confie no suplemento e a caixa de diálogo contém uma lista suspensa em que o usuário seleciona a lista à qual o suplemento deve ter acesso. Somente uma lista pode ser selecionada. Mas o suplemento Chain Store agora grava em duas listas diferentes. Para obter acesso a várias listas, o suplemento precisa solicitar permissão com o escopo da Web. Siga estas etapas:

Em Gerenciador de Soluções, abra o arquivo AppManifest.xml no projeto ChainStore.
Abra a guia Permissões e, no campo Escopo , selecione Web na lista suspensa.
No campo Permissão , selecione Gravar na lista suspensa.
Salve o arquivo.

Execute o suplemento e teste a criação do item

Use a tecla F5 para implantar e executar o suplemento. O Visual Studio hospeda o aplicativo Web remoto no IIS Express e hospeda o banco de dados SQL no SQL Express. Ele também faz uma instalação temporária do suplemento em seu site de teste do SharePoint e executa imediatamente o suplemento. Você é solicitado a conceder permissões ao suplemento antes que sua página inicial seja aberta.
Quando a página inicial do suplemento for aberta, selecione o link Formulário de Pedido na parte inferior da página.
Insira alguns valores no formulário e então selecione Fazer Pedido.
Use o botão de volta do navegador para voltar para a página inicial e selecione Voltar para Site no controle cromado na parte superior.
Na página inicial da loja de Hong Kong, acesse Conteúdo do Site e abra a lista Remessas Esperadas . Agora há um item na lista correspondente à ordem. A captura de tela a seguir é um exemplo.

Figura 2. Lista de remessas esperadas com um único item
Para encerrar a sessão de depuração, feche a janela do navegador ou interrompa a depuração no Visual Studio. Sempre que você seleciona F5, o Visual Studio retira a versão anterior do suplemento e instala a versão mais recente.
Clique com botão direito do mouse no projeto no Gerenciador de Soluções e escolha Retirar.

Próximas etapas

No próximo artigo, você aprenderá a apresentar o Formulário de Pedido remoto como uma Web Part em uma página do SharePoint: inclua uma parte de suplemento no suplemento hospedado pelo provedor.

Partilhar via