Realizar operações básicas usando o código de biblioteca cliente do SharePoint

Artigo
04/08/2023

Você pode usar o CSOM (modelo de objeto do cliente) do SharePoint para recuperar, atualizar e gerenciar dados no SharePoint. O SharePoint disponibiliza o CSOM de diversas formas:

Assemblies redistribuíveis do .NET Framework
Biblioteca JavaScript (JSOM)
Pontos de extremidade REST/OData
Assemblies do Windows Phone (preteridos)
Assemblies redistribuíveis do Silverlight (preteridos)

Para saber mais sobre os conjuntos de APIs disponíveis para a plataforma do SharePoint, confira Escolher o conjunto de API correto no SharePoint.

Este artigo mostra como executar operações básicas usando o modelo de objeto .NET Framework, que está disponível como um pacote redistribuível na Galeria NuGet.

Para obter informações sobre como usar APIs de outro cliente, confira:

Operações básicas com o modelo de objeto cliente .NET do SharePoint

As seções a seguir descrevem tarefas que podem ser concluídas de maneira programática e que incluem exemplos de código do C#, que demonstram as operações CSOM.

Quando você cria um projeto de Suplemento para o SharePoint no Visual Studio 2012, referências a assemblies do .NET Framework, Microsoft.SharePoint.Client.Runtime.dll e Microsoft.SharePoint.Client.dll são adicionados automaticamente ao projeto. Para outros tipos de projetos, como aplicativos do .NET Framework ou aplicativos de console, é necessário adicionar essas referências. Os arquivos estão localizados em qualquer servidor do SharePoint em %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\15\ISAPI.

Esses exemplos pressupõem que o código está em um arquivo code-behind de uma página da Web do Microsoft ASP.NET. A seguinte instrução using deve ser adicionada ao arquivo de código.

using Microsoft.SharePoint.Client;

A menos que não tenha sido especificado, é necessário presumir que cada um desses exemplos é em um método sem parâmetros que foi definido na classe da página. Além disso, label1, label2 e os demais são os nomes dos objetos Label na página.

Observação

Quando você estiver criando um Suplemento do SharePoint hospedado pelo provedor com um aplicativo Web do ASP.NET e adicionar uma referência a um assembly ao projeto de aplicativo Web no Visual Studio, configure a propriedade Copy Local do assembly como True, a menos que você saiba que o assembly já está instalado no servidor Web ou possa garantir que está instalado antes de implantar o suplemento.

O .NET Framework é instalado em funções Web do Microsoft Azure e em sites do Azure. Porém, os assemblies do cliente do SharePoint e as várias extensões de código e as fundações gerenciadas da Microsoft não estão instalados. O Office Developer Tools para Visual Studio 2012 adiciona automaticamente referências a alguns conjuntos usados em suplementos do SharePoint e configura a propriedade Copy Local.

Tarefas de site do SharePoint

Esses exemplos mostram como usar o CSOM .NET Framework para concluir tarefas relacionadas ao site.

Recuperar as propriedades de um site

Recuperar o título de um site do SharePoint.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

// The SharePoint web at the URL.
Web web = context.Web;

// We want to retrieve the web's properties.
context.Load(web);

// Execute the query to the server.
context.ExecuteQuery();

// Now, the web's properties are available and we could display
// web properties, such as title.
label1.Text = web.Title;

Recuperar somente as propriedades selecionadas de um site

Às vezes, o cliente está interessado apenas em algumas propriedades do objeto. Com o CSOM do SharePoint .NET Framework, você não precisa armazenar todas as propriedades de objeto em um servidor. Você pode usar métodos anônimos, como expressões lambda, para solicitar nomes de propriedades. A biblioteca do cliente só realiza consultas para essas propriedades no servidor, e o servidor envia somente essas propriedades ao cliente. Essa técnica reduz transferência desnecessária de dados entre o cliente e servidor. Também é útil quando o usuário não tem permissão para uma ou mais das propriedades não utilizadas em um objeto.

Você precisa adicionar uma instrução using a System.Linq.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

// The SharePoint web at the URL.
Web web = context.Web;

// We want to retrieve the web's title and description.
context.Load(web, w => w.Title, w => w.Description);

// Execute the query to server.
context.ExecuteQuery();

