Lokale ontwikkeling instellen voor Azure Static Web Apps

Wanneer een Azure Static Web Apps site naar de cloud wordt gepubliceerd, worden veel services gekoppeld die samenwerken alsof ze dezelfde toepassing zijn. Deze services omvatten:

  • De statische web-app
  • Azure Functions-API
  • Verificatie- en autorisatieservices
  • Routerings- en configuratieservices

Deze services moeten met elkaar communiceren en Azure Static Web Apps deze integratie voor u in de cloud afhandelt.

Deze services worden echter niet automatisch aan elkaar gekoppeld.

Om een vergelijkbare ervaring te bieden als wat u in Azure krijgt, biedt de Azure Static Web Apps CLI de volgende services:

  • Een lokale statische siteserver
  • Een proxy naar de front-endframeworkontwikkelingsserver
  • Een proxy naar uw API-eindpunten- beschikbaar via Azure Functions Core Tools
  • Een mock-verificatie- en autorisatieserver
  • Afdwingen van lokale routes en configuratie-instellingen

Notitie

Vaak vereisen sites die zijn gebouwd met een front-endframework een proxyconfiguratie-instelling om aanvragen onder de api route correct te verwerken. Wanneer u de Azure Static Web Apps CLI gebruikt, is /apide waarde van de proxylocatie en zonder de CLI de waardehttp://localhost:7071/api.

Uitleg

In de volgende grafiek ziet u hoe aanvragen lokaal worden verwerkt.

Cli-aanvraag- en antwoordstroom voor Azure Static Web App

Belangrijk

Navigeer naar toegang tot http://localhost:4280 de toepassing die wordt geleverd door de CLI.

  • Aanvragen die naar de poort 4280 worden verzonden, worden doorgestuurd naar de juiste server, afhankelijk van het type aanvraag.

  • Aanvragen voor statische inhoud , zoals HTML of CSS, worden verwerkt door de interne CLI-server voor statische inhoud of door de front-endframeworkserver voor foutopsporing.

  • Verificatie- en autorisatieaanvragen worden verwerkt door een emulator, die een nep-identiteitsprofiel aan uw app biedt.

  • Functions Core Tools runtime1 verwerkt aanvragen naar de API van de site.

  • Antwoorden van alle services worden geretourneerd naar de browser alsof ze allemaal één toepassing zijn.

In het volgende artikel worden de stappen beschreven voor het uitvoeren van een toepassing op knooppunten, maar het proces is hetzelfde voor elke taal of omgeving. Nadat u de gebruikersinterface en de Azure Functions API-apps onafhankelijk hebt gestart, start u de Static Web Apps CLI en wijst u deze aan met behulp van de volgende opdracht naar de actieve apps:

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

Als u de swa init opdracht gebruikt, kijkt de Static Web Apps CLI naar uw toepassingscode en bouwt u een swa-cli.config.json-configuratiebestand voor de CLI. Wanneer u het bestandswa-cli.config.json gebruikt, kunt u de swa start toepassing lokaal starten.

1 De Azure Functions Core Tools worden automatisch geïnstalleerd door de CLI als ze nog niet op uw systeem staan.

Vereisten

Aan de slag

Open een terminal naar de hoofdmap van uw bestaande Azure Static Web Apps-site.

  1. Installeer de CLI.

    npm install @azure/static-web-apps-cli
    
  2. Bouw uw app indien nodig door uw toepassing.

    Voer npm run buildof de equivalente opdracht voor uw project uit.

  3. Initialiseer de opslagplaats voor de CLI.

    swa init
    

    Beantwoord de vragen van de CLI om te controleren of uw configuratie-instellingen juist zijn.

  4. Start de CLI.

    swa start
    
  5. Ga naar de http://localhost:4280 app weergeven in de browser.

Andere manieren om de CLI te starten

