Добавление собственной кнопки в надстройку с размещением у поставщика

Статья
04/08/2023

Это третья часть серии статей, посвященной основам разработки надстроек SharePoint, размещаемых у поставщика. Для начала вам следует ознакомиться со статьей Надстройки SharePoint и предыдущими статьями этой серии, представленными в разделе Знакомство с созданием надстроек SharePoint, размещаемых у поставщика.

Примечание.

Если вы изучали предыдущие статьи этой серии о размещаемых у поставщика надстройках, то у вас уже есть решение Visual Studio, которое можно использовать для работы с данной статьей. Кроме того, вы можете скачать репозиторий SharePoint_Provider-hosted_Add-Ins_Tutorials и открыть файл BeforeRibbonButton.sln.

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

Создание специального списка на хост-сайте

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

На домашней странице магазина Fabrikam Hong Kong выберите пункты Содержимое сайта>Добавить надстройку>Настраиваемый список.
В диалоговом окне Настраиваемый список — добавление укажите имя Local Employees (Местные сотрудники) и нажмите кнопку Создать.
На странице Содержимое сайта откройте список Local Employees (Местные сотрудники).
Откройте вкладку Список на ленте, а затем нажмите кнопку Параметры списка.
В разделе Столбцы на странице Параметры списка выберите столбец Название.
Откроется форма Изменение столбца. Замените значение Название в поле Имя столбца на Имя, а затем нажмите кнопку ОК.
На странице Параметры выберите команду Создать столбец.
В форме Создание столбца выполните указанные ниже действия.
1. В поле Имя столбца введите Added to Corporate DB (Добавлено в корпоративную базу данных).
2. В качестве типа укажите Да/Нет (флажок).
3. В поле Значение по умолчанию укажите значение Нет.
4. Нажмите кнопку ОК. Снова откроется страница Параметры.
Выберите Содержимое сайта, чтобы открыть страницу Содержимое сайта. На ней отобразится плитка для нового списка. Откройте ее.
Щелкните Создайте элемент и в форме создания элемента введите имя, но не устанавливайте флажок Added to Corporate DB (Добавлено в корпоративную базу данных). Нажмите кнопку Сохранить. Список должен выглядеть примерно следующим образом:

Рис. 1. Список локальных сотрудников с одним элементом

Добавление специальной кнопки

В этом разделе показано, как добавить в надстройку часть кода, которая будет развертывать кнопку на ленте списка. Когда пользователь выделяет сотрудника в списке и нажимает кнопку, имя сотрудника добавляется в корпоративную базу данных, а в поле Added to Corporate DB (Добавлено в корпоративную базу данных) для этого сотрудника значение Нет заменяется на Да.

Если открыт редактор Visual Studio, вам необходимо будет закрыть его и повторно открыть решение Chain Store, чтобы Visual Studio обнаружил новый список. (Запустите Visual Studio от имени администратора.)
Примечание.

Когда решение открывается повторно, для параметров раздела "Запускаемые проекты" в Visual Studio обычно возвращаются значения по умолчанию. После повторного открытия примера решения, который рассматривается в этой серии статей, всегда выполняйте указанные ниже действия.
1. В верхней части обозревателя решений щелкните узел решения правой кнопкой мыши и выберите пункт Назначить запускаемые проекты.
2. Убедитесь, что в столбце Действие для всех трех проектов указано значение Запуск.
В обозревателе решений щелкните правой кнопкой мыши проект ChainStore и выберите пункты Добавить>Создать элемент.
В диалоговом окне Добавить новый элемент выберите Настраиваемое действие ленты, укажите имя AddEmployeeToCorpDB, а затем нажмите кнопку Добавить.

В открывшемся диалоговом окне будут три вопроса. Дайте на них указанные ниже ответы.

Вопрос	Ответ
Где требуется предоставить настраиваемое действие?	Хост-сайт
К какой области относится настраиваемое действие?	Экземпляр списка
Каким конкретным элементом ограничена область настраиваемого действия?	Local Employees

Нажмите кнопку Далее. Появятся еще три вопроса.

Вопрос	Ответ
Где расположен этот элемент управления?	Ribbon.ListItem.Actions
Какой текст должен отображаться на подписи этой кнопки?	Add To Corporate DB
Куда ведет элемент управления "Кнопка"?	ChainStoreWeb\Pages\EmployeeAdder.aspx (это страница, код программной части которой будет добавлять сотрудника в базу данных)

Нажмите кнопку Готово.