// Now, only the web's title and description are available. If you
// try to print out other properties, the code will throw
// an exception because other properties aren't available.
label1.Text = web.Title;
label1.Text = web.Description;

Observação

Se você tentar acessar outras propriedades, o código criará uma exceção porque não há outras propriedades disponíveis.

Gravar nas propriedades do site

Este exemplo mostra como realizar gravações nas propriedades do site.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

// The SharePoint web at the URL.
Web web = context.Web;

web.Title = "New Title";
web.Description = "New Description";

// Note that the web.Update() doesn't trigger a request to the server.
// Requests are only sent to the server from the client library when
// the ExecuteQuery() method is called.
web.Update();

// Execute the query to server.
context.ExecuteQuery();

Criar um novo site do SharePoint

Este exemplo mostra como criar um novo site do SharePoint como um subsite do site atual. Use a classe WebCreationInformation para criar um novo site. Também é necessário adicionar instruções using para System.Collections.Generic e System.Text.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

WebCreationInformation creation = new WebCreationInformation();
creation.Url = "web1";
creation.Title = "Hello web1";
Web newWeb = context.Web.Webs.Add(creation);

// Retrieve the new web information.
context.Load(newWeb, w => w.Title);
context.ExecuteQuery();

label1.Text = newWeb.Title;

Tarefas de lista do SharePoint

Esses exemplos mostram como usar o CSOM .NET Framework para concluir tarefas relacionadas à lista.

Recuperar todas as listas do SharePoint em um site

Este exemplo recupera todas as listas do SharePoint em um site do mesmo. Para compilar esse código, é necessário adicionar uma instrução using a System.Linq.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

// The SharePoint web at the URL.
Web web = context.Web;

// Retrieve all lists from the server.
// For each list, retrieve Title and Id.
context.Load(web.Lists,
             lists => lists.Include(list => list.Title,
                                    list => list.Id));

// Execute query.
context.ExecuteQuery();

// Enumerate the web.Lists.
foreach (List list in web.Lists)
{
  label1.Text = label1.Text + ", " + list.Title;
}

Observação

Se preferir, você pode usar o método LoadQuery para armazenar o valor de retorno em outro conjunto em vez de usar a propriedade web.Lists. Também será preciso adicionar instruções using para System.Collections.Generic e System.Linq. Além disso, é necessário adicionar um alias à instrução em uso para o namespace Microsoft.SharePoint.Client, de modo que possa se referir às classes sem equívocos. Por exemplo, using SP = Microsoft.SharePoint.Client;.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

// The SharePoint web at the URL.
Web web = context.Web;

// Retrieve all lists from the server, and put the return value in another
// collection instead of the web.Lists.
IEnumerable<SP.List> result = context.LoadQuery(
  web.Lists.Include( 
      // For each list, retrieve Title and Id.
      list => list.Title,
      list => list.Id
  )
);

// Execute query.
context.ExecuteQuery();

// Enumerate the result.
foreach (List list in result)
{
  label1.Text = label1.Text + ", " + list.Title;
}

Criar e atualizar uma lista do SharePoint

Este exemplo cria uma lista do SharePoint e a atualiza com a classe ListCreationInformation.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

// The SharePoint web at the URL.
Web web = context.Web;

ListCreationInformation creationInfo = new ListCreationInformation();
creationInfo.Title = "My List";
creationInfo.TemplateType = (int)ListTemplateType.Announcements;
List list = web.Lists.Add(creationInfo);
list.Description = "New Description";

list.Update();
context.ExecuteQuery();

Excluir uma lista do SharePoint

Este exemplo exclui uma lista do SharePoint.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

// The SharePoint web at the URL.
Web web = context.Web;

List list = web.Lists.GetByTitle("My List");
list.DeleteObject();

context.ExecuteQuery();

Adicionar um campo a uma lista do SharePoint

Este exemplo adiciona um campo a uma lista do SharePoint. É necessário adicionar um alias à instrução em uso para o namespace Microsoft.SharePoint.Client, de modo que possa se referir às classes sem equívocos. Por exemplo, using SP = Microsoft.SharePoint.Client;.

Observação

O exemplo usa context.CastTo para realizar uma conversão. Antes de executar a consulta, a biblioteca do cliente não sabe o tipo real do “campo” do objeto retornado e SharePoint.Field é o único tipo possível. Se você souber o tipo real, use o método ClientContext.CastTo<RealType> para converter o objeto.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

