“记录管理扩展”示例 SharePoint 外接程序

项目
03/21/2023

ECM.RecordsManagement 示例说明如何使用提供程序托管的外接程序来控制网站或列表的就地记录管理设置。

如果在自定义网站设置过程中配置就地记录管理设置，请使用该解决方案。

准备工作

若要开始，请从 GitHub 上的 Office 365 开发人员模式和做法项目下载 ECM.RecordsManagement 示例外接程序。

注意

本文中的代码按原样提供，不提供任何明示或暗示的担保，包括对特定用途适用性、适销性或不侵权的默示担保。

运行此外接程序之前：

激活网站集上的就地记录管理功能。
在网站设置中，确认你在“网站集管理”中可以看到“记录声明设置”。

使用 ECM.RecordsManagement 示例外接程序

当你启动 ECM.RecordsManagement 外接程序时，起始页面将显示两种可用的方案：

为网站启用就地记录管理（方案 1）
为列表启用就地记录管理（方案 2）

显示两种方案的外接程序起始页的屏幕截图。

可以使用方案 1 生成 UI，控制网站集中的记录管理设置。此外接程序 UI 类似于“网站设置”中的“记录声明设置”UI。还可以在网站集中激活或停用就地记录管理功能。

可以使用方案 2 生成 UI，控制列表中的记录管理设置。此外接程序 UI 类似于列表上库设置中的“记录声明设置”UI。

“库记录声明设置”页的屏幕截图。

方案 1

方案 1 解决了网站的就地记录管理功能和设置。加载项 UI 包括停用 (或激活) 按钮，如下图所示。选择此按钮可以在网站集中停用（或激活）就地记录管理功能。

显示现场记录管理停用或激活按钮的屏幕截图。

下面的代码在网站集中激活或停用就地记录管理功能。 DisableInPlaceRecordsManagementFeature 和 EnableSiteForInPlaceRecordsManagement 方法是 OfficeDevPnP.Core 中的 AppModelExtensions\RecordsManagementExtensions.cs 文件的一部分。

protected void btnToggleIPRStatus_Click(object sender, EventArgs e)
{
  if (cc.Site.IsInPlaceRecordsManagementActive())
  {
    cc.Site.DisableInPlaceRecordsManagementFeature();
    IPRStatusUpdate(false);
  }
  else
  {
    cc.Site.EnableSiteForInPlaceRecordsManagement();
    IPRStatusUpdate(true);
  }
}

OfficeDevPnP.Core 包含扩展方法，用于获取和设置网站范围内的所有就地记录管理设置。下面的代码来自 EnableSiteForInPlaceRecordsManagement 方法，展示了如何使用这些扩展方法设置限制，并指定谁可以在网站上声明或取消声明记录。

public static void EnableSiteForInPlaceRecordsManagement(this Site site)
{
  // Activate the In-Place Records Management feature if not yet enabled.
  if (!site.IsFeatureActive(new Guid(INPLACE_RECORDS_MANAGEMENT_FEATURE_ID)))
  {
    // Note: this also sets the ECM_SITE_RECORD_RESTRICTIONS value to "BlockDelete, BlockEdit".
    site.ActivateInPlaceRecordsManagementFeature();
  }

  // Enable in-place records management in all locations.
  site.SetManualRecordDeclarationInAllLocations(true);

  // Set restrictions to default values after enablement (this is also done at feature activation).
  EcmSiteRecordRestrictions restrictions = EcmSiteRecordRestrictions.BlockDelete | EcmSiteRecordRestrictions.BlockEdit;
  site.SetRecordRestrictions(restrictions);

  // Set record declaration to default value.
  site.SetRecordDeclarationBy(EcmRecordDeclarationBy.AllListContributors);

  // Set record undeclaration to default value.
  site.SetRecordUnDeclarationBy(EcmRecordDeclarationBy.OnlyAdmins);
}

如果用户更改就地记录管理设置，并选择“保存更改”按钮，将运行 btnSaveSiteScopedIPRSettings_Click 方法中的下列代码。

protected void btnSaveSiteScopedIPRSettings_Click(object sender, EventArgs e)
{
  EcmSiteRecordRestrictions restrictions = (EcmSiteRecordRestrictions)Convert.ToInt32(rdRestrictions.SelectedValue);
  cc.Site.SetRecordRestrictions(restrictions);
  cc.Site.SetManualRecordDeclarationInAllLocations(Convert.ToBoolean(rdAvailability.SelectedValue));
  EcmRecordDeclarationBy declareBy = (EcmRecordDeclarationBy)Convert.ToInt32(rdDeclarationBy.SelectedValue);
  cc.Site.SetRecordDeclarationBy(declareBy);
  EcmRecordDeclarationBy unDeclareBy = (EcmRecordDeclarationBy)Convert.ToInt32(rdUndeclarationBy.SelectedValue);
  cc.Site.SetRecordUnDeclarationBy(unDeclareBy);
}

