Einschlie?en benutzerdefinierter Schaltfl?chen in anbietergehosteten Add-Ins

Artikel
04/08/2023

Dies ist der dritte einer Reihe von Artikeln ?ber die Grundlagen der Entwicklung von vom Anbieter gehosteten SharePoint-Add-Ins. Machen Sie sich zun?chst mit SharePoint-Add-Ins und den vorherigen Artikeln dieser Reihe vertraut, die Sie unter Erste Schritte beim Erstellen von von einem Anbieter gehosteten SharePoint-Add-Ins finden.

Hinweis

Wenn Sie unsere Artikelreihe zum Thema anbietergehostete Add-Ins durchgearbeitet haben, haben Sie bereits eine Visual Studio-Lösung, die Sie für diesen Artikel verwenden können. Sie k?nnen auch das Repository unter SharePoint_Provider-hosted_Add-Ins_Tutorials herunterladen und die Datei ?BeforeAdd-inPart.sln? ?ffnen.

Ein SharePoint-Add-In kann benutzerdefinierte Aktionen umfasst; dies ist die SharePoint-Bezeichnung f?r benutzerdefinierte Men?elemente oder Men?bandschaltfl?chen. In diesem Artikel erfahren Sie, wie eine benutzerdefinierte Schaltfl?che erstellt wird, die eine SharePoint-Liste mit einer Remotedatenbank synchronisiert.

Erstellen einer benutzerdefinierten Liste auf der Hostwebsite

Die benutzerdefinierte Schaltfläche wird sich auf dem Menüband einer bestimmte Liste befinden, in der die Mitarbeiter eines lokalen Geschäfts aufgezeichnet werden. In einem späteren Artikel dieser Reihe erfahren Sie, wie Sie eine benutzerdefinierte Liste programmgesteuert zu einer Hostwebsite hinzufügen, aber für den Moment werden Sie diese manuell hinzufügen.

Navigieren Sie auf der Startseite des Fabrikam-Stores in Hongkong zu Websiteinhalte>Add-In hinzuf?gen> Benutzerdefinierte Liste.
Geben Sie im Dialogfeld Benutzerdefinierte ListeLokale Mitarbeiter als Name an, und klicken Sie auf Erstellen.
?ffnen Sie auf der Seite Websiteinhalte die Liste Lokale Mitarbeiter.
Klicken Sie auf dem Men?band auf der Registerkarte Liste auf Listeneinstellungen.
Klicken Sie im Abschnitt Spalten der Seite Listeneinstellungen auf die Spalte Titel.
?ndern Sie im Formular Spalte bearbeiten den Spaltenname von Title in Name, und klicken Sie dann auf OK.
Klicken Sie auf der Seite Einstellungen auf Spalte erstellen.
Gehen Sie im Formular Spalte erstellen folgenderma?en vor:
1. Geben Sie Zur Unternehmensdatenbank hinzugef?gt als Spaltenname ein.
2. Legen Sie den Typ auf Ja/Nein (Kontrollk?stchen) fest.
3. Legen Sie den Standardwert auf Nein fest.
4. Klicken Sie auf OK. Sie gelangen zur?ck zur Seite Einstellungen.
W?hlen Sie Websiteinhalte aus, um die Seite Websiteinhalte zu ?ffnen. Dort befindet sich die Kachel f?r die neute Liste. ?ffnen Sie sie.
Klicken Sie auf Neues Element, und geben Sie auf dem Formular zu Erstellen eines Elements einen Namen ein, w?hlen Sie jedoch nicht die Option Zur Unternehmensdatenbank hinzugef?gt aus. Klicken Sie auf Speichern. Die Liste sollte ?hnlich wie im folgenden Beispiel aussehen:

Abbildung 1: Liste "Lokale Mitarbeiter" mit einem einzelnen Element

Hinzuf?gen der benutzerdefinierten Schaltfl?che

In diesem Abschnitt schlie?en Sie das Markup in das Add-In ein, das eine Schaltfl?che f?r das Men?band der Liste bereitstellt. Wenn ein Benutzer einen Mitarbeiter in der Liste markiert und die Schaltfl?che ausw?hlt, wird der Name des Mitarbeiters zur Unternehmensdatenbank hinzugef?gt, und das Feld Zur Unternehmensdatenbank hinzugef?gt ?ndert sich von Nein zu Ja.

Wenn Visual Studio ge?ffnet ist, m?ssen Sie es schlie?en und die Projektmappe ?ChainStore? erneut ?ffen, damit Visual Studio Ihre neue Liste erkennen kann. (F?hren Sie Visual Studio als Administrator aus.)
Hinweis

