Выполнение базовых операций с использованием кода библиотеки клиента в SharePoint

Статья
04/08/2023

С помощью клиентской объектной модели SharePoint (CSOM) вы можете получать и изменять данные в SharePoint, а также управлять ими. В SharePoint доступ к CSOM осуществляется несколькими путями:

через распространяемые сборки .NET Framework;
Библиотека JavaScript (JSOM)
Конечные точки REST и OData
Сборки Windows Phone (устарело)
Вторично распространяемые сборки Silverlight (устарело)

Дополнительные сведения о наборах API, доступных на платформе SharePoint, см. в статье Выбор правильного набора API в SharePoint.

В этой статье показано, как выполнять базовые операции с помощью объектной модели .NET, которая доступна в виде распространяемого пакета в коллекции NuGet.

Сведения об использовании других клиентских API см. в следующих статьях:

Основные операции с клиентской объектной моделью .NET в SharePoint

В приведенных ниже разделах описаны задачи, которые вы можете выполнять программным путем. Они включают примеры кода на языке C#, в которых демонстрируются операции CSOM.

При создании проекта надстройки для SharePoint в Visual Studio 2012 в проект автоматически добавляются ссылки на сборки .NET Framework, Microsoft.SharePoint.Client.Runtime.dll и Microsoft.SharePoint.Client.dll. Для других проектов, таких как приложения .NET Framework или консольные приложения, нужно добавить эти ссылки вручную. Файлы расположены на любом сервере SharePoint по адресу %ProgramFiles%\Common Files\Microsoft Shared\расширения веб-сервера\15\ISAPI.

Во всех этих примерах предполагается, что код находится в файле кода программной части для веб-страницы Microsoft ASP.NET. Следующее утверждение using должно быть добавлено в файл кода.

using Microsoft.SharePoint.Client;

Если не указано иное, предполагается, что каждый из этих примеров относится к методу, не содержащему параметров и определенному в классе страницы. Кроме того, label1, label2 и т. д. — это имена объектов Label на странице.

Примечание.

Когда вы создаете надстройку SharePoint, размещенную поставщиком, с веб-приложением ASP.NET и добавляете ссылку на сборку в проект веб-приложения в Visual Studio, установите для свойства Локальное копирование сборки значение True, если только вы не знать, что сборка уже установлена на веб-сервере, или вы можете убедиться, что она установлена перед развертыванием надстройки.

Платформа .NET Framework установлена для веб-ролей Microsoft Azure и веб-сайтов Azure. Но клиентские сборки SharePoint, а также различные расширения и основы управляемого кода Microsoft не установлены. Инструменты разработчика Office для Visual Studio 2012 автоматически добавляют ссылки на некоторые сборки, часто используемые в надстройках SharePoint, и устанавливают свойство Копировать локально.

Задачи, связанные с веб-сайтом SharePoint

В этих примерах показано, как использовать модель CSOM .NET Framework для выполнения задач, связанных с веб-сайтами.

Получите свойства веб-сайта

Следующий код служит для получения названия веб-сайта 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;

Получение определенных свойств веб-сайта

Иногда клиенту нужны только несколько свойств объекта. CSOM SharePoint .NET Framework не требует, чтобы вы получали все свойства объекта на сервере - вы можете использовать анонимные методы, которые могут быть лямбда-выражениями, для конкретного запроса имен свойств. Клиентская библиотека запрашивает на сервере только эти свойства, и сервер отправляет клиенту только эти свойства. Этот метод позволяет уменьшить объем ненужных данных, передаваемых между клиентом и сервером. Это также полезно, когда пользователь не имеет разрешения на одно или несколько других неиспользуемых свойств объекта.

Вам нужно добавить инструкцию using для пространства имен 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;

Примечание.

Если вы пытаетесь получить доступ к другим свойствам, код выдает исключение, потому что другие свойства недоступны.

Запись значений для свойств веб-сайта

В этом примере показано, как записать значения для свойств веб-сайта.

// 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();

Создание веб-сайта SharePoint

В этом примере показано, как создать дочерний сайт текущего веб-сайта SharePoint. Используйте класс WebCreationInformation для создания нового сайта. Также необходимо добавить инструкции using для System.Collections.Generic и 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;

Задачи, связанные со списками SharePoint

