通过

将自动托管的 SharePoint 加载项转换为提供程序托管的加载项

  • 项目

除了前面使用基于解决方案的自定义项的方法之外，Microsoft SharePoint 还引入了一种用来扩展 SharePoint 网站的新方法。 这种用于 SharePoint 的新扩展模型称为外接程序模型，它使开发人员无论在本地、SharePoint Online，还是在混合部署中运行，都能够创建可部署到 SharePoint 环境中的自定义实现。

开发人员可以生成两种不同类型的 SharePoint 加载项。第一种类型是 SharePoint 托管的加载项，主要运行在浏览器中；支持它的所有资产（如 HTML、CSS、图像和 JavaScript）都由 SharePoint 进行存储和提供支持。 另一种类型的加载项属于云加载项模型 (CAM)，主要在 SharePoint 外部的另一台服务器上运行，并通过客户端对象模型 (CSOM) 和 REST API 与 SharePoint 进行通信。 它们使用 SharePoint 支持的热门 OAuth 2.0 协议建立标识。

开发人员可以使用加载项模型以提供程序托管的加载项或自动托管的加载项这两种方式中的任一方式来实现加载项。 当 SharePoint 发布时自动托管的加载项发布为预览计划，但在 2014 年 5 月，Microsoft 宣布他们将关闭预览计划，不再支持创建自动托管的加载项。有关通知的信息，请参阅自动托管的加载项的预览计划更新。

本文介绍了如何将自动托管的外接程序转换和迁移到提供程序托管的外接程序。 然而，重要的是开发人员要理解这两种方法之间的一些特定差异，因为具备这方面的知识可以大大简化转换过程。

将自动托管的加载项转换为提供程序托管的加载项的先决条件

转换自动托管的加载项之前需要了解的核心概念

将自动托管的加载项转换为提供程序托管的加载项之前，应该对 SharePoint 加载项以及 SharePoint 托管的加载项、提供程序托管的加载项与自动托管的 SharePoint 加载项之间的区别有一个基本的了解。可以通过下表中所列的文章了解这些信息。

文章标题 说明
SharePoint 外接程序 了解 SharePoint 中新的外接程序模型，可以利用此模型来创建对最终用户来说是小型且易于使用的解决方案的外接程序。
SharePoint 外接程序体系结构和开发前景的重要方面 了解 SharePoint 外接程序和 SharePoint 外接程序的模型的体系结构的各个方面，包括外接程序托管选项、用户界面 (UI) 选项、部署系统、安全系统和生命周期。
选择用于开发和托管 SharePoint 外接程序的模式 了解您可以托管 SharePoint 外接程序的各种方式。
SharePoint 中的主机 Web、外接程序 Web 和 SharePoint 组件 了解主机 Web 和外接程序 Web 之间的差异。 了解 SharePoint 外接程序中可以包括哪些 SharePoint 组件、将哪些组件部署到主机 Web、将哪些组件部署到外接程序 Web 以及如何将外接程序 Web 部署到隔离域中。

转换加载项

将自动托管的 SharePoint 加载项转换为提供程序托管的加载项涉及对两个或三个组件的修改：

  • SharePoint 加载项本身
  • 远程 Web 应用程序或服务
  • 加载项中的 Microsoft Azure SQL 数据库（如果有）

在安装 SharePoint 自动托管的加载项时，它会自动部署到 Azure 网站和 Azure SQL 数据库；但是，提供程序托管的加载项可能在任何 Web 平台上拥有其远程 Web 应用程序及其他服务。 本文假定自动托管的加载项中的远程组件在转换为提供程序托管的加载项后，仍作为 Azure 服务。

以下各节逐步介绍将自动托管的加载项转换为提供程序托管的加载项的过程。 使用的自动托管的加载项示例 Customer Manager 非常简单，让用户可以专注于转换步骤而非实际加载项。 它包括三个项目：

  • CustomersDb：生成必要的 *.dacpac 的 SQL 数据库项目。 请注意，此项目中不定义架构。 它只用于创建数据库，因为架构由 ASP.NET Web 应用程序创建。

  • CustomerManagerAH：SharePoint 自动托管的加载项，配置为将 ASP.NET Web 应用程序项目和 Azure SQL 数据层应用程序包含在生成的 SharePoint 加载项包中。

  • CustomerManagerAHWeb：ASP.NET MVC Web 应用程序，使用“Entity Framework Code First 迁移”方法来创建数据库架构以及对数据库进行读取和写入。