Die Einstellungen für Startprojekte in Visual Studio werden in der Regel nach jedem erneuten Öffnen der Lösung wieder auf die Standardwerte zurückgesetzt. Wann immer Sie beim Durcharbeiten dieser Artikelreihe die Beispiellösung erneut öffnen, müssen Sie umgehend die folgenden Schritte durchführen:
1. Klicken Sie oben im Projektmappen-Explorer mit der rechten Maustaste auf den Lösungsknoten, und wählen Sie die Option Startprojekte festlegen aus.
2. Stellen Sie sicher, dass alle drei Projekte in der Spalte Aktion auf Start festgelegt sind.
Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das ChainStore-Projekt, und w?hlen Sie Hinzuf?gen>Neues Element aus.
W?hlen Sie im Dialogfeld Neues Element hinzuf?gen die Option Benutzerdefinierte Men?bandaktion aus, nennen Sie sie AddEmployeeToCorpDB, und klicken Sie dann auf Hinzuf?gen.

Im daraufhin geöffneten Dialogfeld werden drei Fragen gestellt. Geben Sie die folgenden Antworten:

Frage	Geben Sie die folgende Antwort:
Wo soll die benutzerdefinierte Aktion zur Verfügung gestellt werden?	Hostweb
Zu welchem Bereich ist die benutzerdefinierte Aktion zugeordnet?	Listeninstanz
Welchem bestimmten Element ist die benutzerdefinierte Aktion zugeordnet?	Lokale Mitarbeiter

Klicken Sie auf Weiter, und Sie erhalten drei weitere Fragen:

Frage	Geben Sie die folgende Antwort:
Wo befindet sich das Steuerelement?	Ribbon.ListItem.Actions
Was ist der Beschriftungstext für das Steuerelement?	Zu Unternehmens-DB hinzufügen
Wohin navigiert das Schaltfl?chen-Steuerelement?	ChainStoreWeb\Pages\EmployeeAdder.aspx (Dies ist eine Seite, deren zugrunde liegender Code den Mitarbeiter zur Datenbank hinzuf?gt.)

Klicken Sie auf Fertig stellen.