在前面的代码中，调用 RecordsManagementExtensions.cs 中的 SetRecordRestrictions 方法。下一个示例使用 SetRecordRestrictions 方法，展示了如何对记录设置限制。

public static void SetRecordRestrictions(this Site site, EcmSiteRecordRestrictions restrictions)
{
  string restrictionsProperty = "";

  if (restrictions.Has(EcmSiteRecordRestrictions.None))
  {
    restrictionsProperty = EcmSiteRecordRestrictions.None.ToString();
  }
  else if (restrictions.Has(EcmSiteRecordRestrictions.BlockEdit))
  {
    // BlockEdit is always used in conjunction with BlockDelete.
    restrictionsProperty = EcmSiteRecordRestrictions.BlockDelete.ToString() + ", " + EcmSiteRecordRestrictions.BlockEdit.ToString();
  }
  else if (restrictions.Has(EcmSiteRecordRestrictions.BlockDelete))
  {
    restrictionsProperty = EcmSiteRecordRestrictions.BlockDelete.ToString();
  }

  // Set property bag entry.
  site.RootWeb.SetPropertyBagValue(ECM_SITE_RECORD_RESTRICTIONS, restrictionsProperty);
}

方案 2

方案 2 展示了如何与列表的就地记录管理设置进行交互。外接程序在安装后会创建一个名为“IPRTest”的文档库。如果使用此外接程序更改并保存就地记录管理设置，所做的更改就会应用于 IPRTest。

注意

若要对列表使用就地记录管理设置，必须对网站集激活就地记录管理功能。

当用户选择“保存更改”按钮时，Default.aspx.cs 中的以下代码运行。

protected void btnSaveListScopedIPRSettings_Click(object sender, EventArgs e)
{
  List ipr = cc.Web.GetListByTitle(IPR_LIBRARY);
  EcmListManualRecordDeclaration listManual = (EcmListManualRecordDeclaration)Convert.ToInt32(rdListAvailability.SelectedValue);
  ipr.SetListManualRecordDeclaration(listManual);
  ipr.SetListAutoRecordDeclaration(chbAutoDeclare.Checked);

  // Refresh the settings as AutoDeclare changes the manual settings.
  if (ipr.IsListRecordSettingDefined())
  {
    rdListAvailability.SelectedValue = Convert.ToString((int)ipr.GetListManualRecordDeclaration());
    chbAutoDeclare.Checked = ipr.GetListAutoRecordDeclaration();
    rdListAvailability.Enabled = !chbAutoDeclare.Checked;
  }
}

代码将调用 OfficeDevPnP.Core 的 RecordsManagementExtensions.cs 文件中的下列两个方法：

SetListManualRecordDeclaration - 定义此列表的手动记录声明设置。
SetListAutoRecordDeclaration - 将添加到此列表的项自动声明为记录。如果对此列表设置自动声明记录，将不再对列表应用手动记录声明设置。列表中添加有事件接收器，用于在事件发生时启动特定的记录管理操作。

public static void SetListManualRecordDeclaration(this List list, EcmListManualRecordDeclaration settings)
{
  if (settings == EcmListManualRecordDeclaration.UseSiteCollectionDefaults)
  {
    // If you set list record declaration back to the default values, you also need to
    // turn off auto record declaration. Other property bag values are left as is; when
    // settings are changed again these properties are also again usable.
    if (list.PropertyBagContainsKey(ECM_AUTO_DECLARE_RECORDS))
    {
      list.SetListAutoRecordDeclaration(false);
    }
    // Set the property that dictates custom list record settings to false.
    list.SetPropertyBagValue(ECM_IPR_LIST_USE_LIST_SPECIFIC, false.ToString());
  }
  else if (settings == EcmListManualRecordDeclaration.AlwaysAllowManualDeclaration)
  {
    list.SetPropertyBagValue(ECM_ALLOW_MANUAL_DECLARATION, true.ToString());
    // Set the property that dictates custom list record settings to true.
    list.SetPropertyBagValue(ECM_IPR_LIST_USE_LIST_SPECIFIC, true.ToString());
  }
  else if (settings == EcmListManualRecordDeclaration.NeverAllowManualDeclaration)
  {
    list.SetPropertyBagValue(ECM_ALLOW_MANUAL_DECLARATION, false.ToString());
    // Set the property that dictates custom list record settings to true.
    list.SetPropertyBagValue(ECM_IPR_LIST_USE_LIST_SPECIFIC, true.ToString());
  }
  else
  {
    throw new ArgumentOutOfRangeException("settings");
  }
}

