Erste Schritte mit Azure WebJobs für Ihre Office 365-Websites
Wenn Sie mit Office 365 den SharePoint Online-Dienst ausführen und verwenden, müssen Sie die Art und Weise überdenken, wie Sie früher Zeitgeberaufträge ausführen, die in Ihren herkömmlichen Farmlösungen.
In der herkömmlichen SharePoint-Entwicklung verwenden Sie Zeitgeberaufträge, um geplante Aufgaben in SharePoint-Farmen auszuführen. Eine häufig verwendete Technik besteht darin, benutzerdefinierte Zeitgeberaufträge zu entwickeln, um bestimmte Aufgaben in Ihrer Umgebung kontinuierlich oder iterativ auszuführen. Mit Office 365 und SharePoint Online haben Sie nicht die Möglichkeit, Ihre Farmlösungen bereitzustellen, in denen sich Ihre herkömmlichen Zeitgeberaufträge normalerweise befinden. Stattdessen müssen Sie eine andere Möglichkeit finden, Ihre Aufgaben zu planen, was uns zu Azure WebJobs führt.
In diesem Artikel werden die grundlegenden Konzepte für die ersten Schritte beim Erstellen von benutzerdefinierten Aufträgen für Office 365-Websites beschrieben, und es wird beschrieben, wie Sie einen Azure-WebJob erstellen können, der als geplanter Auftrag für Ihre Office 365-SharePoint-Installation (oder lokal) fungiert.
Erstellen des WebJobs mit Visual Studio
Um einen neuen WebJob zu erstellen, müssen Sie lediglich eine neue Konsolenanwendung erstellen und sicherstellen, dass Sie dem Projekt die erforderlichen Assemblys hinzufügen. In diesem Beispiel verwenden wir Visual Studio.
Schritt 1: Erstellen der Konsolenanwendung
Erstellen Sie zunächst ein neues Projekt, und stellen Sie sicher, dass Sie die Vorlage Konsolenanwendung auswählen. Stellen Sie außerdem sicher, dass Sie .NET Framework 4.5 oder höher auswählen.
Schritt 2: Hinzufügen der SharePoint-spezifischen Assemblys aus NuGet
Wenn Sie Visual Studio verwenden, unterscheidet sich das Dialogfeld für den NuGet-Paket-Manager möglicherweise geringfügig von früheren Versionen von Visual Studio, aber das Konzept ist identisch.
Wählen Sie Tools>NuGet-Paket-Manager>NuGet-Pakete für Lösung verwalten aus, und suchen Sie nach App für SharePoint.
Installieren Sie das Paket namens AppForSharePointOnlineWebToolkit.
Das Toolkit installiert die erforderlichen Hilfsklassen für die Arbeit mit dem clientseitigen SharePoint-Objektmodell (CSOM).
Stellen Sie sicher, dass das NuGet-Paket funktioniert hat, indem Sie sicherstellen, dass die folgenden zwei neuen Klassen in Ihrem Konsolenanwendungsprojekt angezeigt werden:
- SharePointContext.cs
- TokenHelper.cs
Schritt 3: Hinzufügen des erforderlichen Codes zum Ausführen des Auftrags auf Ihrer Office 365-Website
An diesem Punkt haben Sie Ihre Konsolenanwendung erstellt und die erforderlichen Assemblys hinzugefügt, mit denen Sie problemlos mit SharePoint kommunizieren können. Die nächsten Schritte bestehen darin, diese Hilfsklassen zum Ausführen von Befehlen in Ihrer SharePoint-Umgebung mithilfe Ihrer Konsolenanwendung zu verwenden.
Hinweis
Im fertigen Beispiel verwenden Sie einen Konto- und Kennwortansatz (z. B. ein Dienstkonto). Authentifizierungsoptionen werden weiter unten in diesem Artikel erläutert.
Verknüpfen der Aufrufe der SharePoint Online-Websitesammlung
Der folgende Code veranschaulicht, wie Sie den Aufruf Ihrer Website jetzt verknüpfen, nachdem Sie die Hilfsklassen aus Ihrem NuGet-Paket hinzugefügt haben.
static void Main(string[] args)
{
using (ClientContext context = new ClientContext("https://redacted.sharepoint.com"))
{
// Use default authentication mode
context.AuthenticationMode = ClientAuthenticationMode.Default;
// Specify the credentials for the account that will execute the request
context.Credentials = new SharePointOnlineCredentials(GetSPOAccountName(), GetSPOSecureStringPassword());
// TODO: Add your logic here!
}
}
private static SecureString GetSPOSecureStringPassword()
{
try
{
Console.WriteLine(" - > Entered GetSPOSecureStringPassword()");
var secureString = new SecureString();
foreach (char c in ConfigurationManager.AppSettings["SPOPassword"])
{
secureString.AppendChar(c);
}
Console.WriteLine(" - > Constructed the secure password");
return secureString;
}
catch
{
throw;
}
}
private static string GetSPOAccountName()
{
try
{
Console.WriteLine(" - > Entered GetSPOAccountName()");
return ConfigurationManager.AppSettings["SPOAccount"];
}
catch
{
throw;
}
}
Sie können in der Beispielanwendung sehen, dass zwei Hilfsmethoden zum Abrufen des Kontonamens und des Kontokennworts aus der Datei "app.config" hinzugefügt wurden. Diese werden im Abschnitt zur Authentifizierung weiter unten in diesem Artikel erläutert.
Wie bei der Main Methode müssen Sie alles mit Ihrem Portal verknüpfen. Bevor Sie sich eingehender damit befassen, wie Sie SharePoint über Ihren Code bearbeiten können, besprechen wir die Optionen für die Authentifizierung.
Berücksichtigen von Authentifizierungsoptionen
Dafür gibt es zwei Möglichkeiten. In den folgenden Abschnitten werden diese häufig verwendeten Ansätze und ihre Unterschiede beschrieben.
Option 1: Verwenden eines Dienstkontos (Benutzername und Kennwort)
Dieser Ansatz ist recht einfach und ermöglicht es Ihnen, einfach ein Konto und ein Kennwort für Ihren Office 365-Mandanten einzugeben und dann z. B. CSOM zum Ausführen von Code auf Ihren Websites zu verwenden. Dies wurde auch im vorherigen Beispielcode ausgeführt.
Erstellen eines neuen Kundenkontos in Office 365
Damit dies funktioniert, sollten Sie ein bestimmtes Konto erstellen, das als Dienstkonto für diese spezifische Anwendung oder ein allgemeines Dienstanwendungskonto fungiert, das von allen Ihren Aufträgen und Diensten verwendet werden kann.
Für diese Demo haben wir ein neues Konto namens SP WebJob erstellt.
Abhängig von den Berechtigungen, über die der Auftrag verfügen sollte, müssen Sie die Berechtigungen des Kontos bearbeiten, wenn Sie es einrichten.
Speichern von Anmeldeinformationen in "app.config"
In der Datei "app.config" Ihres Projekts können Sie die Anmeldeinformationen angeben, damit sie problemlos aus der ausführbaren Codedatei abgerufen werden können. So sieht die Datei "app.config" aus:
<?xml version="1.0" encoding="utf-8" ?>
<configuration>
<startup>
<supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.5" />
</startup>
<appSettings>
<add key="SPOAccount" value="spwebjob@redacted.onmicrosoft.com"/>
<add key="SPOPassword" value="redacted"/>
</appSettings>
</configuration>
Die beiden Einstellungen werden in der Datei "app.config" angezeigt:
- SPOAccount
- SPOPassword
Wenn Sie den ersten Codeausschnitt überprüfen, stammen diese Einstellungen aus der Datei "app.config". Denken Sie daran, dass dies bedeutet, dass der Kontoname und das Kennwort in Klartext in Ihrer App.config gespeichert werden müssen. Sie müssen in Ihren eigenen Projekten entscheiden, wie und wo Sie Ihre Kennwörter speichern und schützen sollten, wenn Sie diesen Ansatz wählen.
Ausführen des Auftrags unter dem angegebenen Konto
Nachdem die Anwendung ausgeführt wurde, wird sie mit dem im SharePointOnlineCredentials()-Konstruktor angegebenen Konto ausgeführt.
Im vorherigen Beispiel führt der WebJob Aktionen für eine benutzerdefinierte Liste auf einer der Websites aus, die in einer SharePoint Online-Websitesammlung gehostet werden.
Aus diesem Grund können Sie eine ziemlich gute Nachverfolgbarkeit von Änderungen im Portal erhalten, die von Ihrem Dienstkonto ausgeführt werden. Aus diesem Grund ist es wichtig, das Konto mit Bedacht zu benennen. jeder weiß, dass die Änderungen automatisch von Ihrem Dienst vorgenommen wurden, indem er sich einfach die geänderten/erstellten Metadaten angesehen hat.
Option 2: Verwenden von OAuth und Einschließen von Authentifizierungstoken in Ihre Anforderungen, um die Angabe von Konto/Kennwort zu vermeiden
In einem Blogbeitrag von Kirk Evans namens Building a SharePoint Add-In as a Timer Job erläutert er, wie Sie Zugriffstoken verwenden und übergeben können, um Benutzernamen-/Kennwortsetups zu vermeiden, falls Sie die Kennwörter und Anmeldeinformationen nicht in Ihrer Anwendung speichern möchten.
Erweitern des Codes mit CSOM
An diesem Punkt verfügen Sie über eine funktionierende Konsolenanwendung, die Anforderungen an Ihre Office 365-Websites authentifizieren und ausführen kann. Im Code wurde noch nichts Ausgefallenes getan. Hier ist also ein Beispielausschnitt zum Abrufen einiger Informationen aus einer Liste namens Automatische Übersetzungen. Die Codelogik bestimmt, ob Elemente in der Liste vorhanden sind, die nicht übersetzt wurden. Anschließend wird ein Aufruf eines Übersetzungsdiensts ausgeführt und der Text in die gewünschte Ausgabesprache übersetzt.
static void Main(string[] args)
{
try
{
Console.WriteLine("Initiating Main()");
using (ClientContext context = new ClientContext("https://redacted.sharepoint.com"))
{
Console.WriteLine("New ClientContext('https://redacted.sharepoint.com') opened. ");
context.AuthenticationMode = ClientAuthenticationMode.Default;
context.Credentials = new SharePointOnlineCredentials(GetSPOAccountName(), GetSPOSecureStringPassword());
Console.WriteLine("Authentication Mode and Credentials configured");
List translationlist = context.Web.Lists.GetByTitle("Automatic Translations");
context.Load(translationlist);
context.ExecuteQuery();
Console.WriteLine("TranslationList fetched, loaded and ExecuteQuery'ed");
if (translationlist != null && translationlist.ItemCount > 0)
{
Console.WriteLine("The list exist, let's do some magic");
CamlQuery camlQuery = new CamlQuery();
camlQuery.ViewXml =
@"<View>
<Query>
<Where><Eq><FieldRef Name='IsTranslated' /><Value Type='Boolean'>0</Value></Eq></Where>
</Query>
</View>";
ListItemCollection listItems = translationlist.GetItems(camlQuery);
context.Load(listItems);
context.ExecuteQuery();
Console.WriteLine("Query for listItems executed.");
foreach (ListItem item in listItems)
{
item["Output"] = TranslatorHelper.GetTranslation(item["Title"], item["Target Language"], item["Original Language"]);
item["IsTranslated"] = true;
item.Update();
}
context.ExecuteQuery();
Console.WriteLine("Updated all the list items you found. Carry on...");
}
}
}
catch (Exception ex)
{
Console.WriteLine("ERROR: " + ex.Message);
Console.WriteLine("ERROR: " + ex.Source);
Console.WriteLine("ERROR: " + ex.StackTrace);
Console.WriteLine("ERROR: " + ex.InnerException);
}
}
Die TranslatorHelper -Klasse ist eine Hilfsklasse, die eine benutzerdefinierte Übersetzungs-API aufruft, aber sie wird in diesem Beitrag nicht ausführlich erläutert, da sie außerhalb des Bereichs dieses Artikels liegt.
Hinweis
Wie aus dem Code ersichtlich, ist dies eine Demo und definitiv nicht für die Verwendung in der Produktion. Überarbeiten Sie sie, und passen Sie sie an Ihre Codierungsstandards und Sicherheitsprinzipien an. Allerdings werden alle Console.WriteLine-Hinzufügungen hinzugefügt, damit Sie die Ausführung der Aufträge problemlos über die Azure-Portalüberprüfen können. Weitere Informationen zur Protokollierung und Überwachung finden Sie weiter unten in diesem Artikel.
Veröffentlichen Sie Ihren WebJob in Azure
Wenn Sie Ihren WebJob entwickelt haben und bereit sind, ihn in Ihrer Azure-Umgebung (auf einer Azure-Website) bereitzustellen, haben Sie zwei Hauptoptionen, wie in den folgenden Abschnitten beschrieben.
Option 1: Hochladen einer ZIP-Datei mit den WebJob-Binärdateien in Ihre Azure-Portal
Mithilfe der Azure-Portal, in der Sie ihre Ganzes in Azure behalten, können Sie eine ZIP-Datei hochladen, die die Ausgabe des Builds Visual Studio enthält. Dies ist eine einfache Möglichkeit zum Kompilieren und Versenden Ihres Codes an eine andere Person, die die Bereitstellung für Sie durchführt.
Erstellen Sie die ZIP-Datei
Rufen Sie einfach alle Ausgabedateien aus Ihrem Visual Studio Build ab (normalerweise im Ordner "bin/Debug" oder "bin/Release").
Komprimieren Sie sie, sodass Sie eine ansprechende ZIP-Datei für Ihren WebJob erhalten.
Suchen einer Website, auf der der Auftrag bereitgestellt werden soll
Nachdem Sie ihr Paket erhalten haben, besteht der nächste Schritt darin, zu Ihrem Azure-Portal zu wechseln und sich anzumelden.
Von dort aus müssen Sie entweder eine neue Webseite erstellen oder eine vorhandene Webseite verwenden. Diese Webseite ist der Host für Ihren WebJob.
Wenn Sie im Einstellungsbereich für Ihre Webseite nach unten scrollen, finden Sie unter der Kopfzeile Vorgänge eine Kachel namensWebJobs.
Klicken Sie auf den Bereich, auf den der Pfeil zeigt.
Laden Sie Ihren WebJob hoch
Laden Sie Ihren WebJob hoch, indem Sie die [+ Hinzufügen] Signieren auswählen.
Wählen Sie einen Namen und die Art und Weise aus, wie der Auftrag ausgeführt werden soll, und laden Sie dann die eigentliche ZIP-Datei hoch.
Wichtig
Die alternative How to Run bietet derzeit nur On Demand oder Continuous. In Kürze wird jedoch auch Geplante unterstützt, was Sie wirklich wünschen. Im Abschnitt "Direkte Veröffentlichung in Azure" können Sie ihn innerhalb Visual Studio planen.
Sie können Ihren WebJob jetzt über Ihre Azure-Portal ausführen.
Option 2: Direktes Veröffentlichen in Azure über Visual Studio
Sie können die Tools in Visual Studio verwenden, um Änderungen schnell direkt in Ihrem gehosteten Dienst zu veröffentlichen. Sie können den Auftrag auch genau so planen, wie er direkt in den Dialogen in Visual Studio ausgeführt werden soll.
Veröffentlichen Sie den WebJob über Visual Studio
Hinweis
Diese Dialogfelder können sich geringfügig unterscheiden, wenn Sie eine frühere Version von Visual Studio ausführen. Wenn Sie dies zum ersten Mal tun, erhalten Sie möglicherweise ein Anmeldedialogfeld, um sich bei Ihrem Azure-Konto anzumelden.
Klicken Sie mit der rechten Maustaste auf das Webprojekt und anschließend auf Als Azure WebJob veröffentlichen.
Azure WebJob hinzufügen
Dadurch gelangen Sie zu einem neuen Dialogfeld, in dem Sie den Auftrag konfigurieren können. Da Sie einen wiederkehrenden Auftrag wünschen, der nach einem Zeitplan ausgeführt werden soll (z. B. einmal pro Nacht), können Sie den Zeitplan direkt über die Dialogfelder konfigurieren.
Stellen Sie sicher, dass der WebJob-Name webfreundlich ist.
Wählen Sie ihren WebJob-Ausführungsmodusaus. Wenn sie jeden Tag zu einer bestimmten Uhrzeit auftreten soll, wählen Sie Ausführen nach einem Zeitplanaus.
Sollte es sich bei dem Auftrag um einen sich wiederholenden oder um einen einmaligen Auftrag verhalten? Da Sie einen Zeitgeberauftrag simulieren möchten, muss er periodisch sein und jede Nacht ohne Enddatum ausgeführt werden.
Sie können die Wiederholung bei Bedarf auf jede Minute planen.
Geben Sie das Startdatum und Uhrzeitsowie die Zeitzonean.
Wählen Sie OK aus. Visual Studio sendet die folgende Meldung: Installation NuGet-Paket zur WebJobs-Veröffentlichung Package.
Dadurch wird Ihrem Projekt eine neue Datei namens "webjob-publish-settings.json" hinzugefügt, die die Konfiguration für den Auftrag enthält.
Die Überprüfung sieht wie folgt aus:
{ "$schema": "http://schemastore.org/schemas/json/webjob-publish-settings.json", "webJobName": "Zimmergren-O365-WebJobSample", "startTime": "2015-01-09T01:00:00+01:00", "endTime": null, "jobRecurrenceFrequency": "Day", "interval": 1, "runMode": "Scheduled" }Hinweis
Sie benötigen diese Datei im Moment nicht, da Sie die Planung bereits mithilfe der Dialogfelder entworfen haben.
Veröffentlichungs-/Bereitstellungsziel auswählen
Der nächste Schritt im Dialogfeld besteht darin, anzugeben, wo Ihr WebJob veröffentlicht/bereitgestellt werden soll. Sie können entweder ein Veröffentlichungsprofil importieren oder Azure-Websites zur Authentifizierung auswählen und eine Ihrer vorhandenen Websites auswählen.
Wählen Sie in Ihrem Azure-Portal Import aus, und geben Sie die Veröffentlichungsprofildatei an, die Sie von Ihrer Azure-Website heruntergeladen haben.
Veröffentlichen
Anschließend müssen Sie nur noch Veröffentlichenauswählen. Im Dialogfeld Webveröffentlichungsaktivität wird dann der Fortschritt Ihrer WebJob-Bereitstellung angezeigt.
Wenn sie fertig ist, sollte der WebJob in Ihrer Azure-Portal angezeigt werden.
Der WebJob-Status wird jetzt als Abgeschlossenangezeigt. Es würde Fehlfunktion/Fehler melden, wenn er nicht behandelte Ausnahmen ausgelöst oder anderweitig ein fehlerhaftes Verhalten bereitgestellt hat.
Der Typ besagt immer noch On Demand, aber dieser Auftrag wird jetzt tatsächlich einmal pro Stunde ausgeführt.
Überwachen des Auftrags und Überprüfen von Protokollen
Wenn Sie alle vorherigen Schritte abgeschlossen haben, haben Sie nun einen Auftrag, der für Sie als geplante Aufgabe in der Cloud arbeitet und Aktionen für Ihre Office 365-Websites ausführt.
Wenn Sie überprüfen möchten, wann der Auftrag zuletzt ausgeführt wurde, was das Ergebnis jeder Ausführung des Auftrags war oder was während der Ausführung des Auftrags passiert ist, können Sie den Link unter Protokolle auswählen, wenn Sie sich in der WebJobs-Übersicht befinden.
Dadurch erhalten Sie einen Überblick über alle Ausführungen der ausgewählten Aufträge, einschließlich Zustand/Ergebnis.
Wenn Sie den hervorgehobenen Link auswählen, können Sie eine bestimmte Ausführung untersuchen, um die Protokolle des Auftrags zu überprüfen und sicherzustellen, dass alles in Ordnung aussieht. Dies ist wahrscheinlich relevanter, wenn der Auftrag tatsächlich einen Fehler verursacht hat und Sie untersuchen mussten, was schief gelaufen ist, oder wenn das Ergebnis des Auftrags falsch oder nicht erwartungsgemäß ist.
Sie können auch sehen, dass die Console.WriteLine-Anweisungen, die wir in der Konsolenanwendung für diese Demo verwendet haben, jetzt im Auftragsausführungsprotokoll angezeigt werden.
Siehe auch
- Ursprünglicher Blogbeitrag zu Azure WebJobs von Tobias Zimmergren
- Entwickeln und Bereitstellen von WebJobs mit Visual Studio – Azure App Service
- Einfacher Remotetimerauftrag, der mit SharePoint Online interagiert,Video von Andrew Connell auf Channel9
- Verwenden von Microsoft Azure WebJobs mit Office 365
- Framework für PnP-Remotezeitgeberauftrag