Eine elements.xml-Datei, die die benutzerdefinierte Aktion definiert, wird dem Projekt hinzugefügt und geöffnet. In den meisten F?llen k?nnen Sie diese Datei als Blackbox betrachten; Sie werden erst in einem sp?teren Artikel in dieser Reihe ?nderungen daran vornehmen. Jetzt beachten Sie nur Folgendes:
- Das Attribut Location des Elements CommandUIDefinition hat den Wert Ribbon.ListItem.Actions.Controls_children. Der zweite Teil davon, ListItem, identifiziert die Registerkarte auf dem Men?band, auf der die Schaltfl?che platziert wird (dies ist aber m?glicherweise nicht genau der Anzeigename der Registerkarte). Der dritte Teil, Actions, ist der Name des Abschnitts des Men?bands, in dem die Schaltfl?che platziert wird.
- Das Attribut CommandAction des Elements CommandUIHandler beginnt mit dem Platzhalter ~remoteAppUrl. Dieser wird bei der Bereitstellung der Schaltfläche ersetzt durch die URL der Remotewebanwendung.
- Dem Wert CommandAction wurden einige Abfrageparameter mit Platzhalterwerte in Klammern ?{ }? hinzugef?gt. Diese Platzhalter werden zur Laufzeit aufgel?st. Beachten Sie, dass einer der Platzhalter die ID des Listenelements ist, das vom Benutzer ausgew?hlt wurde, bevor die benutzerdefinierte Schaltfl?che auf dem Men?band ausgew?hlt wurde.
?ffnen Sie im Projekt ChainStoreWeb die Datei Pages/EmployeeAdder.aspx. Beachten Sie, dass keine Benutzeroberfläche vorhanden ist. Das Add-In wird diese Seite als eine Art Webdienst verwenden. Dies ist möglich, da die ASP.NET System.Web.UI.Page Klasse System.Web.IHttpHandler implementiert und das Page_Load-Ereignis automatisch ausgeführt wird, wenn die Seite angefordert wird.
?ffnen Sie die Code-Behind-Datei Pages/EmployeeAdder.aspx.cs. Die Methode, die den Mitarbieter zu der Remotedatenbank hinzuf?gt (AddLocalEmployeeToCorpDB) ist bereits vorhanden. Sie verwendet das SharePointContext-Objekt, um die URL des Hostwebs abzurufen, die das Add-In als Mandantendiskriminator verwendet. Das erste, was die Page_Load-Methode tun muss, ist die Initialisierung des Objekts. Das Objekt wird erstellt und in der Sitzung zwischengespeichert, wenn die Startseite des Add-Ins geladen wird, f?gen Sie den folgenden Code daher zur Page_Load-Methode hinzu. (Das SharePointContext-Objekt wird in der Datei ?SharePointContext.cs? definiert, die von den Office-Entwicklertools f?r Visual Studio generiert wird, wenn die Add-In-L?sung erstellt wird.
```
spContext = Session["SPContext"] as SharePointContext;
```
Da die AddLocalEmployeeToCorpDB-Methode den Namen des Mitarbeiters als Parameter akzeptiert, f?gen Sie die folgende Zeile zur Page_Load-Methode hinzu. Sie erstellen die GetLocalEmployeeName-Methode in einem sp?teren Schritt.
```
// Read from SharePoint 
string employeeName = GetLocalEmployeeName();
```
F?gen Sie unterhalb dieser Zeile den Aufruf der AddLocalEmployeeToCorpDB-Methode hinzu.
```
// Write to remote database 
AddLocalEmployeeToCorpDB(employeeName);
```
Fügen Sie eine using-Anweisung zur Datei für den Namespace Microsoft.SharePoint.Client hinzu. (Die Office-Entwicklertools für Visual Studio enthielten die Microsoft.SharePoint.Client-Assembly im ChainStoreWeb-Projekt, als dieses erstellt wurde.)
F?gen Sie der EmployeeAdder-Klasse jetzt die folgende Methode hinzu. Das clientseitige SharePoint .NET-Objektmodell (CSOM) wird an einer anderen Stelle in MSDN ausf?hrlich beschrieben, und es wird empfohlen, dass Sie sich dieses genauer ansehen, wenn Sie mit dieser Artikelreihe fertig sind. Beachten Sie, dass in diesem Artikel die ListItem-Klasse ein Element in einer SharePoint-Liste darstellt und dass auf einen Wert eines Felds in dem Element mit der ?indexer?-Syntax verwiesen werden kann. Beachten Sie au?erdem, dass der Code das Feld als Titel bezeichnet, obwohl Sie den Feldnamen in Name ge?ndert haben. Dies liegt daran, dass Felder im Code immer mit ihrem internen Namen und nicht mit ihrem Anzeigenamen bezeichnet werden. Der interne Name eines Felds wird festgelegt, wenn das Feld erstellt wird, und kann nicht geändert werden. Sie schließen TODO1 in einem späteren Schritt ab.
```
private string GetLocalEmployeeName()
{
  ListItem localEmployee;

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

  return localEmployee["Title"].ToString();
}
```
Unser Code ben?tigt die ID des Listenelements, bevor dieser aus SharePoint abgerufen werden kann. F?gen Sie die folgende Deklaration der EmployeeAdder-Klasse direkt unter der Deklaration f?r das spContext-Objekt hinzu.
```
private int listItemID;
```

F?gen Sie jetzt die folgende Methode der EmployeeAdder-Klasse hinzu, um die ID dieses Listenelements aus dem Abfrageparameter abzurufen.

private int GetListItemIDFromQueryParameter()
{
  int result;
  Int32.TryParse(Request.QueryString["SPListItemId"], out result);
  return result;
}

Um die listItemID-Variable zu initialisieren, f?gen Sie der Page_Load-Methode die folgende Zeile unter der Zeile hinzu, die die spContext-Variable initialisiert.
```
listItemID = GetListItemIDFromQueryParameter();
```

Ersetzen Sie in GetLocalEmployeeName die Zeile TODO1 durch den folgenden Code. Behandeln Sie diesen Code vorerst wie eine Blackbox, solange wir uns auf das darauf konzentrieren, die benutzerdefinierte Schaltfl?che zum Laufen zu bringen. Im n?chsten Artikel in dieser Reihe, in der es um das clientseitige SharePoint-Objektmodell geht, erfahren Sie mehr ?ber diesen Code.

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

Die gesamte Methode sollte jetzt wie folgt aussehen.

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

Die Seite ?EmployeeAdder? sollte tats?chlich nicht gerendert werden, f?gen Sie Folgendes als letzte Zeile in der Page_Load-Methode hinzu. Dadurch wird der Browser zur?ck zur Listenansichtsseite f?r die Local Employees-Liste geleitet.

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

Die gesamte Page_Load-Methode sollte jetzt wie folgt aussehen.

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);
}

Anfordern der Berechtigung zum Lesen der Hostwebliste

Wie Sie bereits gesehen haben, werden Sie in SharePoint aufgefordert, die Add-In-Berechtigungen zum Hostweb hinzuzuf?gen, wenn es installiert wird. Jedes Mal, wenn Sie F5 dr?cken, haben Sie das Add-In erneut installiert. Bisher ben?tigte das Add-In nur minimale Berechtigungen, die GetLocalEmployeeName-Methode ben?tigt jedoch die Berechtigung zum Lesen der Listen der Hostwebsite. Das Add-In verwendet sein Add-In-Manifest, um SharePoint mitzuteilen, welche Berechtigungen es ben?tigt. F?hren Sie die folgenden Schritte aus.