SP.List list = context.Web.Lists.GetByTitle("Announcements");

SP.Field field = list.Fields.AddFieldAsXml("<Field DisplayName='MyField2' Type='Number' />",
                                           true,
                                           AddFieldOptions.DefaultValue);
SP.FieldNumber fldNumber = context.CastTo<FieldNumber>(field);
fldNumber.MaximumValue = 100;
fldNumber.MinimumValue = 35;
fldNumber.Update();

context.ExecuteQuery();

Tarefas de item de lista do SharePoint

Esses exemplos mostram como usar o CSOM .NET Framework para realizar tarefas relacionadas aos itens de lista.

Recuperar itens de uma lista do SharePoint

Este exemplo recupera todos os itens de uma lista do SharePoint. Você também precisa adicionar uma instrução using para Microsoft.SharePoint.Client.QueryExpression.

Observação

Você pode usar a propriedade FolderServerRelativeUrl para restringir ainda mais os itens que são retornados a eles em uma pasta especificada.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

// Assume the web has a list named "Announcements".
List announcementsList = context.Web.Lists.GetByTitle("Announcements");

// This creates a CamlQuery that has a RowLimit of 100, and also specifies Scope="RecursiveAll"
// so that it grabs all list items, regardless of the folder they are in.
CamlQuery query = CamlQuery.CreateAllItemsQuery(100);
ListItemCollection items = announcementsList.GetItems(query);

// Retrieve all items in the ListItemCollection from List.GetItems(Query).
context.Load(items);
context.ExecuteQuery();
foreach (ListItem listItem in items)
{
  // We have all the list item data. For example, Title.
  label1.Text = label1.Text + ", " + listItem["Title"];
}

Criar um novo item de lista

Este exemplo cria um novo item de lista do SharePoint com a classe ListItemCreationInformation.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

// Assume that the web has a list named "Announcements".
List announcementsList = context.Web.Lists.GetByTitle("Announcements");

// We are just creating a regular list item, so we don't need to
// set any properties. If we wanted to create a new folder, for
// example, we would have to set properties such as
// UnderlyingObjectType to FileSystemObjectType.Folder.
ListItemCreationInformation itemCreateInfo = new ListItemCreationInformation();
ListItem newItem = announcementsList.AddItem(itemCreateInfo);
newItem["Title"] = "My New Item!";
newItem["Body"] = "Hello World!";
newItem.Update();

context.ExecuteQuery();

Atualizar um item de lista

Este exemplo atualiza um item de lista do SharePoint.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

// Assume that the web has a list named "Announcements".
List announcementsList = context.Web.Lists.GetByTitle("Announcements");

// Assume there is a list item with ID=1.
ListItem listItem = announcementsList.GetItemById(1);

// Write a new value to the Body field of the Announcement item.
listItem["Body"] = "This is my new value!!";
listItem.Update();

context.ExecuteQuery();

Excluir um item de lista

Este exemplo exclui um item de lista do SharePoint.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

// Assume that the web has a list named "Announcements".
List announcementsList = context.Web.Lists.GetByTitle("Announcements");

// Assume that there is a list item with ID=2.
ListItem listItem = announcementsList.GetItemById(2);
listItem.DeleteObject();

context.ExecuteQuery(); }

Tarefas de campo do SharePoint

Esses exemplos mostram como usar o CSOM .NET Framework do SharePoint para concluir tarefas de campo.

Recuperar todos os campos de uma lista

Este exemplo recupera todos os campos de uma lista do SharePoint. Você também precisa adicionar um alias à instrução using para o namespace Microsoft.SharePoint.Client, de modo que possa se referir às classes sem equívocos; por exemplo, using SP = Microsoft.SharePoint.Client;.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

SP.List list = context.Web.Lists.GetByTitle("Shared Documents");
context.Load(list.Fields);

// We must call ExecuteQuery before enumerate list.Fields.
context.ExecuteQuery();

foreach (SP.Field field in list.Fields)
{
  label1.Text = label1.Text + ", " + field.InternalName;
}

Recuperar um campo específico da lista