public static void SetListAutoRecordDeclaration(this List list, bool autoDeclareRecords)
{
  // Determine the SharePoint version based on the loaded CSOM library.
  Assembly asm = Assembly.GetAssembly(typeof(Microsoft.SharePoint.Client.Site));
  int sharePointVersion = asm.GetName().Version.Major;

  if (autoDeclareRecords)
  {
    // Set the property that dictates custom list record settings to true.
    list.SetPropertyBagValue(ECM_IPR_LIST_USE_LIST_SPECIFIC, true.ToString());
    // Prevent manual declaration.
    list.SetPropertyBagValue(ECM_ALLOW_MANUAL_DECLARATION, false.ToString());

    // Hook up the needed event handlers.
    list.Context.Load(list.EventReceivers);
    list.Context.ExecuteQuery();

    List<EventReceiverDefinition> currentEventReceivers = new List<EventReceiverDefinition>(list.EventReceivers.Count);
    currentEventReceivers.AddRange(list.EventReceivers);

    // Track changes to see if a list.Update is needed.
    bool eventReceiverAdded = false;

    // ItemUpdating receiver.
    EventReceiverDefinitionCreationInformation newEventReceiver = CreateECMRecordEventReceiverDefinition(EventReceiverType.ItemUpdating, 1000, sharePointVersion);
    if (!ContainsECMRecordEventReceiver(newEventReceiver, currentEventReceivers))
    {
      list.EventReceivers.Add(newEventReceiver);
      eventReceiverAdded = true;
    }
    // ItemDeleting receiver.
    newEventReceiver = CreateECMRecordEventReceiverDefinition(EventReceiverType.ItemDeleting, 1000, sharePointVersion);
    if (!ContainsECMRecordEventReceiver(newEventReceiver, currentEventReceivers))
    {
      list.EventReceivers.Add(newEventReceiver);
      eventReceiverAdded = true;
    }
    // ItemFileMoving receiver.
    newEventReceiver = CreateECMRecordEventReceiverDefinition(EventReceiverType.ItemFileMoving, 1000, sharePointVersion);
    if (!ContainsECMRecordEventReceiver(newEventReceiver, currentEventReceivers))
    {
      list.EventReceivers.Add(newEventReceiver);
      eventReceiverAdded = true;
    }
    // ItemAdded receiver.
    newEventReceiver = CreateECMRecordEventReceiverDefinition(EventReceiverType.ItemAdded, 1005, sharePointVersion);
    if (!ContainsECMRecordEventReceiver(newEventReceiver, currentEventReceivers))
    {
      list.EventReceivers.Add(newEventReceiver);
      eventReceiverAdded = true;
    }
    // ItemUpdated receiver.
    newEventReceiver = CreateECMRecordEventReceiverDefinition(EventReceiverType.ItemUpdated, 1007, sharePointVersion);
    if (!ContainsECMRecordEventReceiver(newEventReceiver, currentEventReceivers))
    {
      list.EventReceivers.Add(newEventReceiver);
      eventReceiverAdded = true;
    }
    // ItemCheckedIn receiver.
    newEventReceiver = CreateECMRecordEventReceiverDefinition(EventReceiverType.ItemCheckedIn, 1006, sharePointVersion);
    if (!ContainsECMRecordEventReceiver(newEventReceiver, currentEventReceivers))
    {
      list.EventReceivers.Add(newEventReceiver);
      eventReceiverAdded = true;
    }

    if (eventReceiverAdded)
    {
      list.Update();
      list.Context.ExecuteQuery();
    }

    // Set the property that dictates the autodeclaration.
    list.SetPropertyBagValue(ECM_AUTO_DECLARE_RECORDS, autoDeclareRecords.ToString());
  }
  else
  {
    // Set the property that dictates the autodeclaration.
    list.SetPropertyBagValue(ECM_AUTO_DECLARE_RECORDS, autoDeclareRecords.ToString());
    //Note: Existing list event handlers will just stay as they are, no need to remove them.
  }
}

另请参阅

适用于 SharePoint 的企业内容管理解决方案

通过