快速浏览 SharePoint 对象模型

项目
04/08/2023

这是关于开发 SharePoint 托管的 SharePoint 加载项的基础知识系列文章中的第 4 篇文章。你应该首先熟悉 SharePoint 加载项以及本系列中之前的文章（可在创建提供程序托管的 SharePoint 加载项入门中找到相关内容）。

注意

如果已完成有关提供商托管加载项的本系列文章之一，便已生成 Visual Studio 解决方案，可以在继续阅读本主题的过程中使用。也可以从 SharePoint_SP-hosted_Add Ins_Tutorials 下载存储库，再打开 BeforeSharePointWriteOps.sln 文件。

在本文中，将暂别编码，改为简要概览 SharePoint 客户端对象模型 (CSOM)。此模型很大，MSDN 中有很多参考主题、“操作说明”和代码示例。本文只是冰山上非常小的一角。不过，即使是非常简短的介绍，也会让本系列中的大部分代码变得不太那么难理解。

内容层次结构

下表列出了 SharePoint 中的内容层次结构以及表示它们的 CSOM 类。其中每个实体的正下面都是它的子类型。

实体	类	备注
本地 SharePoint 服务器场或 SharePoint Online 订阅（也称为租户）		CSOM 中对此级别的编程访问有限。例如，没有 Farm、Subscription 或 Tenant 类。 (SharePoint 的服务器端对象模型（不能在外接程序中使用）允许以编程方式访问这些实体。)
site collection	Site	主要出于管理原因而归入一组的网站，囊括可应用于所有子网站的品牌母版页或自定义安全组等 SharePoint 组件。所有网站均属于某网站集。
website	Web	一组页面和 SharePoint 组件。可以有子网站。
list	List	文档库和其他类型的库也属于此级别。文档库是一种特殊类型的列表，其中每行均包含一个附加文档，其他列则包含关于文档的数据，例如其作者、上次编辑时间以及签出者。
list item	ListItem	列表中的一行即列表项，它在行的字段中具有特定值。也具有类型。请参阅下一行。
list item	Content Type	列表项的类型。由 ContentType 类表示。每个列表项基本上都是一组列和元数据。最简单的是内置 Item 内容类型。所有其他内容类型均派生自 Item。 SharePoint 包含许多内置的内容类型，如事件和通知。
column	Field	Field 对象不仅包括与基础数据类型有关的信息，还包括有关数据在表单上如何格式化和呈现的信息，例如用于创建、显示和编辑特定列表项的表单。

可以编程方式创建自定义列表、内容类型、列类型和列表项。

除了内容之外，CSOM 还支持访问用户、组、角色和权限、分类、搜索功能等。

客户端运行时和批处理

CSOM 使用批处理系统。多个托管代码块转换成 XML，并通过一个 HTTP 请求发送到服务器。对于每个命令，将会调用相应的服务器对象模型，然后服务器会以 JavaScript 对象表示法 (JSON) 格式向客户端返回响应。

客户端上的 SharePoint 代码会先检索表示当前请求上下文的客户端上下文对象，包括 SharePoint 网站（及其父网站集）的标识。通过此上下文，可以获取对 CSOM 对象的访问权限。下面展示了基本结构，可能会反复看到。

  using (var clientContext = spContext.CreateUserClientContextForSPHost())
  {
      // CRUD operation or query code goes here.

      clientContext.ExecuteQuery();
  }

关于此代码，请注意以下几点：

spContext 对象的类型为 SharePointContext，在 Visual Studio 的 Office 开发人员工具生成的 SharePointContext.cs/.vb 文件中进行定义。可以修改此文件，但很少需要这样做。对于大多数 SharePoint 加载项项目，此文件和 TokenHelper.cs/.vb 文件（也是由工具生成）可有效用作 CSOM 本身的扩展。
clientContext 对象是 CSOM 类型 ClientContext。
ExecuteQuery 方法将 CRUD 操作代码捆绑到它发送到 SharePoint 服务器的 XML 消息中。在其中，它被翻译成等效的服务器端对象模型代码，并予以执行。

本系列的上一篇文章中有此模式的示例，如下面的 GetLocalEmployeeName 方法所示。

private string GetLocalEmployeeName()
{
    ListItem localEmployee;

    using (var clientContext = spContext.CreateUserClientContextForSPHost())
    {
        List localEmployeesList = clientContext.Web.Lists.GetByTitle("Local Employees");
        localEmployee = localEmployeesList.GetItemById(listItemID);
        clientContext.Load(localEmployee);
        clientContext.ExecuteQuery();
    }
    return localEmployee["Title"].ToString();
}

对于此方法，请注意以下事项：

using 块中的前两行似乎会获取对列表和列表项对象的引用。但实际上，当这些行在 SharePoint 客户端运行时中执行时，它们只会转换为 XML 格式。 ExecuteQuery 方法会将该 XML 发送到服务器。
Load 方法向此消息添加一些额外信息，即指示服务器将指定对象向下发送到客户端。 ExecuteQuery 方法接收此对象（以 JSON 形式），并用它来初始化客户端 localEmployee 变量。随后，客户端代码引用 ListItem 对象及其成员。可以看到，下一代码行引用项的 "Title" 字段值。如果尚未调用 Load 方法，此代码行会抛出异常，因为只有先加载这个对象，客户端上才有它。

后续步骤

下一篇文章将回归编码，介绍如何将 SharePoint 写入操作添加到提供程序托管加载项。

快速浏览 SharePoint 对象模型

内容层次结构

客户端运行时和批处理

后续步骤

其他资源