Se você deseja recuperar informações sobre um campo específico, use o método Fields.GetByInternalNameOrTitle. O tipo de retorno desse método é Field. Antes que a consulta seja executada, o cliente não conhece o tipo do objeto e a sintaxe C# não está disponível para ser direcionada ao tipo derivado. Portanto, use o método ClientContext.CastTo para convertê-la. Esse processo faz com que a biblioteca do cliente recrie um objeto. Também é necessário adicionar uma instrução using a System.Collections.Generic. Você também precisa adicionar um alias à instrução using para o namespace Microsoft.SharePoint.Client, de modo que possa se referir às classes sem equívocos. Por exemplo, using SP = Microsoft.SharePoint.Client;.

Observação

O método GetByInternalNameOrTitle usado neste exemplo é um método remoto. Ele não usa os dados do conjunto do cliente, mesmo se este já estiver preenchido.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

SP.List list = context.Web.Lists.GetByTitle("Shared Documents");
SP.Field field = list.Fields.GetByInternalNameOrTitle("Title");
FieldText textField = context.CastTo<FieldText>(field);
context.Load(textField);
context.ExecuteQuery();

// Now, we can access the specific text field properties.
label1.Text = textField.MaxLength;

Tarefas de usuário do SharePoint

Você pode usar o CSOM .NET Framework do SharePoint para gerenciar usuários, grupos e a segurança do usuário do SharePoint.

Adicionar um usuário a um grupo do SharePoint

Este exemplo adiciona um usuário e algumas informações do usuário a um grupo do SharePoint denominado Membros.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

GroupCollection siteGroups = context.Web.SiteGroups;

// Assume that there is a "Members" group, and the ID=5.
Group membersGroup = siteGroups.GetById(5);

// Let's set up the new user info.
UserCreationInformation userCreationInfo = new UserCreationInformation();
userCreationInfo.Email = "user@domain.com";
userCreationInfo.LoginName = "domain\\user";
userCreationInfo.Title = "Mr User";

// Let's add the user to the group.
User newUser = membersGroup.Users.Add(userCreationInfo);

context.ExecuteQuery();

Recuperar todos os usuários de um grupo do SharePoint

Este exemplo obtém informações de todos os usuários de um grupo do SharePoint denominado Membros.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

GroupCollection siteGroups = context.Web.SiteGroups;

// Assume that there is a "Members" group, and the ID=5.
Group membersGroup = siteGroups.GetById(5);
context.Load(membersGroup.Users);
context.ExecuteQuery();

foreach (User member in membersGroup.Users)
{
  // We have all the user info. For example, Title.
  label1.Text = label1.Text + ", " + member.Title;
}

Criar uma função

Este exemplo cria uma função que tem de criar e gerenciar permissões de alertas.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

BasePermissions perm = new BasePermissions();
perm.Set(PermissionKind.CreateAlerts);
perm.Set(PermissionKind.ManageAlerts);

RoleDefinitionCreationInformation creationInfo = new RoleDefinitionCreationInformation();
creationInfo.BasePermissions = perm;
creationInfo.Description = "A role with create and manage alerts permission";
creationInfo.Name = "Alert Manager Role";
creationInfo.Order = 0;
RoleDefinition rd = context.Web.RoleDefinitions.Add(creationInfo);

context.ExecuteQuery();

Adicionar um usuário a uma função

Este exemplo adiciona um usuário a uma função.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

// Assume that we have a SiteUser with Login user.
Principal user = context.Web.SiteUsers.GetByLoginName(@"domain\user");

// Assume that we have a RoleDefinition named "Read".
RoleDefinition readDef = context.Web.RoleDefinitions.GetByName("Read");
RoleDefinitionBindingCollection roleDefCollection = new RoleDefinitionBindingCollection(context);
roleDefCollection.Add(readDef);
RoleAssignment newRoleAssignment = context.Web.RoleAssignments.Add(user, roleDefCollection);

context.ExecuteQuery();

Regras e práticas recomendadas para a utilização do modelo de objeto cliente .NET do SharePoint

Estes exemplos ilustram algumas práticas recomendadas importantes e requisitos que devem ser cumpridos para usar o CSOM .NET Framework do SharePoint.

Chamar ClientContext.ExecuteQuery antes de acessar as propriedades de valor

O CSOM do SharePoint .NET Framework exige que você use um padrão de programação do tipo SQL: declarar o que você deseja e executar a consulta antes de acessar os dados. Por exemplo, o código a seguir tenta exibir o título do site do SharePoint e acaba gerando uma exceção.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