该加载项是一个 ASP.NET MVC Web 应用程序，既可以从 Azure SQL 数据库的表中显示客户，也可以添加新客户。 这是一个匿名 Web 应用程序，任何人都可以查看或添加客户。 可以从以下公共存储库下载自动托管加载项和相关项目的 Visual Studio 解决方案： Autohosted-Migration-Code-Samples。

将 SharePoint 自动托管的加载项转换为提供程序托管的加载项包含多个步骤。 以下各节列出了这些步骤：

  1. 部署 Azure SQL 数据库

  2. 创建用于托管远程 Web 应用程序的 Azure 网站

  3. 使用您的 SharePoint 网站注册外接程序

  4. 更新和部署用于远程 Web 应用程序的 Azure 网站

  5. 重新配置 SharePoint 加载项项目

部署 Azure SQL 数据库

将自动托管的加载项转换为提供程序托管的加载项的第一步是部署 ASP.NET Web 应用程序所依赖的 Azure SQL 数据库。 可通过许多不同的方法创建 Azure SQL 数据库，Azure 文档网站中记录了一些方法：将 SQL Server 数据库迁移到云中的 SQL 数据库。

以下步骤中所述方法使用数据层应用程序部署模式，因为这是将数据库部署在 SharePoint 自动托管的外接程序中的方法。 这涉及到生成数据层应用程序包 (*.dacpac) 和使用它来创建数据库。

创建 Azure SQL 数据库

  1. 在 Visual Studio 中打开自动托管的解决方案。

  2. 右键单击数据库项目“CustomerDb”，然后选择“生成”。 这将在 [..]\bin\[debug | release] 文件夹中生成 CustomerDb.dacpac 文件。

  3. 创建新的 Azure SQL 数据库。 登录到 Azure 门户，在仪表板完成加载后，选择边距中的“SQL 数据库”链接。

    Azure SQL 数据库列表


  4. 选择顶部导航栏中的“服务器”链接，然后选择页脚的“添加”按钮，如下图所示。

    Azure SQL 数据库“添加”按钮


  5. 在出现的“创建服务器”对话框中，为将有权访问服务器的用户选择 Azure“订阅”、“登录名”和“密码”，然后选择在之前创建 Azure 网站时使用的同一“区域”。 记下登录名和密码以供后续步骤使用。

    Azure SQL 新建 DB 对话框


  6. 填写表单后，选择右下角的选中图标创建数据库。 现在服务器已创建，但有权访问它的唯一资源是其他 Azure 服务。 记下 Azure SQL 数据库的名称，在后续步骤中将会使用该名称。

部署 Azure SQL 数据库

  1. 要连接到 Azure SQL 数据库并部署数据库，必须创建防火墙规则，以允许来自部署数据库的计算机的流量。 否则，与 Azure SQL 数据库的连接将被拒绝，并显示如下图所示的错误。

    连接到服务器错误


  2. 若要创建防火墙规则，请在 Azure 门户中选择先前创建的 Azure SQL 数据库，然后选择顶部导航栏中的“配置”链接。

  3. 在“允许的 IP 地址”部分，IP 地址当前如下图显示。 选择“添加到允许的 IP 地址”以添加防火墙规则。 执行此操作将允许连接到 Azure SQL 数据库并部署数据库。 选择页脚中的“保存”。

    Azure SQL 创建防火墙规则


  4. 使用 Azure SDK for .NET 2.3 从 Visual Studio 部署数据库。

  5. 在 Visual Studio 中打开“SQL Server 对象资源管理器”工具窗口，右键单击“SQL Server”节点，然后选择“添加 SQL Server”。

    从 Visual Studio 连接到 Azure SQL 数据库


  6. 在“连接到服务器”对话框中，输入“服务器名称”，将“身份验证”设置为“SQL Server 身份验证”，然后输入与创建 Azure SQL 数据库时定义的相同“登录名”和“密码”。 服务器名称应当是该服务器的完全限定的名称，即 [server-name].database.windows.net，如下图所示。

    SQL 登录到服务器对话框


  7. 连接到 Azure SQL 数据库后，为新添加的服务器扩展节点，右键单击“数据库”节点，然后选择“发布数据层应用程序”以弹出发布向导。

  8. 在“源数据层应用程序 (.dacpac)”部分，使用“浏览”按钮找到上一步骤中构建数据库项目时生成的 *.dacpac 文件，并确认“数据库名称”设置为 CustomerDb。

  9. 然后选择“发布”来发布 Azure SQL 数据库中的 CustomerDb。

    发布 DACPAC 对话框


  10. 刷新 Visual Studio"SQL Server 对象资源管理器"工具窗口查看"数据库"节点下列出的 CustomerDb。