В этих примерах показано, как использовать модель CSOM .NET Framework для выполнения задач, связанных со списками.

Получение всех списков SharePoint на сайте

В этом примере показано, как извлечь все списки SharePoint на веб-сайте SharePoint. Чтобы скомпилировать код, нужно добавить оператор using для 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;
}

Примечание.

Кроме того, вы можете использовать метод LoadQuery для хранения возвращаемого значения в другой коллекции, а не использовать свойство web.Lists. Также потребуется добавить инструкции using для System.Collections.Generic и System.Linq. Кроме того, добавьте псевдоним в оператор “using” для пространства имен Microsoft.SharePoint.Client, чтобы вы могли однозначно ссылаться на его классы. Например, 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;
}

Создание и обновление списка SharePoint

В этом примере создается список SharePoint и обновляется его с помощью класса 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();

Удаление списка SharePoint

В этом примере удаляется список 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();

Добавление поля в список SharePoint

В этом примере показано, как добавить поле в список SharePoint. Добавьте псевдоним в оператор using для пространства имен Microsoft.SharePoint.Client, чтобы вы могли однозначно ссылаться на его классы. Например, using SP = Microsoft.SharePoint.Client;.

Примечание.

В этом примере для выполнения приведения используется context.CastTo. Перед выполнением запроса клиентская библиотека не знает реальный тип возвращаемого объекта «поле», и SharePoint.Field является единственным возможным типом. Если вы знаете реальный тип, вы можете использовать метод ClientContext.CastTo<RealType> для приведения объекта.

// 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();

Задачи, связанные с элементами списков SharePoint

В этих примерах демонстрируется использование модели CSOM .NET Framework для выполнения задач, связанных с элементами списков.

Получение элементов из списка SharePoint

В этом примере показано, как извлечь элементы из списка SharePoint. Также необходимо добавить оператор using для Microsoft.SharePoint.Client.QueryExpression.

Примечание.

С помощью свойства FolderServerRelativeUrl вы можете ограничить возвращаемые элементы только теми, которые находятся в указанной папке.

// 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"];
}

Создание элемента списка

В этом примере создается новый элемент списка SharePoint с использованием класса 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();

Обновление элемента списка

В этом примере обновляется элемент списка 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();

Удаление элемента списка

В этом примере удаляется элемент списка 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(); }

Задачи, связанные с полями SharePoint

В этих примерах показано, как использовать модель CSOM .NET Framework в SharePoint для выполнения задач, связанных с полями.

Получение всех полей в списке

В этом примере показано, как получить все поля в списке SharePoint. Кроме того, необходимо добавить псевдоним в оператор using для пространства имен Microsoft.SharePoint.Client, чтобы можно было ссылаться на его классы неоднозначно; Например, 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;
}

Получение определенного поля из списка

Если вы хотите получить информацию о конкретном поле, используйте метод Fields.GetByInternalNameOrTitle. Тип возврата этого метода - Field. Перед выполнением запроса клиент не знает тип объекта, и синтаксис C # недоступен для приведения его к производному типу. Поэтому используйте метод ClientContext.CastTo для его приведения, который инструктирует клиентскую библиотеку воссоздать объект. Также необходимо добавить оператор using для System.Collections.Generic. Кроме того, необходимо добавить псевдоним в оператор using для пространства имен Microsoft.SharePoint.Client, чтобы можно было однозначно ссылаться на его классы. Например, using SP = Microsoft.SharePoint.Client;.

Примечание.

Метод GetByInternalNameOrTitle, используемый в этом примере, является удаленным методом. Он не использует данные из клиентской коллекции, даже если клиентская коллекция уже заполнена.

// 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;

Задачи, связанные с пользователями SharePoint

Вы можете использовать модель CSOM .NET Framework в SharePoint для управления пользователями и группами SharePoint, а также безопасностью пользователей.

Добавление пользователя в группу SharePoint

В этом примере в группу SharePoint с именем Members добавляется пользователь и некоторые сведения о нем.

// 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();

Получение всех пользователей из группы SharePoint

В этом примере извлекаются сведения о всех пользователях в группе SharePoint с именем Members.

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

Создание роли

В этом примере создается роль, имеющая разрешения на создание оповещений и управление ими.

// 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();

Добавление пользователя к роли

В этом примере к роли добавляется пользователь.

