使用 SharePoint 客户端库代码完成基本操作

项目
04/08/2023

可以使用 SharePoint 客户端对象模型 (CSOM) 在 SharePoint 中检索、更新和管理数据。 SharePoint 按以下几种形式提供此 CSOM：

.NET Framework 可再发行程序集
JavaScript 库 (JSOM)
REST/OData 终结点
Windows Phone 程序集（已弃用）
Silverlight 可再发行程序集（已弃用）

若要详细了解 SharePoint 平台上的 API 集，请参阅在 SharePoint 中选择合适的 API 集。

本文介绍如何使用 .NET Framework 对象模型执行基本操作，该模型可作为可再发行包在 NuGet 库上使用。

若要了解如何使用其他客户端 API，请参阅：

使用 SharePoint .NET 客户端对象模型执行的基本操作

以下各节介绍可以通过编程方式完成的任务，这些内容包括演示 CSOM 操作的 C# 代码示例。

在 Visual Studio 2012 中创建 SharePoint 外接程序项目时，对 .NET Framework 程序集、Microsoft.SharePoint.Client.Runtime.dll 和 Microsoft.SharePoint.Client.dll 的引用将自动添加到该项目中。对于 .NET Framework 应用程序或控制台应用程序等其他类型的项目，应添加这些引用。文件位于 %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\15\ISAPI 中的任何 SharePoint 服务器上。

所有这些示例都假设代码位于 Microsoft ASP.NET 网页的代码隐藏文件中。必须将以下 using 语句添加到代码文件中。

using Microsoft.SharePoint.Client;

除了指定的内容之外，还可以假定这些示例中的每一个示例均位于在页面的类中定义的无参数方法中。此外，label1、label2 等为页面上 Label 对象的名称。

注意

若要在 ASP.NET Web 应用程序中生成提供程序托管 SharePoint 外接程序，并将对程序集的引用添加到 Visual Studio 中的 Web 应用程序项目中，请将程序集的 Copy Local 属性设置为 True，除非确定程序集已安装在 Web 服务器上，或能确保程序集已在外接程序部署前安装。

.NET Framework 安装在 Microsoft Azure Web 角色和 Azure 网站中。不过，SharePoint 客户端程序集和各种 Microsoft 托管代码扩展和基础组件并未安装。 Visual Studio 2012的 Office 开发人员工具自动添加对 SharePoint 加载项中常用的某些程序集的引用，并设置 Copy Local 属性。

SharePoint 网站任务

以下示例演示如何使用 .NET Framework CSOM 完成与网站相关的任务。

检索网站的属性

检索 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;

仅检索网站的选定属性

有时，客户端仅对几个对象的属性感兴趣。 SharePoint .NET Framework CSOM 不要求用户从服务器上的对象中获取所有属性，可以使用匿名方法（可以是 lambda 表达式）来专门请求属性名称。客户端库仅查询服务器上的这些属性，服务器仅将这些属性发送到客户端。此技术可减少客户端和服务器之间不必要的数据传输。此外，在用户不具备对象上一个或多个其他未使用属性的权限时，此技术也非常有帮助。

你需要为 System.Linq 添加 using 语句。

// 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 课堂创建一个新网站。还需要为 System.Collections.Generic 和 System.Text 添加 using 语句。

// 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 列表任务

以下示例演示如何使用 .NET Framework CSOM 完成与列表相关的任务。

检索网站中的所有 SharePoint 列表

本示例检索 SharePoint 网站中的所有 SharePoint 列表。若要编译此代码，需要为 System.Linq 添加 using 语句。

// 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 属性。还需要为 System.Collections.Generic 和 System.Linq 添加 using 语句。此外，为 Microsoft.SharePoint.Client 命名空间的 using 语句添加一个别名，以便清楚地引用其类。例如，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 列表

此示例使用 ListCreationInformation 类创建 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;

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 列表添加域。为 Microsoft.SharePoint.Client 命名空间的 using 语句添加一个别名，以便清楚地引用其类。例如，using SP = Microsoft.SharePoint.Client;。