注意

根据针对自动托管的加载项创建数据库的方式，可能需要执行一些额外的工作将其部署到 Azure。 有关详细信息，请参阅 在 Visual Studio 中创建和管理数据库和数据层应用程序创建和管理数据层应用程序

部署后操作

在创建 Azure SQL 数据库后，为用于建立到数据库的连接的字符串创建一个副本。 可通过两种方法获取。

  • 一种方法是登录到“Azure 门户”，然后转到在最后一个步骤中创建的 Azure SQL 数据库：CustomerDb。 在数据库的“仪表板”页上，选择链接“显示连接字符串”以查看连接字符串的列表。 创建 ADO.NET 连接字符串副本以便稍后使用。

    Azure SQL 连接字符串对话框


  • 假如安装了 Azure SDK v2.3，则另一种方法是从 Visual Studio 中获取连接字符串。 在 Visual Studio 的“SQL Server 对象资源管理器”工具窗口中，选择数据库 CustomerDb。 在选择数据库后，请检查“属性”工具窗口，以查看连接字符串。 它与在 Azure 门户中找到的值相同。

    在 Visual Studio 中获取 SQL 连接字符串


创建 Azure 网站

下一步是创建一个新的 Azure 网站，其中远程 Web 应用程序将驻留在提供程序托管的加载项中。 必须先完成此操作，因为在注册加载项之前需要远程 Web 应用程序的 URL。 但是，在部署 SharePoint Web 应用程序的文件之前，应该先在 SharePoint 中注册加载项，因为注册过程有两个输出（客户端 ID 和客户端密码），在部署 ASP.NET Web 应用程序文件之前需要这两个输出。

创建新的 Azure 网站

  1. 登录到 Azure 门户。 加载仪表板后，单击左侧边距处的“网站”导航链接，然后选择页脚中的“新建”按钮，如下图所示。

    Azure 网站仪表板


  2. 在“新建网站向导”中，依次选择“计算”、“网站”和“快速创建”，然后指定“URL”和“WEB 托管计划”。 最后指定应在其中创建网站的“区域”。 请务必记住所选的区域，因为在后面创建 Azure SQL 数据库时将用到同一区域。

  3. 如果 Web 托管计划尚不存在或需要新建一个，则选择选项“新建 Web 托管计划”。 下图举了一个例子。

    创建 Azure 网站对话框


  4. 创建了 Azure 网站之后，请记下该网站所使用的 URL。 在上图中，创建的网站是 http://spahapptoph.azurewebsites.net。

注册新加载项

使用加载项模型创建的所有 SharePoint 加载项都必须使用托管 SharePoint 场或租户进行注册，以便能够在 SharePoint 和远程 Web 应用程序之间建立信任。 这涉及到通过使用 SharePoint 指定下列值来注册一个新的加载项主体：

  • 客户端 ID：加载项 ID
  • 客户端密码：加载项密码
  • 标题：加载项名称
  • 加载项域：远程 Web 应用程序的顶级域

在 SharePoint Online 中安装自动托管的加载项后，Office 365 会自动创建加载项主体。 它会自动创建网站，因此它知道远程 Web 应用程序的 URL。 此外，它还会获取客户端 ID 和客户端密码，并将它们添加到远程 Web 应用程序的 web.config 中。在通过 SharePoint 验证请求和身份验证时，Microsoft 提供的类会在 web.config 中（在 TokenHelper.cs 或 .vb 文件中）查找客户端 ID 和密码。