// 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();

Правила и рекомендации по клиентской объектной модели .NET в SharePoint

В этих примерах демонстрируются некоторые важные рекомендации и требования, которые следует соблюдать при использовании модели CSOM .NET Framework в SharePoint.

Вызов метода ClientContext.ExecuteQuery перед доступом к свойствам значений

Модель CSOM SharePoint .NET Framework требует использования шаблона программирования наподобие SQL: необходимо объявить запрос и выполнить его перед доступом к данным. Например, при выполнении следующего кода, который пытается отобразить название веб-сайта SharePoint, выдается исключение.

// 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;

Сбой произойдет по той причине, что в коде CSOM .NET Framework в SharePoint необходимо выполнить следующие действия:

создать специальный запрос SQL или хранимую процедуру
выполнить запрос SQL
читать результаты из SQL

В модели CSOM SharePoint .NET Framework при вызове метода создается запрос. Запросы накапливаются и не отправляются на сервер до вызова ExecuteQuery .

Ниже показано код, необходимый для отображения названия веб-сайта. Кроме того, нужно добавить инструкцию using для пространства имен System.Linq. Кроме того, добавьте псевдонимы в оператор using для пространства имен Microsoft.SharePoint.Client, чтобы можно было однозначно ссылаться на классы. Например, 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;

Различия заключаются в добавлении этих строк; первая строка создает запрос для свойства сети Title. Вторая строка выполняет запрос.

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

Не используйте объекты-значения, возвращаемые методами или свойствами в одном запросе

Когда объект значения возвращается из метода или свойства, вы не можете использовать этот объект, пока не выполните запрос. Например, приведенный ниже код пытается создать список SharePoint с тем же названием, что и у родительского веб-сайта, но выдается исключение.

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

Выдается исключение, потому что свойство недоступно до выполнения запроса. В SQL можно объявить локальную переменную для хранения значения web.Title и использовать ее для создания сайта. В клиентской библиотеке создать локальную переменную нельзя. Вы должны разделить функциональность на два отдельных запроса, как показано в следующем примере. Кроме того, нужно добавить инструкцию using для пространства имен System.Linq. Кроме того, добавьте псевдоним в оператор “using” для пространства имен Microsoft.SharePoint.Client, чтобы вы могли однозначно ссылаться на его классы. Например, 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();

Отличие заключается в следующих трех строках:

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

Использование методов или свойств, возвращающих клиентские объекты, в вызове другого метода в том же запросе

В отличие от объекта значения, клиентский объект можно использовать в вызове другого метода в том же запросе.

В удаленной среде .NET объект значения представляет собой класс или структуру, маршалируемую по значению, а клиентский объект класс или структуру, маршалируемую по ссылке. Например, ListItem — это клиентский объект, в то время как UrlFieldValue и другие значения полей являются объектами значений.

В клиентской библиотеке соответствующий объект сервера имеет атрибут [ClientCallable(ValueObject = true)]. Эти значения могут иметь только свойства и не иметь методов. Примитивные типы, такие как строки и целочисленные значения, обрабатываются как объекты значений. Для всех значений выполняется маршалинг между клиентом и сервером. Значение по умолчанию для ValueObject - false.

Аналогом объекта значения является клиентский объект. Если соответствующий объект сервера имеет атрибут [ClientCallable(ValueObject = false)], объект является клиентским объектом. Для клиентских объектов мы отслеживаем, как создается объект; это называется ObjectPath в реализации клиентской библиотеки. Например, если у нас есть код, подобный следующему:

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

Мы знаем, что список создается следующим образом:

получение свойства Web из контекста
получение свойства Lists из приведенного выше результата
вызов метода GetByTitle с параметром Объявления из приведенного выше результата

Когда модель CSOM SharePoint .NET Framework передает эту информацию на сервер, вы можете воссоздать объект на сервере. В клиентской библиотеке вы можете отслеживать ObjectPath, созданный клиентским объектом. Вы знаете, как создан объект, поэтому можете использовать его как параметр для вызова других методов в том же запросе.

Получение сгруппированных данных из одного объекта для повышения производительности