Web web = context.Web;
label1.Text = web.Title;

Esse código falha porque o código CSOM .NET Framework do SharePoint deve:

crie uma consulta SQL ad hoc ou um procedimento armazenado
execute a consulta SQL
leia os resultados do SQL

No CSOM do SharePoint .NET Framework, você cria uma consulta sempre que chama um método. As consultas se acumulam e não são enviadas para o servidor até ExecuteQuery serem chamadas.

O exemplo a seguir mostra o código necessário para exibir o título do site. Você também precisa adicionar uma instrução using a System.Linq. Além disso, é necessário adicionar um alias à instrução using para o namespace Microsoft.SharePoint.Client, de modo que possa se referir às classes sem equívocos. Por exemplo, using SP = Microsoft.SharePoint.Client;.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

Web web = context.Web;

context.Load(web, w => w.Title);

context.ExecuteQuery();

label1.Text = web.Title;

As diferenças são a adição dessas linhas; a primeira linha cria uma consulta para a propriedade Title da Web. A segunda linha executa a consulta.

context.Load(web, w => w.Title);
context.ExecuteQuery();

Não use objetos valor que tenham sido retornados de métodos ou propriedades da mesma consulta

Quando um objeto valor é retornado de um método ou propriedade, só será possível executá-lo depois da consulta. Por exemplo, o código a seguir tenta criar uma lista do SharePoint que tenha o mesmo título que o site pai, mas gera uma exceção.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

Web web = context.Web;
ListCreationInformation creationInfo = new ListCreationInformation();
creationInfo.TemplateType = (int)ListTemplateType.Announcements;
creationInfo.Description = web.Title;
creationInfo.Title = web.Title;
List newList = web.Lists.Add(creationInfo);

Essa exceção é criada porque a propriedade não está disponível até que uma consulta seja executada. No SQL, você poderia declarar uma variável local para armazenar o valor do web.Title e usar a variável local para a criação da Web. Não é possível criar uma variável local na biblioteca do cliente. você precisa dividir a funcionalidade em duas consultas separadas, conforme mostrado no exemplo a seguir. Você também precisa adicionar uma instrução using a System.Linq. Além disso, é necessário adicionar um alias à instrução em uso para o namespace Microsoft.SharePoint.Client, de modo que possa se referir às classes sem equívocos. Por exemplo, using SP = Microsoft.SharePoint.Client;.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

Web web = context.Web;

context.Load(web, w => w.Title, w => w.Description);

context.ExecuteQuery();

ListCreationInformation creationInfo = new ListCreationInformation();
creationInfo.TemplateType = (int)ListTemplateType.Announcements;
creationInfo.Description = web.Description;
creationInfo.Title = web.Title;
SP.List newList = web.Lists.Add(creationInfo);

context.ExecuteQuery();

A diferença está nas três linhas a seguir:

context.Load(web, w => w.Title, w => w.Description);
context.ExecuteQuery();
// ...
context.ExecuteQuery();

Usando métodos ou propriedades que retornam objetos de cliente em outras chamadas de método na mesma consulta

Diferente de um objeto valor, um objeto cliente pode ser usado em outra chamada de método de uma mesma consulta.

No .NET Remoting, o objeto valor é uma classe ou struct empacotada por valor, e o objeto cliente é uma classe ou struct empacotada por referência. Por exemplo, o ListItem é um objeto cliente, enquanto o UrlFieldValue e os outros valores de campo são objetos de valor.

Na biblioteca cliente, o objeto servidor correspondente tem o atributo [ClientCallable(ValueObject = true)]. Esses valores podem ter apenas propriedades e nenhum método. Tipos primitivos, como cadeias de caracteres e integrações, são tratados como objetos de valor. Todos os valores são empacotados entre o cliente e servidor. O valor padrão do false é false.

O representante do objeto valor é o objeto de cliente. Se o objeto de servidor correspondente apresentar o atributo [ClientCallable(ValueObject = false)], o objeto será um objeto de cliente. Para objetos de cliente, podemos manter o controle de como o objeto é criado; isso se chama ObjectPath na implementação da biblioteca cliente. Por exemplo, se temos um código como este:

ClientContext context = new ClientContext("https://{site_url}");
Web web = context.Web;
SP.List list = web.Lists.GetByTitle("Announcements");