但是，在提供程序托管的加载项中，开发人员必须手动注册加载项，并手动更新 ASP.NET Web 项目中的 web.config。

注册新加载项

  1. 浏览到 SharePoint 网站的加载项注册页，将在该页中安装加载项。 此页面位于 http://[SharePoint-site-url]/_layouts/15/appregnew.aspx。

  2. 在加载项注册页上，将“加载项类型”设置为“在 Web 服务器上运行的加载项”，然后选择两个“生成”按钮以创建新的“客户端 ID”和“客户端密码”。

  3. 在“标题”字段中输入加载项的名称，并在“加载项域”字段中输入在之前步骤中创建的目标 Azure 网站的 URL。 最后，选择“创建”按钮。

  4. 在注册加载项后，SharePoint 显示在表单中用于创建注册的信息摘要。 为安全起见，请务必创建该信息的副本，特别是客户端 ID 和客户端密码，因为在后续步骤中将用到这些信息。

更新和部署用于远程 Web 应用程序的 Azure 网站

下一步是重新配置远程 Web 应用程序，将其部署为提供程序托管的加载项（而不是自动托管的加载项）。 可通过多种方法将 ASP.NET 站点部署到 Azure 网站，其中包括直接从 Visual Studio 进行部署、从诸如 Visual Studio Team Services 之类的源控件自动部署、从 GitHub 甚至通过经证明可靠的 FTP 选项进行部署。 本文中使用的是 Visual Studio。 但是，在部署 Web 应用程序之前，首先需要一些更新才能使用提供程序托管的加载项。

更新远程 Web 应用程序项目

ASP.NET MVC Web 应用程序需要进行的重大更改位于 web.config 文件中。 在此文件中，appSettings 节点中<存在三个>设置。 它们是 ClientId、 ClientSecret 和 SqlAzureConnectionString。 前两个供 Microsoft 提供的类（在 TokenHelper.cs 或 .vb 中）使用，以便进行身份验证及从远程 Web 应用程序与 SharePoint 进行通信。 后者 SqlAzureConnectionString 由外接程序用来连接到 Azure SQL 数据库。

在 SharePoint 自动托管的加载项中，安装该加载项时会创建 Azure 网站和 Azure SQL 数据库，与此同时，Office 365 会填充这些设置的值。 但是，在提供程序托管的加载项中，在部署该加载项之前，必须手动设置这些值。

一个选项是粘贴用于本文上述步骤中的三个设置的值，但这种方法的缺点是，如果它们需要更改，就需要手动更新 web.config 并重新部署到 Azure 网站。

另一个选项是只清除这些设置（原地保留设置键，仅 value="" 属性设置为一个空字符串），改为通过 Azure 门户在 Azure 网站设置中对它们进行定义。 这种方法意味着可以在不更新基本代码的情况下更改设置。 为此，请执行以下操作：

  1. 登录到 Azure 门户并转到在前面步骤中创建的 Azure 网站。

  2. 在“Azure 网站仪表板”页上，选择顶部导航栏菜单中的“配置”，然后向下滚动到“加载项设置”部分。

  3. 使用 web.config 文件中的相同设置名称添加三个新加载项设置。 将前面步骤中获取的值用于 ClientId、ClientSecret 和 SqlAzureConnectionString。

请确保 Azure SQL 数据库连接字符串正确且有效，因为在通过 Azure 门户 和 Visual Studio 公开连接字符串后，密码属性将替换为掩码。 应更改连接字符串中的掩码密码，以使用在创建针对 Azure SQL 数据库的登录时定义的正确密码。

将远程 Web 应用程序部署到 Azure 网站

现在，ASP.NET MVC Web 应用程序文件需要作为远程 Web 应用程序部署到 Azure 网站。

  1. 在 Visual Studio 中，右键单击 Web 项目，然后选择“发布”。 这将启动“发布 Web 向导”对话框。

  2. 在此对话框中，选择“Windows Azure 网站”，然后选择“发布”。

    在 Visual Studio 中发布网站对话框


  3. 选择在上一步骤中创建的 Azure 网站的名称，如下图所示，选择“确定”，并确保站点的 URL 是 HTTPS。

    选择现有网站对话框


  4. 选择“验证连接”，确保设置和连接处于良好的工作状态。

  5. 选择“发布”，此操作可使 Visual Studio 将 ASP.NET Web 应用程序部署到 Azure 网站。

  6. 复制网站的 URL。

