Einrichten der lokalen Entwicklung für Azure Static Web Apps

Artikel
02/05/2024

Bei Veröffentlichung in der Cloud verknüpft eine Azure Static Web Apps-Website zahlreiche Dienste, die wie eine einzelne Anwendung zusammenarbeiten. Zu diesen Diensten gehören:

Die statische Web-App
Azure Functions-API
Authentifizierungs- und Autorisierungsdienste
Routing- und Konfigurationsdienste

Diese Dienste müssen miteinander kommunizieren, und in der Cloud nimmt Azure Static Web Apps Ihnen diese Integration ab.

Wenn Sie Ihre Anwendung jedoch lokal ausführen, sind diese Dienste nicht automatisch miteinander verknüpft.

Um eine ähnliche Funktionalität wie in Azure zu erreichen, bietet die Azure Static Web Apps-Befehlszeilenschnittstelle folgende Dienste:

Lokaler statischer Websiteserver
Proxy für den Entwicklungsserver des Front-End-Frameworks
Proxy für Ihre API-Endpunkte (verfügbar über Azure Functions Core Tools)
Simulierter Authentifizierungs- und Autorisierungsserver
Erzwingung lokaler Routen und Konfigurationseinstellungen

Hinweis

Häufig erfordern Websites, die mit einem Front-End-Framework erstellt wurden, eine Proxykonfigurationseinstellung, um Anforderungen unter der api-Route ordnungsgemäß zu verarbeiten. Wenn Sie die Azure Static Web Apps CLI verwenden, lautet der Wert für den Proxyspeicherort /api, und ohne die CLI ist der Wert http://localhost:7071/api.

Funktionsweise

Das folgende Diagramm veranschaulicht die lokale Behandlung von Anforderungen:

Diagram showing the Azure Static Web App CLI request and response flow.

Wichtig

Navigieren Sie zu http://localhost:4280, um auf die von der Befehlszeilenschnittstelle bereitgestellte Anwendung zuzugreifen.

An den Port 4280 gesendete Anforderungen werden je nach Art der Anforderung an den entsprechenden Server weitergeleitet.
Anforderungen vom Typ Statischer Inhalt (beispielsweise HTML oder CSS) werden entweder vom statischen Inhaltsserver der internen Befehlszeilenschnittstelle oder vom Front-End-Framework-Server (zum Debuggen) behandelt.
Anforderungen vom Typ Authentifizierung und Autorisierung werden von einem Emulator behandelt, der ein unechtes Identitätsprofil für Ihre App bereitstellt.
Von der Functions Core Tools-Runtime¹ werden Anforderungen für die API der Website behandelt.
Antworten von allen Diensten werden an den Browser zurückgegeben, als würde es sich um eine einzelne Anwendung handeln.

Nachdem Sie die Benutzeroberfläche und die Azure Functions-API-Apps unabhängig voneinander gestartet haben, starten Sie die Static Web Apps-CLI, und verweisen Sie mit dem folgenden Befehl auf die ausgeführten Apps:

swa start http://localhost:<DEV-SERVER-PORT-NUMBER> --api-location http://localhost:7071

Wenn Sie optional den swa init-Befehl verwenden, betrachtet die Static Web Apps CLI Ihren Anwendungscode und erstellt die Konfigurationsdatei swa-cli.config.json für die CLI. Wenn Sie die Datei swa-cli.config.json verwenden, können Sie swa start ausführen, um Ihre Anwendung lokal zu starten.

¹ Die Azure Functions Core Tools werden automatisch von der CLI installiert, wenn sie sich nicht bereits auf Ihrem System befinden.

Im folgenden Artikel werden die Schritte zum Ausführen einer knotenbasierten Anwendung beschrieben. Der Prozess ist für jede Sprache oder Umgebung identisch.

Voraussetzungen

Vorhandene Azure Static Web Apps-Website: Sollten Sie über keine Website verfügen, beginnen Sie mit der Starter-App vanilla-api.
Node.js mit npm: Verwenden Sie die Version Node.js LTS (beinhaltet Zugriff auf npm).
Visual Studio Code: Dient zum Debuggen der API-Anwendung, ist für die Befehlszeilenschnittstelle aber nicht erforderlich.

Erste Schritte

Öffnen Sie ein Terminal am Stammordner Ihrer vorhandenen Azure Static Web Apps-Website.

Installieren Sie die Befehlszeilenschnittstelle.
```
npm install -D @azure/static-web-apps-cli
```
Tipp

Wenn Sie die SWA CLI global installieren möchten, verwenden Sie -g anstelle von -D. Es wird jedoch dringend empfohlen, SWA als Entwicklungsabhängigkeit zu installieren.
Erstellen Sie Ihre App, falls dies für Ihre Anwendung erforderlich ist.

Führen Sie npm run build oder den entsprechenden Befehl für Ihr Projekt aus.
Initialisieren Sie das Repository für die CLI.
```
swa init
```
Beantworten Sie die von der CLI gestellten Fragen, um zu überprüfen, ob Ihre Konfigurationseinstellungen korrekt sind.
Starten Sie die Befehlszeilenschnittstelle.
```
swa start
```
Navigieren Sie zu http://localhost:4280, um die App im Browser anzuzeigen.

Weitere Möglichkeiten zum Starten der Befehlszeilenschnittstelle