Файл elements.xml, который определяет дополнительное действие, будет добавлен в проект и открыт. Вы можете обращаться с этим файлом как с "черным ящиком". Вам не потребуется вносить в него изменения до знакомства со следующими статьями этой серии. А сейчас обратите внимание на указанные ниже моменты.
- Атрибут Location элемента CommandUIDefinition имеет значение Ribbon.ListItem.Actions.Controls_children. Его вторая часть (ListItem) идентифицирует вкладку на ленте, на которую будет помещена кнопка (но это может и не быть точным отображаемым именем вкладки). Третья часть (Actions) — это имя раздела ленты, в который будет помещена кнопка.
- Атрибут CommandAction элемента CommandUIHandler начинается с заполнителя ~remoteAppUrl. При развертывании кнопки он будет заменен URL-адресом удаленного веб-приложения.
- В значение CommandAction с использованием значений заполнителей в фигурных скобках "{ }" добавлены несколько параметров запроса. Эти заполнители разрешаются в среде выполнения. Обратите внимание, что один из них — идентификатор элемента списка, выбранного пользователем перед нажатием специальной кнопки на ленте.
В проекте ChainStoreWeb откройте файл Pages/EmployeeAdder.aspx. Обратите внимание, что в нем нет пользовательского интерфейса. Предполагается, что надстройка будет использовать эту страницу в качестве веб-службы. Это возможно, так как класс ASP.NET System.Web.UI.Page реализует System.Web.IHttpHandler и событие Page_Load запускается автоматически при запросе страницы.
Откройте файл с кодом программной части Pages/EmployeeAdder.aspx.cs. В нем уже есть метод, который добавляет сотрудника в удаленную базу данных AddLocalEmployeeToCorpDB. Он использует объект SharePointContext для получения URL-адреса хост-сайта, который надстройка использует в качестве своего дискриминатора клиента. Первое, что должен сделать метод Page_Load, — инициализировать этот объект. Объект создается и помещается в кэш в сеансе, когда загружается начальная страница надстройки, поэтому добавьте указанный ниже код в метод Page_Load. (Объект SharePointContext определен в файле SharePointContext.cs, который пакет "Инструменты разработчика Office для Visual Studio" создает при создании решения надстройки.)
```
spContext = Session["SPContext"] as SharePointContext;
```
Метод AddLocalEmployeeToCorpDB использует имя сотрудника в качестве параметра, поэтому добавьте указанную ниже строку в метод Page_Load. Вы создадите метод GetLocalEmployeeName на одном из следующих этапов.
```
// Read from SharePoint 
string employeeName = GetLocalEmployeeName();
```
После этой строки добавьте вызов метода AddLocalEmployeeToCorpDB.
```
// Write to remote database 
AddLocalEmployeeToCorpDB(employeeName);
```
Добавьте в файл оператор using для пространства имен Microsoft.SharePoint.Client. (При создании проекта ChainStoreWebИнструменты разработчика Office для Visual Studio включил в него сборку Microsoft.SharePoint.Client.)
Теперь добавьте указанный ниже метод в класс EmployeeAdder. Клиентская объектная модель (CSOM) .NET для SharePoint подробно задокументирована на MSDN. Рекомендуем изучить ее по завершении работы с этой серией статей. Обратите внимание на то, что класс ListItem представляет элемент в списке SharePoint и что на значение поля в элементе можно сослаться с помощью синтаксиса "индексатора". Кроме того, учтите, что код ссылается на поле, используя имя Название, даже если вы заменили его на Имя. Это происходит из-за того, что в коде необходимо ссылаться на поля, используя их внутренние, а не отображаемые имена. Внутреннее имя поля указывается при создании поля и его не удастся изменить. Вы выполните TODO1 на одном из следующих этапов.
```
private string GetLocalEmployeeName()
{
  ListItem localEmployee;

  // TODO1: Initialize the localEmployee object by getting  
  // the item from SharePoint.

  return localEmployee["Title"].ToString();
}
```
Чтобы наш код смог получить элемент списка из SharePoint, ему потребуется идентификатор этого элемента. Добавьте указанное ниже объявление в класс EmployeeAdder сразу же после объявления для объекта spContext.
```
private int listItemID;
```
Теперь добавьте указанный ниже метод в класс EmployeeAdder, чтобы получить идентификатор элемента списка из параметра запроса.
```
private int GetListItemIDFromQueryParameter()
{
  int result;
  Int32.TryParse(Request.QueryString["SPListItemId"], out result);
  return result;
}
```
Чтобы инициализировать переменную listItemID, добавьте указанную ниже строку в метод Page_Load сразу же за строкой, в которой выполняется инициализация переменной spContext.
```
listItemID = GetListItemIDFromQueryParameter();
```

В GetLocalEmployeeName замените TODO1 указанным ниже кодом. На данный момент относитесь к этому коду как к "черному ящику", потому что сейчас нас интересует то, как заставить работать специальную кнопку. Мы более подробно рассмотрим этот код в следующей статье серии, которая будет целиком посвящена клиентской объектной модели SharePoint.

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

Теперь весь метод должен выглядеть, как указано ниже.