部署网站后，Visual Studio 会启动默认调试浏览器并导航到 Azure 网站。 但是网站会显示错误，因为 ASP.NET MVC 控制器附有一个属性（特别是 SharePointContextFilter），该属性希望 SharePoint 能够在 HTTP POST 请求的标头中将特定值发送到该控制器，但默认情况下，该浏览器会启动 HTTP GET 请求，所以预计会出现此错误。

注意

有关将 ASP.NET Web 应用程序部署到 Azure 网站的其他选项，请参阅将本地 Git 部署到 Azure 应用服务。

Azure 网站的自定义域和 SSL 证书

所有 Azure 网站都使用以下命名约定：http[s]://[site-name].azurewebsites.net。 Microsoft 已经将通配符 SSL 证书添加到 *.azurewebsites.net 域下的所有网站，但客户可以使用自己的 Azure 网站自由地关联自定义域，也可以将自己的 SSL 证书用于这些自定义域。

有关使用自定义域的信息，请参阅将现有的自定义 DNS 名称映射到 Azure Web 应用。

有关为自定义域名添加自定义 SSL 证书的信息，请参阅将现有自定义 SSL 证书绑定到 Azure Web 应用。

重新配置 SharePoint 加载项项目

最后一步是重新配置 SharePoint 加载项项目。 SharePoint 加载项的 Visual Studio 项目将加载项类型配置为自动托管，需要将其更改为提供程序托管。

重新配置 SharePoint 加载项项目

  1. 在 SharePoint 加载项项目中，打开 AppManifest.xml 文件，并将“托管类型”选项从“自动托管”更改为“提供程序托管”。

  2. 将加载项的“起始页”设置为指向远程 Web 应用程序起始页的 URL，即 Azure 网站的 URL。 请务必包含查询字符串值 {StandardTokens}（如果还没有）。 这可确保在 SharePoint 打开远程 Web 应用程序时，可以将核心查询字符串标记添加到 URL。

  3. 通过在 Visual Studio“解决方案资源管理器”中选择 SharePoint 加载项项目，删除在 SharePoint 加载项项目中对 ASP.NET MVC Web 应用程序的引用。 在“属性”工具窗口中，将“Web 项目”属性设置为“(无)”，如下图所示。

    Visual Studio 中的 Web 项目属性


  4. 此步骤需要手动更新 AppManifest.xml 文件，因为某些设置不在设计器中公开。 要执行此操作，请将所有现有更改保存到 AppManifest.xml 文件，然后右键单击“解决方案资源管理器”中的相同文件，并选择“查看代码”。

    Visual Studio 中的应用部件清单 (manifest) 上下文菜单


  5. 在 AppManifest.xml 文件的代码视图中，删除对 ASP.NET MVC Web 应用程序项目和 SQL 数据层应用程序项目的两个引用，因为 SharePoint 提供程序托管的加载项不再需要这些引用。

  6. 创建新的 GUID 并替换 ProductId 属性中的现有 GUID。 这向 SharePoint 表明这是一个新的加载项，而不是对现有加载项的更新。

    重要

    如果现有 ProductId 已被使用，则在安装已转换的加载项时，SharePoint 将返回错误“提供的加载项与使用相同版本和产品 ID 的其他加载项不同”。

  7. <找到 RemoteWebApplication> 元素，并将 ClientId 属性更新为在向 SharePoint 注册外接程序时获得的 GUID，并在 Azure 网站的web.config加载项设置中使用的 GUID。

    应用部件清单 (manifest) 中的客户端 ID 属性


  8. 在保存对 AppManifest.xml 文件的所有更改后，加载项现可作为 SharePoint 提供程序托管的加载项用于测试。 将加载项部署到 SharePoint 场或 SharePoint Online 网站，验证转换步骤是否已正确执行。

另请参阅