Sabemos que a lista foi criada:

obtendo a propriedade Web do contexto
obtendo a propriedade Lists do resultado acima
invocando o método GetByTitle com o parâmetro Announcements do resultado acima

Quando o CSOM do SharePoint .NET Framework passa essas informações para o servidor, é possível recriar o objeto no servidor. Na biblioteca do cliente, é possível acompanhar o ObjectPath no qual o objeto de cliente é criado. Uma vez que você sabe como o objeto é criado, é possível usar o objeto como um parâmetro para chamar outros métodos de uma mesma consulta.

Grupo de recuperação de dados no mesmo objeto para melhorar o desempenho

Ao ler vários dados do mesmo objeto, você deve tentar obter todos eles em uma única consulta; ou seja, uma única chamada para o Load<T>(T, []) método. O código a seguir mostra duas maneiras de recuperar o título e a descrição de um site, bem como a descrição da lista Comunicados. Para compilar esse código, é necessário adicionar uma instrução using a System.Linq. Além disso, é necessário adicionar um alias à instrução using para o namespace Microsoft.SharePoint.Client, de modo que possa se referir às classes sem equívocos. Por exemplo, using SP = Microsoft.SharePoint.Client;.

static void Method1()
{
  ClientContext context = new ClientContext("https://{site_url}");
  Web web = context.Web;
  SP.List list = web.Lists.GetByTitle("Announcements");
  context.Load(web, w => w.Title, w => w.Description);
  context.Load(list, l => l.Description);
  context.ExecuteQuery();
}

static void Method2()
{
  ClientContext context = new ClientContext("https://{site_url}");
  Web web = context.Web;
  SP.List list = web.Lists.GetByTitle("Announcements");
  context.Load(web, w => w.Title);
  context.Load(list, l => l.Description);
  context.Load(web, w => w.Description);
  context.ExecuteQuery();
}

Eles não são igualmente eficientes. Em Method1, o código para recuperar o título e a descrição da Web está agrupado. Em Method2, o código para recuperar o título e a descrição da Web está separado por outras ações. Isso significa que Method2 disparará duas consultas separadas no mesmo objeto da Web e haverá dois conjuntos de resultados para a mesma Web. Como a biblioteca do cliente tenta retornar dados consistentes, o segundo conjunto de resultados inclui o título e a descrição. Você pode pensar no código anterior da seguinte maneira.

// Method1:
SELECT Title, Description FROM Webs WHERE ...
SELECT Description FROM Lists WHERE …

// Method2:
SELECT Title FROM Webs WHERE …
SELECT Description FROM Lists WHERE …
SELECT Title, Description FROM Webs WHERE …

Especificar quais propriedades de objetos você deseja retornar

Se for possível recuperar um objeto SPWeb no modelo do objeto servidor SharePoint, você poderá inspecionar todas as suas propriedades. Para obter todas as colunas de uma tabela no SQL, você pode executar:

SELECT * FROM Webs

Na biblioteca do cliente, nem Load<T> nem outros métodos retornam todas as propriedades, de modo que é necessário especificar explicitamente o que você deseja. Por exemplo, o código a seguir recupera o objeto site da Web sem especificar as propriedades que precisam ser devolvidas. Em seguida, ele tenta ler duas propriedades e uma delas não se encontra entre as propriedades que são automaticamente retornadas por Load. Este código gera uma exceção.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

Web web = context.Web;
context.Load(web);
context.ExecuteQuery();

Console.WriteLine(web.Title);
Console.WriteLine(web.HasUniqueRoleAssignments);

Para que o código seja compilado com sucesso, é necessário atualizá-lo da maneira a seguir. Para compilar esse código, é necessário adicionar uma instrução using a System.Linq. Além disso, é necessário adicionar um alias à instrução using para o namespace Microsoft.SharePoint.Client, de modo que possa se referir às classes sem equívocos. Por exemplo, using SP = Microsoft.SharePoint.Client;.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

Web web = context.Web;
context.Load(web);
context.Load(web, web => web.HasUniqueRoleAssignments);
context.ExecuteQuery();

Console.WriteLine(web.Title);
Console.WriteLine(web.HasUniqueRoleAssignments);

Use o escopo condicional para testar pré-condições antes de carregar dados