Description Opdracht Opmerkingen
Een specifieke map gebruiken swa start ./<OUTPUT_FOLDER_NAME> Vervang door <OUTPUT_FOLDER_NAME> de naam van de uitvoermap.
Een actieve frameworkontwikkelingsserver gebruiken swa start http://localhost:3000 Deze opdracht werkt wanneer u een exemplaar van uw toepassing hebt dat wordt uitgevoerd onder poort 3000. Werk het poortnummer bij als uw configuratie anders is.
Een Functions-app in een map starten swa start ./<OUTPUT_FOLDER_NAME> --api-location ./api Vervang door <OUTPUT_FOLDER_NAME> de naam van de uitvoermap. Met deze opdracht wordt verwacht dat de API van uw toepassing bestanden bevat in de API-map . Werk deze waarde bij als uw configuratie anders is.
Een actieve Functions-app gebruiken swa start ./<OUTPUT_FOLDER_NAME> --api-location http://localhost:7071 Vervang door <OUTPUT_FOLDER_NAME> de naam van de uitvoermap. Met deze opdracht wordt verwacht dat uw Azure Functions-toepassing beschikbaar is via poort7071. Werk het poortnummer bij als uw configuratie anders is.

Autorisatie- en verificatie-emulatie

De Static Web Apps CLI emuleert de beveiligingsstroom die in Azure is geïmplementeerd. Wanneer een gebruiker zich aanmeldt, kunt u een nep-identiteitsprofiel definiëren dat wordt geretourneerd naar de app.

Wanneer u bijvoorbeeld probeert te /.auth/login/githubnavigeren, wordt er een pagina geretourneerd waarmee u een identiteitsprofiel kunt definiëren.

Notitie

De emulator werkt met elke beveiligingsprovider, niet alleen Met GitHub.

Lokale verificatie en autorisatieemulator

De emulator biedt een pagina waarmee u de volgende client-principalwaarden kunt opgeven:

Waarde Beschrijving
Gebruikersnaam De accountnaam die is gekoppeld aan de beveiligingsprovider. Deze waarde wordt weergegeven als de userDetails eigenschap in de client-principal en wordt automatisch gegenereerd als u geen waarde opgeeft.
Gebruikers-id Waarde automatisch gegenereerd door de CLI.
Rollen Een lijst met rolnamen, waarbij elke naam zich op een nieuwe regel bevindt.
Claims Een lijst met gebruikersclaims, waarbij elke naam zich op een nieuwe regel bevindt.

Zodra u bent aangemeld:

  • U kunt het /.auth/me eindpunt of een functie-eindpunt gebruiken om de client-principal van de gebruiker op te halen.

  • Navigeren om de clientprincipaal te /.auth/logout wissen en de mock-gebruiker uit te loggen.

Foutopsporing

Er zijn twee contexten voor foutopsporing in een statische web-app. De eerste is voor de statische inhoudssite en de tweede is voor API-functies. Lokale foutopsporing is mogelijk door de Static Web Apps CLI toe te staan ontwikkelservers te gebruiken voor een of beide contexten.

In de volgende stappen ziet u een veelvoorkomend scenario dat gebruikmaakt van ontwikkelingsservers voor beide foutopsporingscontexten.

  1. Start de statische siteontwikkelingsserver. Deze opdracht is specifiek voor het front-endframework dat u gebruikt, maar wordt vaak geleverd in de vorm van opdrachten zoals npm run build, npm startof npm run dev.

  2. Open de map API-toepassing in Visual Studio Code en start een foutopsporingssessie.

  3. Start de Static Web Apps CLI met behulp van de volgende opdracht.

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

    Vervang <DEV_SERVER_PORT_NUMBER> door het poortnummer van de ontwikkelserver.

In de volgende schermopnamen ziet u de terminals voor een typisch foutopsporingsscenario:

De statische inhoudssite wordt uitgevoerd via npm run dev.

Statische siteontwikkelingsserver

De Azure Functions API-toepassing voert een foutopsporingssessie uit in Visual Studio Code.

Foutopsporing voor Visual Studio Code-API

De Static Web Apps CLI wordt gestart met beide ontwikkelservers.

CLI-terminal Azure Static Web Apps

Aanvragen die via de poort 4280 worden verzonden, worden nu doorgestuurd naar de server voor statische inhoudsontwikkeling of de API-foutopsporingssessie.

Zie de Azure Static Web Apps CLI-opslagplaats voor meer informatie over verschillende foutopsporingsscenario's, met richtlijnen voor het aanpassen van poorten en serveradressen.

Voorbeeldconfiguratie voor foutopsporing

Visual Studio Code maakt gebruik van een bestand om foutopsporingssessies in te schakelen in de editor. Als Visual Studio Code geen launch.json-bestand voor u genereert, kunt u de volgende configuratie in .vscode/launch.json plaatsen.

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

Volgende stappen