При считывании нескольких фрагментов данных из одного объекта следует попытаться получить все это в одном запросе; т. е Load<T>(T, []) . один вызов метода . В приведенном ниже коде показаны два способа получения названия и описания веб-сайта, а также описания списка Announcements. Чтобы скомпилировать код, нужно добавить оператор using для System.Linq. Кроме того, добавьте псевдонимы в оператор using для пространства имен Microsoft.SharePoint.Client, чтобы можно было однозначно ссылаться на классы. Например, 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();
}

Это не одинаково эффективно. В Method1, код для получения заголовка и описания сети сгруппированы вместе. В Method2, код для получения заголовка и описания сети отделяется другими действиями. Это означает, что Method2 запускает два отдельных запроса для одного и того же веб-объекта, и для одной и той же сети есть два набора результатов. Так как клиентская библиотека пытается возвращать согласованные данные, второй набор результатов включает как название, так и описание. Предыдущий код можно представить следующим образом.

// 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 …

Указание свойств объектов, которые необходимо вернуть

В объектной модели сервера SharePoint, если вы получаете объект SPWeb, вы можете проверить все его свойства. В SQL, чтобы получить все столбцы таблицы, вы можете запустить:

SELECT * FROM Webs

В клиентской библиотеке ни Load<T>, ни какой-либо другой метод не возвращают все свойства, поэтому вам нужно явно указать, что вы хотите. Например, следующий код извлекает объект веб-сайта, не указывая, какие свойства возвращать. Затем он пытается прочитать два свойства, и одно из них не входит в число свойств, автоматически возвращаемых Load. Создается исключение.

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

Для успешной компиляции кода обновите его так, как показано ниже. Чтобы скомпилировать код, нужно добавить оператор using для System.Linq. Кроме того, добавьте псевдонимы в оператор using для пространства имен Microsoft.SharePoint.Client, чтобы можно было однозначно ссылаться на классы. Например, 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);

Использование условной области для проверки предварительных условий перед загрузкой данных

Чтобы условно выполнить код, установите условную область с помощью объекта ConditionalScope. Например, получить свойство списка, если список не нулевой. Также необходимо добавить инструкции using для System.Collections.Generic и System.Linq. Кроме того, добавьте псевдонимы в оператор using для пространства имен Microsoft.SharePoint.Client, чтобы можно было однозначно ссылаться на классы. Например, using SP = Microsoft.SharePoint.Client;.

Примечание.

Вызов метода и установка свойств в условной области не разрешены, поскольку клиентская библиотека не отслеживает побочные эффекты вызовов методов и настроек свойств. Вы должны использовать только Load внутри условного объема.

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

Использование области обработки исключений для перехвата исключений

В этом примере показано, как создать и использовать область обработки исключений для объекта ExceptionHandlingScope. Сценарий предполагает обновление описания списка и обеспечение создания папок. Существует вероятность того, что список может не существовать.

// 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();

Выполнение базовых операций с использованием кода библиотеки клиента в SharePoint

Основные операции с клиентской объектной моделью .NET в SharePoint

Задачи, связанные с веб-сайтом SharePoint

Получите свойства веб-сайта

Получение определенных свойств веб-сайта

Запись значений для свойств веб-сайта

Создание веб-сайта SharePoint

Задачи, связанные со списками SharePoint

Получение всех списков SharePoint на сайте

Создание и обновление списка SharePoint

Удаление списка SharePoint

Добавление поля в список SharePoint

Задачи, связанные с элементами списков SharePoint

Получение элементов из списка SharePoint

Создание элемента списка

Обновление элемента списка

Удаление элемента списка

Задачи, связанные с полями SharePoint

Получение всех полей в списке

Получение определенного поля из списка

Задачи, связанные с пользователями SharePoint

Добавление пользователя в группу SharePoint

Получение всех пользователей из группы SharePoint

Создание роли

Добавление пользователя к роли

Правила и рекомендации по клиентской объектной модели .NET в SharePoint

Вызов метода ClientContext.ExecuteQuery перед доступом к свойствам значений

Не используйте объекты-значения, возвращаемые методами или свойствами в одном запросе

Использование методов или свойств, возвращающих клиентские объекты, в вызове другого метода в том же запросе

Получение сгруппированных данных из одного объекта для повышения производительности

Указание свойств объектов, которые необходимо вернуть

Использование условной области для проверки предварительных условий перед загрузкой данных

Использование области обработки исключений для перехвата исключений

См. также

Дополнительные ресурсы