?ffnen Sie im Projektmappen-Explorer die Datei AppManifest.xml im ChainStore-Projekt. (Die Datei hei?t AppManifest, da Add-Ins fr?her als ?Apps" bezeichnet wurden.) Der Manifest-Designer wird ge?ffnet.
?ffnen Sie die Registerkarte Berechtigungen, w?hlen Sie die leere Zelle unter der Spalte Bereich aus, und w?hlen Sie dann Liste aus der Dropdownliste aus.
W?hlen Sie im Feld Berechtigung die Option Lesen aus der Dropdownliste aus.
Lassen Sie das Feld Eigenschaften leer, und speichern Sie die Datei. Die Registerkarte Berechtigungen sollte etwa wie folgt aussehen.

Abbildung 2: Registerkarte "Berechtigungen"

Ausführen des Add-Ins und Testen der Schaltfläche

Dr?cken Sie die Taste F5, um Ihr Add-In bereitzustellen und auszuf?hren. Visual Studio hostet die Remotewebanwendung in IIS Express und die SQL-Datenbank in SQL Express. Außerdem wird eine temporäre Installation des Add-Ins auf Ihrer SharePoint-Testwebsite durchgeführt, und das Add-In wird sofort ausgeführt. Sie werden aufgefordert, Berechtigungen f?r das Add-In zu erteilen, bevor die Startseite ge?ffnet wird. Dieses Mal weist die Aufforderung ein Dropdownmen? auf, in dem Sie die Liste ausw?hlen, die die App zum Lesen ben?tigt, wie im folgenden Screenshot dargestellt.

Abbildung 3: SharePoint-Add-In-Berechtigungsaufforderung
W?hlen Sie Lokale Mitarbeiter aus der Liste aus, und klicken Sie dann auf Vertrauen.
Wenn die Add-In-Startseite ge?ffnet wird, klicken Sie auf Zur?ck zur Website im Chromesteuerelement im oberen Bereich.
Gehen Sie auf der Startseite der Website zu Websiteinhalte>Lokale Mitarbeiter. Die Seite mit der Listenansicht wird geöffnet.
F?gen Sie der Liste ein paar Mitarbeiter hinzu. Aktivieren Sie das Kontrollk?stchen Zur Unternehmensdatenbank hinzugef?gt nicht.
?ffnen Sie auf dem Men?band die Registerkarte Elemente. Im Abschnitt Aktionen der Registerkarte wird die benutzerdefinierte Schaltfl?che Zur Unternehmensdatenbank hinzuf?gen angezeigt.
W?hlen Sie ein Element in der Liste aus. Die Seite und das Men?band sollten in etwa wie folgt aussehen:

Abbildung 4: Liste "Lokale Mitarbeiter"
Klicken Sie nach dem Ausw?hlen eines Elements in der Liste auf Zur Unternehmensdatenbank hinzuf?gen.
Die Seite scheint neu geladen zu werden, da die Page_Load-Methode der Seite ?EmployeeAdder? eine direkte Umleitung aufweist.
Klicken Sie im Browser zweimal auf die Schaltfl?che ?Zur?ck?, um zur?ck zur Startseite f?r das Add-In zu navigieren.
Klicken Sie auf Mitarbeiter anzeigen, und die Liste der Mitarbeiter wird mit dem Mitarbeiter, den Sie hinzugef?gt haben, aufgef?llt. Sie sollte etwa wie folgt aussehen:

Abbildung 5: Liste der Mitarbeiter des Unternehmens auf der Add-In-Startseite
Schließen Sie zum Beenden der Debugsitzung das Browserfenster, oder beenden Sie das Debuggen in Visual Studio. Wann immer Sie F5 drücken, zieht Visual Studio die bisherige Version des Add-Ins zurück und installiert die jeweils neueste Version.
Da Sie mit diesem Add-In und dieser Visual Studio-Lösung in anderen Artikeln arbeiten werden, hat es sich bewährt, das Add-In ein letztes Mal zurückzuziehen, wenn Sie Ihre Arbeit daran für eine Weile abgeschlossen haben. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projekt, und wählen Sie die Option Zurückziehen aus.

Nächste Schritte

In diesem Artikel legen Sie eine kurze Pause vom Codieren ein, um einen schnellen ?berblick ?ber das SharePoint-Clientobjektmodell (CSOM) zu erhalten.

Freigeben über