Para executar códigos condicionalmente, use um objeto ConditionalScope para definir um escopo condicional. Por exemplo, recupere a propriedade de lista quando a lista não for lista. Também é necessário adicionar instruções using para System.Collections.Generic e System.Linq. Além disso, é necessário adicionar um alias à instrução using para o namespace Microsoft.SharePoint.Client, de modo que possa se referir às classes sem equívocos. Por exemplo, using SP = Microsoft.SharePoint.Client;.

Observação

O método de chamada e as propriedades de configuração presentes em um escopo condicional não são permitidos, porque a biblioteca do cliente não acompanha os efeitos colaterais das chamadas de método e as configurações de propriedade. Você deve usar somente o Load dentro do escopo condicional.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

SP.List list = context.Web.GetCatalog(ListTemplateType.WebPartCatalog);
BasePermissions perm = new BasePermissions();
perm.Set(PermissionKind.ManageLists);

ConditionalScope scope =
    new ConditionalScope(context,
                         () => list.ServerObjectIsNull &amp;&amp; context.Web.DoesUserHavePermissions(perm).Value);
using (scope.StartScope())
{
  context.Load(list, l => l.Title);
}
context.ExecuteQuery();

label1.Text = scope.TestResult.Value;

if (scope.TestResult.Value)
{
  label1.Text = list.Title;
}

Use um escopo da manipulação de exceção para capturar exceções

Este exemplo mostra como criar e usar um escopo da manipulação de exceção com um objeto ExceptionHandlingScope. O cenário é atualizar a descrição de uma lista e ativar a criação da pasta. Há uma possibilidade de que a lista não exista.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

ExceptionHandlingScope scope = new ExceptionHandlingScope(context);

using (scope.StartScope())
{
  using (scope.StartTry())
  {
    List fooList = context.Web.Lists.GetByTitle("Sample");
    fooList.Description = "In Try Block";
    fooList.Update();
  }
  using (scope.StartCatch())
  {
    // Assume that if there's an exception,
    // it can be only because there was no "Sample" list.
    ListCreationInformation listCreateInfo = new ListCreationInformation();
    listCreateInfo.Title = "Sample";
    listCreateInfo.Description = "In Catch Block";
    listCreateInfo.TemplateType = (int)ListTemplateType.Announcements;
    List fooList = context.Web.Lists.Add(listCreateInfo);
  }
  using (scope.StartFinally())
  {
    List fooList = context.Web.Lists.GetByTitle("Sample");
    fooList.EnableFolderCreation = true;
    fooList.Update();
  }
}

context.ExecuteQuery();

Compartilhar via

Realizar operações básicas usando o código de biblioteca cliente do SharePoint

Operações básicas com o modelo de objeto cliente .NET do SharePoint

Tarefas de site do SharePoint

Recuperar as propriedades de um site

Recuperar somente as propriedades selecionadas de um site

Gravar nas propriedades do site

Criar um novo site do SharePoint

Tarefas de lista do SharePoint

Recuperar todas as listas do SharePoint em um site

Criar e atualizar uma lista do SharePoint

Excluir uma lista do SharePoint

Adicionar um campo a uma lista do SharePoint

Tarefas de item de lista do SharePoint

Recuperar itens de uma lista do SharePoint

Criar um novo item de lista

Atualizar um item de lista

Excluir um item de lista

Tarefas de campo do SharePoint

Recuperar todos os campos de uma lista

Recuperar um campo específico da lista

Tarefas de usuário do SharePoint

Adicionar um usuário a um grupo do SharePoint

Recuperar todos os usuários de um grupo do SharePoint

Criar uma função

Adicionar um usuário a uma função

Regras e práticas recomendadas para a utilização do modelo de objeto cliente .NET do SharePoint

Chamar ClientContext.ExecuteQuery antes de acessar as propriedades de valor

Não use objetos valor que tenham sido retornados de métodos ou propriedades da mesma consulta

Usando métodos ou propriedades que retornam objetos de cliente em outras chamadas de método na mesma consulta

Grupo de recuperação de dados no mesmo objeto para melhorar o desempenho

Especificar quais propriedades de objetos você deseja retornar

Use o escopo condicional para testar pré-condições antes de carregar dados

Use um escopo da manipulação de exceção para capturar exceções

Confira também

Recursos adicionais