注意

该示例使用 context.CastTo 执行强制转换。执行查询之前，客户端库不知道返回对象“field”的真实类型，而 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 列表项任务

以下示例演示如何使用 .NET Framework CSOM 完成与列表项相关的任务。

检索 SharePoint 列表中的项

本示例检索 SharePoint 列表中的项。还需要为 Microsoft.SharePoint.Client.QueryExpression 添加 using 语句。

注意

你可以使用 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"];
}

创建新的列表项

此示例使用 ListItemCreationInformation 类创建新的 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");

// 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 域任务

以下示例演示如何使用 SharePoint .NET Framework CSOM 完成与域相关的任务。

检索列表中的所有域

本示例检索 SharePoint 列表中的所有域。此外，你还需要为 Microsoft.SharePoint.Client 命名空间的 using 语句添加一个别名，以便清楚地引用其类，例如，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 方法将其强制转换，这将指示客户端库重新创建一个对象。还需要为 System.Collections.Generic 添加 using 语句。此外，你还需要为 Microsoft.SharePoint.Client 命名空间的 using 语句添加一个别名，以便清楚地引用其类。例如，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 用户任务

可使用 SharePoint .NET Framework CSOM 管理 SharePoint 用户、组和用户安全。

向 SharePoint 组添加用户

此示例向名为“成员”的 SharePoint 组添加一名用户和一些用户信息。

// 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 组中的所有用户的信息。

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

使用 SharePoint .NET 客户端对象模型的规则和最佳实践

这些示例阐释在使用 SharePoint .NET Framework CSOM 时应遵循的一些重要最佳做法和要求。

在访问任何值属性之前调用 ClientContext.ExecuteQuery

SharePoint .NET Framework CSOM 要求使用类似于 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;

此代码失败，因为 SharePoint .NET Framework CSOM 代码必须：

生成临时 SQL 查询或存储过程
执行 SQL 查询
读取 SQL 的结果

在 SharePoint .NET Framework CSOM 中，当调用方法时，将生成查询。查询累积，在调用之前 ExecuteQuery 不会发送到服务器。

以下示例介绍显示网站标题所需的代码。还需要为 System.Linq 添加 using 语句。此外，为 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 的值，并使用本地变量来创建网页。在客户端库中，无法创建本地变量。必须将功能划分为两个单独的查询，如下例所示。还需要为 System.Linq 添加 using 语句。此外，为 Microsoft.SharePoint.Client 命名空间的 using 语句添加一个别名，以便清楚地引用其类。例如，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 属性
使用上面结果中的 Announcements 参数调用 GetByTitle 方法

当 SharePoint .NET Framework CSOM 将该信息传递到服务器时，可以在该服务器上重新创建对象。在客户端库中，可以跟踪客户端对象创建的 ObjectPath。因为你知道对象是如何创建的，因此，可以使用对象作为参数来调用同一查询中的其他方法。

将同一对象上的数据检索分组在一起以改进性能

从同一对象读取多个数据时，应尝试在单个查询中获取所有数据;即对方法的单个调用 Load<T>(T, []) 。下面的代码演示检索网站标题和说明以及 Announcements 列表的说明的两种方法。若要编译此代码，需要为 System.Linq 添加 using 语句。此外，为 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 在同一 Web 对象中触发了两个单独的查询，并且针对同一 Web 有两个结果集。由于客户端库尝试返回一致的数据，因此，第二个结果集同时包含标题和说明。可以将前面的代码视为以下内容。

// 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 Server 对象模型中，如果获取 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);

若要成功获取代码进行编译，请将其更新为以下内容。若要编译此代码，需要为 System.Linq 添加 using 语句。此外，为 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 对象设置条件范围。例如，在列表不为 null 时检索列表属性。还需要为 System.Collections.Generic 和 System.Linq 添加 using 语句。此外，为 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();