private string GetLocalEmployeeName()
{
  ListItem localEmployee;

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

Страница EmployeeAdder не должна отрисовываться, поэтому добавьте указанный ниже код в метод Page_Load в качестве последней строки. Она будет перенаправлять браузер обратно на страницу представления списка для списка Local Employees (Местные сотрудники).

// Go back to the Local Employees page
Response.Redirect(spContext.SPHostUrl.ToString() + "Lists/Local%20Employees/AllItems.aspx", true);

Теперь весь метод Page_Load должен выглядеть, как указано ниже.

protected void Page_Load(object sender, EventArgs e)
{
  spContext = Session["SPContext"] as SharePointContext;
  listItemID = GetListItemIDFromQueryParameter();

  // Read from SharePoint
  string employeeName = GetLocalEmployeeName();

  // Write to remote database
  AddLocalEmployeeToCorpDB(employeeName);

  // Go back to the preceding page
  Response.Redirect(spContext.SPHostUrl.ToString() + "Lists/Local%20Employees/AllItems.aspx", true);
}

Запрашивание разрешения на чтение списка на хост-сайте

Как вы уже видели, при установке надстройки SharePoint предлагает предоставить ей разрешения на доступ к хост-сайту. Каждый раз, когда вы нажимали клавишу F5, выполнялась переустановка надстройки. До настоящего момента у надстройки были только минимально необходимые разрешения, но методу GetLocalEmployeeName необходимо разрешение на чтение списков хост-сайта. Надстройка использует свой манифест, чтобы сообщить SharePoint, какие разрешения ей необходимы. Выполните указанные ниже действия.

В обозревателе решений откройте файл AppManifest.xml в проекте ChainStore (файл называется AppManifest и в нем использовано слово App, потому что ранее надстройки назывались приложениями). Откроется конструктор манифестов.
Откройте вкладку Разрешения и щелкните пустую ячейку в столбце Область. Затем в раскрывающемся списке выберите Список.
Щелкнув пустую ячейку в столбце Разрешение, в раскрывающемся списке выберите Read.
Оставьте столбец Свойства пустым и сохраните файл. Вкладка Разрешения должна иметь примерно следующий вид:

Рис. 2. Вкладка "Разрешения"

Запуск надстройки и тестирование кнопки

Нажмите клавишу F5, чтобы развернуть и запустить надстройку. Редактор Visual Studio размещает удаленное веб-приложение в IIS Express, а базу данных SQL — в SQL Express. Кроме того, он выполняет временную установку надстройки на вашем тестовом сайте SharePoint и сразу же запускает ее. Прежде чем откроется начальная страница надстройки, вам будет предложено предоставить надстройке необходимые разрешения. В этот раз будет отображен раскрывающийся список, в котором вы можете выбрать список, данные из которого необходимо считывать приложению, как показано на снимке экрана ниже.

Рис. 3. Запрос разрешений надстройки SharePoint
В списке выберите пункт Local Employees (Местные сотрудники), а затем нажмите кнопку Сделать доверенным.
Когда откроется начальная страница надстройки, выберите Вернуться на сайт на размещенном в верхней части элементе управления хрома.
На домашней странице веб-сайта выберите Содержимое сайта>Local Employees (Местные сотрудники). Откроется страница представления списка.
Добавьте несколько сотрудников в список. Не устанавливайте флажок Added to Corporate DB (Добавлено в корпоративную базу данных).
На ленте откройте вкладку Элементы. В разделе Действия вкладки есть специальная кнопка Add to Corporate DB (Добавить в корпоративную базу данных).
Выберите элемент в списке. Страница и лента должны иметь примерно следующий вид:

Рис. 4. Список местных сотрудников
Выбрав элемент в списке, нажмите кнопку Add To Corporate DB (Добавить в корпоративную базу данных).
Вам покажется, что страница перезагружается, так как метод Page_Load страницы EmployeeAdder выполняет перенаправление на нее.
Дважды нажмите кнопку "Назад" в браузере, чтобы вернуться на начальную страницу надстройки.
Нажмите кнопку Show Employees (Показать сотрудников), после чего список сотрудников будет заполнен добавленными вами сотрудниками. Он должен выглядеть примерно следующим образом:

Рис. 5. Список сотрудников организации на начальной странице надстройки
Чтобы завершить сеанс отладки, закройте окно браузера или остановите отладку в Visual Studio. При каждом нажатии клавиши F5 Visual Studio будет отзывать предыдущую версию надстройки и устанавливать ее последнюю версию.
Вы будете работать с этой надстройкой и решением Visual Studio при изучении других статей, поэтому при перерывах в работе рекомендуем отзывать надстройку. В обозревателе решений щелкните проект правой кнопкой мыши и выберите пункт Отозвать.

Дальнейшие действия

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

Поделиться через