Beschreibung	Get-Help	Kommentare
Bereitstellen eines bestimmten Ordners	`swa start ./<OUTPUT_FOLDER_NAME>`	Ersetzen Sie `<OUTPUT_FOLDER_NAME>` durch den Namen Ihres Ausgabeordners.
Verwenden eines aktiven Framework-Entwicklungsservers	`swa start http://localhost:3000`	Dieser Befehl funktioniert, wenn eine Instanz Ihrer Anwendung unter Port `3000` ausgeführt wird. Aktualisieren Sie die Portnummer, wenn Ihre Konfiguration anders ist.
Starten einer Funktions-App in einem Ordner	`swa start ./<OUTPUT_FOLDER_NAME> --api-location ./api`	Ersetzen Sie `<OUTPUT_FOLDER_NAME>` durch den Namen Ihres Ausgabeordners. Dieser Befehl erwartet, dass die API Ihrer Anwendung Dateien im `api` Ordner enthält. Aktualisieren Sie diesen Wert, wenn Ihre Konfiguration anders ist.
Verwenden einer aktiven Funktions-App	`swa start ./<OUTPUT_FOLDER_NAME> --api-location http://localhost:7071`	Ersetzen Sie `<OUTPUT_FOLDER_NAME>` durch den Namen Ihres Ausgabeordners. Dieser Befehl erwartet, dass Ihre Azure Functions-Anwendung über Port `7071` verfügbar ist. Aktualisieren Sie die Portnummer, wenn Ihre Konfiguration anders ist.

Autorisierungs- und Authentifizierungsemulation

Die Static Web Apps-Befehlszeilenschnittstelle emuliert den in Azure implementierten Sicherheitsflow. Wenn sich ein Benutzer anmeldet, können Sie ein unechtes Identitätsprofil definieren, das an die App zurückgegeben wird.

Wenn Sie also beispielsweise versuchen, zu /.auth/login/github zu navigieren, wird eine Seite zurückgegeben, auf der Sie ein Identitätsprofil definieren können.

Hinweis

Der Emulator kann mit einem beliebigen Sicherheitsanbieter verwendet werden, nicht nur mit GitHub.

Local authentication and authorization emulator

Der Emulator bietet eine Seite, auf der Sie die folgenden Werte für den Clientprinzipal angeben können:

Wert	BESCHREIBUNG
Benutzername	Der dem Sicherheitsanbieter zugeordnete Kontoname. Dieser Wert wird im Clientprinzipal als Eigenschaft `userDetails` angezeigt und automatisch generiert, wenn Sie keinen Wert angeben.
Benutzer-ID	Automatisch von der Befehlszeilenschnittstelle generierter Wert.
Rollen	Eine Rollennamenliste mit jeweils einer Zeile pro Name.
Ansprüche	Eine Liste von Benutzeransprüchen, wobei jeder Name in einer neuen Zeile steht.

Nach der Anmeldung gilt Folgendes:

Sie können den Endpunkt /.auth/me oder einen Funktionsendpunkt verwenden, um den Clientprinzipal des Benutzers abzurufen.
Navigieren zum /.auth/logout Löschen des Clientprinzipals und Abmelden des simulierten Benutzers.

Debuggen

In einer statischen Web-App gibt es zwei Debugkontexte: einen für die statische Inhaltswebsite und einen für API-Funktionen. Lokales Debuggen ist möglich, indem der Static Web Apps-Befehlszeilenschnittstelle die Verwendung von Entwicklungsservern für einen oder beide dieser Kontexte ermöglicht wird.

Die folgenden Schritte zeigen ein gängiges Szenario, in dem Entwicklungsserver für beide Debugkontexte verwendet werden.

Starten Sie den statischen Websiteentwicklungsserver. Dieser Befehl ist für das von Ihnen verwendete Front-End-Framework spezifisch, lautet aber häufig npm run build, npm start oder npm run dev.
Öffnen Sie den API-Anwendungsordner in Visual Studio Code, und starten Sie eine Debugsitzung.
Starten Sie die Static Web Apps-CLI mit dem folgenden Befehl.
```
swa start http://localhost:<DEV-SERVER-PORT-NUMBER> --appDevserverUrl http://localhost:7071
```
Ersetzen Sie <DEV_SERVER_PORT_NUMBER> durch die Portnummer des Entwicklungsservers.

Die folgenden Screenshots zeigen die Terminals für ein typisches Debugszenario:

Die statische Inhaltswebsite wird über npm run dev ausgeführt.

Static site development server

Von der Azure Functions-API-Anwendung wird eine Debugsitzung in Visual Studio Code ausgeführt.

Visual Studio Code API debugging

Die Static Web Apps-Befehlszeilenschnittstelle wird unter Verwendung beider Entwicklungsserver gestartet.

Azure Static Web Apps CLI terminal

Anforderungen über den Port 4280 werden nun entweder an den statischen Inhaltsentwicklungsserver oder an die API-Debugsitzung weitergeleitet.

Weitere Informationen zu verschiedenen Debugszenarien sowie Anleitungen zum Anpassen von Ports und Serveradressen finden Sie im Repository für die Azure Static Web Apps-Befehlszeilenschnittstelle.

Debug-Beispielkonfiguration

Visual Studio Code verwendet eine Datei, um Debugsitzungen im Editor zu ermöglichen. Wenn Visual Studio Code keine launch.json-Datei für Sie generiert, können Sie die folgende Konfiguration in .vscode/launch.json platzieren.

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Attach to Node Functions",
            "type": "node",
            "request": "attach",
            "port": 9229,
            "preLaunchTask": "func: host start"
        }
    ]
}

Nächste Schritte

Konfigurieren Der Anwendung

Freigeben über