Werken met Azure Functions Core Tools

Met Azure Functions Core Tools kunt u uw functies op uw lokale computer ontwikkelen en testen vanaf de opdrachtprompt of terminal. Uw lokale functies kunnen verbinding maken met live Azure-services en u kunt fouten opsporen in uw functies op uw lokale computer met behulp van de volledige Functions-runtime. U kunt zelfs een functie-app implementeren in uw Azure-abonnement.

Belangrijk

Combineer geen lokale ontwikkeling met portal-ontwikkeling in dezelfde functie-app. Wanneer u functies maakt en publiceert vanuit een lokaal project, moet u niet proberen projectcode in de portal te onderhouden of te wijzigen.

Als u functies ontwikkelt op uw lokale computer en deze publiceert naar Azure met behulp van Core Tools, voert u de volgende basisstappen uit:

Vereisten

De specifieke vereisten voor Core Tools zijn afhankelijk van de functies die u wilt gebruiken:

Publiceren: Core Tools is momenteel afhankelijk van de Azure CLI of Azure PowerShell voor verificatie met uw Azure-account. Dit betekent dat u een van deze hulpprogramma's moet installeren om vanuit Azure Functions Core Tools naar Azure te kunnen publiceren.

Extensies installeren: Als u extensies handmatig wilt installeren met Core Tools, moet de .NET Core 3.1 SDK zijn geïnstalleerd. De .NET Core SDK wordt door Core Tools gebruikt om extensies van NuGet te installeren. U hoeft .NET niet te kennen om Azure Functions-extensies te gebruiken.

Versies van Core Tools

Er zijn vier versies van Azure Functions Core Tools. De versie die u gebruikt, is afhankelijk van uw lokale ontwikkelomgeving, de keuze van de taal en het vereiste ondersteuningsniveau.

Kies hieronder een versietabblad voor meer informatie over elke specifieke versie en voor gedetailleerde installatie-instructies:

Ondersteunt versie 4.x van de Functions-runtime. Deze versie ondersteunt Windows, macOS en Linux en maakt gebruik van platformspecifieke pakketbeheerders of npm voor installatie. Dit is de aanbevolen versie van de Functions-runtime en Core Tools.

U kunt slechts één versie van Core Tools op een bepaalde computer installeren. Tenzij anders vermeld, zijn de voorbeelden in dit artikel voor versie 3.x.

Azure Functions Core Tools installeren

Azure Functions Core Tools bevat een versie van dezelfde runtime die Azure Functions runtime mogelijk maakt die u kunt uitvoeren op uw lokale ontwikkelcomputer. Het biedt ook opdrachten om functies te maken, verbinding te maken met Azure en functieprojecten te implementeren.

Vanaf versie 2.x worden Core Tools uitgevoerd op Windows, macOS en Linux.

In de volgende stappen wordt een Windows Installer (MSI) gebruikt om Core Tools v4.x te installeren. Zie het leesmij-leesmij-bestand voor Core Tools voor meer informatie over andere installatieprogramma's op basis van pakketten.

Download en voer het Core Tools-installatieprogramma uit op basis van uw versie van Windows:

Versies van Core Tools wijzigen

Wanneer u overgaat naar een andere versie van Core Tools, moet u hetzelfde pakketbeheer gebruiken als de oorspronkelijke installatie om naar een andere pakketversie te gaan. Als u bijvoorbeeld Core Tools versie 2.x hebt geïnstalleerd met npm, moet u de volgende opdracht gebruiken om een upgrade uit te voeren naar versie 3.x:

npm install -g azure-functions-core-tools@3 --unsafe-perm true

Als u Windows Installer (MSI) hebt gebruikt om Core Tools in Windows te installeren, moet u de oude versie verwijderen uit Programma's toevoegen voordat u een andere versie installeert.

Een lokaal Functions-project maken

Een Functions-projectmap bevat de volgende bestanden en mappen, ongeacht de taal:

Bestandsnaam Description
host.json Zie de verwijzing naar host.json voor meer informatie.
local.settings.json Instellingen die door Core Tools worden gebruikt bij het lokaal uitvoeren, inclusief app-instellingen. Zie de lokale instellingen voor meer informatie.
.gitignore Hiermee voorkomt u dat het bestand local.settings.json per ongeluk wordt gepubliceerd naar een Git-opslagplaats. Zie lokale instellingen voor meer informatie
.vscode\extensions.json Het instellingenbestand dat wordt gebruikt bij het openen van de projectmap in Visual Studio Code.

Zie de handleiding Azure Functions ontwikkelaars voor meer informatie over de projectmap Functions.

Voer in het terminalvenster of vanaf een opdrachtprompt de volgende opdracht uit om het project en de lokale Git-opslagplaats te maken:

func init MyFunctionProj

In dit voorbeeld wordt een Functions-project gemaakt in een nieuwe MyFunctionProj map. U wordt gevraagd om een standaardtaal voor uw project te kiezen.

De volgende overwegingen zijn van toepassing op project initialisatie:

  • Als u de --worker-runtime optie niet opgeeft in de opdracht, wordt u gevraagd uw taal te kiezen. Zie de func init-verwijzing voor meer informatie.

  • Wanneer u geen projectnaam opgeeft, wordt de huidige map geïnitialiseerd.

  • Als u van plan bent uw project te publiceren naar een aangepaste Linux-container, gebruikt u de --docker optie om ervoor te zorgen dat een Dockerfile voor uw project wordt gegenereerd. Zie Een functie maken in Linux met behulp van een aangepaste installatiekopieën voor meer informatie.

Bepaalde talen kunnen aanvullende overwegingen hebben:

  • Standaard maken versie 2.x en latere versies van de Core Tools functie-app-projecten voor de .NET-runtime als C#-klasseprojecten (.csproj). Versie 3.x biedt ook ondersteuning voor het maken van functies die worden uitgevoerd op .NET 5.0 in een geïsoleerd proces. Deze C#-projecten, die kunnen worden gebruikt met Visual Studio of Visual Studio Code, worden gecompileerd tijdens foutopsporing en bij het publiceren naar Azure.

  • Gebruik de --csx parameter als u lokaal wilt werken met C#-scriptbestanden (.csx). Dit zijn dezelfde bestanden die u krijgt wanneer u functies maakt in de Azure Portal en wanneer u versie 1.x van Core Tools gebruikt. Zie de func init-verwijzing voor meer informatie.

Extensies registreren

Vanaf runtimeversie 2.x worden Functions-triggers en -bindingen geïmplementeerd als .NET-extensiepakketten (NuGet). Voor gecompileerde C#-projecten verwijst u gewoon naar de NuGet-extensiepakketten voor de specifieke triggers en bindingen die u gebruikt. VOOR HTTP-bindingen en timertriggers zijn geen extensies vereist.

Als u de ontwikkelervaring voor niet-C#-projecten wilt verbeteren, kunt u in Functions verwijzen naar een versie-extensiebundel in uw host.json-projectbestand. Uitbreidingsbundels maken alle extensies beschikbaar voor uw app en verwijderen de kans op pakketcompatibiliteitsproblemen tussen extensies. Extensiebundels verwijderen ook de vereiste voor het installeren van de .NET Core 3.1 SDK en het bestand extensions.csproj.

Uitbreidingsbundels is de aanbevolen benadering voor andere functies dan C# uitgevoerde projecten, evenals C#-script. Voor deze projecten wordt de extensiebundelinstelling gegenereerd in het host.json-bestand tijdens de initialisatie. Als bundels niet zijn ingeschakeld, moet u het host.json-bestand van het project bijwerken.

De eenvoudigste manier om bindingextensies te installeren, is door extensiebundelsin te schakelen. Wanneer u bundels inschakelt, wordt er automatisch een vooraf gedefinieerde set extensiepakketten geïnstalleerd.

Als u extensiebundels wilt inschakelen, opent u het bestand host.json en werkt u de inhoud daarvan zodanig bij dat deze overeenkomt met de volgende code:

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[2.*, 3.0.0)"
    }
}

Zie Azure Functions bindingsextensies registreren voor meer informatie.

Er kunnen zich gevallen voordoen in een non-.NET project wanneer u geen uitbreidingsbundels kunt gebruiken, bijvoorbeeld wanneer u een specifieke versie van een extensie niet in de bundel moet richten. In deze zeldzame gevallen kunt u Core Tools gebruiken om de specifieke uitbreidingspakketten die vereist zijn voor uw project lokaal te installeren. Zie Extensies installeren voor meer informatie.

Lokale instellingen

Wanneer u in een functie-app in Azure uitvoert, worden instellingen die vereist zijn voor uw functies veilig opgeslagen in app-instellingen. Tijdens de lokale ontwikkeling worden deze instellingen toegevoegd aan het Values object in het bestand local.settings.json. Het bestand local.settings.json slaat ook instellingen op die worden gebruikt door lokale ontwikkelhulpprogramma's.

Omdat de local.settings.json geheimen kan bevatten, zoals verbindingsreeksen, moet u deze nooit opslaan in een externe opslagplaats. Zie het bestand Met lokale instellingen voor meer informatie over lokale instellingen.

Deze instellingen worden standaard niet automatisch gemigreerd wanneer het project wordt gepubliceerd naar Azure. Gebruik de --publish-local-settings optie wanneer u publiceert om ervoor te zorgen dat deze instellingen worden toegevoegd aan de functie-app in Azure. Waarden in de ConnectionStrings sectie worden nooit gepubliceerd.

De instellingen van de functie-app kunnen in uw code ook worden gelezen als omgevingsvariabelen. Raadpleeg het gedeelte Omgevingsvariabelen van deze taalspecifieke referentie-onderwerpen voor meer informatie:

Als er geen geldige opslag connection string is ingesteld AzureWebJobsStorage en de emulator niet wordt gebruikt, wordt het volgende foutbericht weergegeven:

Ontbrekende waarde voor AzureWebJobsStorage in local.settings.json. Dit is vereist voor alle andere triggers dan HTTP. U kunt 'func azure functionapp fetch-app-settings <functionAppName>' uitvoeren of een connection string opgeven in local.settings.json.

Uw opslagverbindingsreeksen ophalen

Zelfs wanneer u de Microsoft Azure Storage Emulator gebruikt voor ontwikkeling, wilt u mogelijk lokaal worden uitgevoerd met een werkelijke opslagverbinding. Ervan uitgaande dat u al een opslagaccount hebt gemaakt, kunt u op een van de volgende manieren een geldige opslag connection string krijgen:

  1. Zoek en selecteer opslagaccounts in de Azure Portal.

    Opslagaccounts selecteren in Azure Portal

  2. Selecteer uw opslagaccount, selecteer Toegangssleutels in Instellingen en kopieer vervolgens een van de verbindingsreekswaarden .

    Connection string kopiëren vanuit Azure Portal

Een functie maken

Als u een functie in een bestaand project wilt maken, voert u de volgende opdracht uit:

func new

Wanneer u in versie 3.x/2.x een func new sjabloon kiest in de standaardtaal van uw functie-app, wordt u gevraagd een sjabloon te kiezen. Vervolgens wordt u gevraagd een naam voor uw functie te kiezen. In versie 1.x moet u ook de taal kiezen.

U kunt ook de functienaam en sjabloon opgeven in de func new opdracht. In het volgende voorbeeld wordt de optie gebruikt om een HTTP-trigger met de --template naam MyHttpTriggerte maken:

func new --template "Http Trigger" --name MyHttpTrigger

In dit voorbeeld wordt een Queue Storage-trigger gemaakt met de naam MyQueueTrigger:

func new --template "Azure Queue Storage Trigger" --name MyQueueTrigger

Zie de func new opdracht voor meer informatie.

Functies lokaal uitvoeren

Als u een Functions-project wilt uitvoeren, voert u de Functions-host uit vanuit de hoofdmap van uw project. De host schakelt triggers in voor alle functies in het project. De start opdracht is afhankelijk van uw projecttaal.

func start

Notitie

Versie 1.x van de Functions-runtime vereist func host startin plaats daarvan. Zie Azure Functions Naslaginformatie over Core Tools voor meer informatie.

Wanneer de Functions-host wordt gestart, wordt de URL van door HTTP geactiveerde functies uitgevoerd, zoals in het volgende voorbeeld:

Found the following functions:
Host.Functions.MyHttpTrigger

Job host started
Http Function MyHttpTrigger: http://localhost:7071/api/MyHttpTrigger

Belangrijk

Wanneer u lokaal wordt uitgevoerd, wordt autorisatie niet afgedwongen voor HTTP-eindpunten. Dit betekent dat alle lokale HTTP-aanvragen worden verwerkt als authLevel = "anonymous". Zie het http-bindingsartikel voor meer informatie.

Testgegevens doorgeven aan een functie

Als u uw functies lokaal wilt testen, start u de Functions-host en roept u eindpunten aan op de lokale server met behulp van HTTP-aanvragen. Het eindpunt dat u aanroept, is afhankelijk van het type functie.

Notitie

Voorbeelden in dit onderwerp gebruiken het cURL-hulpprogramma om HTTP-aanvragen vanuit de terminal of een opdrachtprompt te verzenden. U kunt een hulpprogramma van uw keuze gebruiken om HTTP-aanvragen naar de lokale server te verzenden. Het cURL-hulpprogramma is standaard beschikbaar op Linux-systemen en Windows 10 build 17063 en hoger. In oudere Windows moet u eerst het cURL-hulpprogramma downloaden en installeren.

Zie Strategieën voor het testen van uw code in Azure Functions voor meer algemene informatie over testfuncties.

Door HTTP en webhook geactiveerde functies

U roept het volgende eindpunt aan om lokaal http- en webhook geactiveerde functies uit te voeren:

http://localhost:{port}/api/{function_name}

Zorg ervoor dat u dezelfde servernaam en poort gebruikt waarop de Functions-host luistert. U ziet dit in de uitvoer die wordt gegenereerd bij het starten van de functiehost. U kunt deze URL aanroepen met behulp van elke HTTP-methode die wordt ondersteund door de trigger.

De volgende cURL-opdracht activeert de MyHttpTrigger quickstart-functie van een GET-aanvraag met de naamparameter die is doorgegeven in de queryreeks.

curl --get http://localhost:7071/api/MyHttpTrigger?name=Azure%20Rocks

Het volgende voorbeeld is dezelfde functie die wordt aangeroepen vanuit een POST-aanvraag die de naam doorgeeft in de hoofdtekst van de aanvraag:

curl --request POST http://localhost:7071/api/MyHttpTrigger --data '{"name":"Azure Rocks"}'

U kunt GET-aanvragen doen vanuit een browser die gegevens doorgeeft in de querytekenreeks. Voor alle andere HTTP-methoden moet u cURL, Fiddler, Postman of een vergelijkbaar HTTP-testprogramma gebruiken dat POST-aanvragen ondersteunt.

Niet-HTTP-geactiveerde functies

Voor alle andere functies dan HTTP- en Event Grid-triggers kunt u uw functies lokaal testen met behulp van REST door een speciaal eindpunt aan te roepen dat een beheereindpunt wordt genoemd. Als u dit eindpunt aanroept met een HTTP POST-aanvraag op de lokale server, wordt de functie geactiveerd.

Als u door Event Grid geactiveerde functies lokaal wilt testen, raadpleegt u Lokaal testen met viewer-web-app.

U kunt eventueel testgegevens doorgeven aan de uitvoering in de hoofdtekst van de POST-aanvraag. Deze functionaliteit is vergelijkbaar met het tabblad Testen in de Azure Portal.

U roept het volgende beheerderseindpunt aan om niet-HTTP-functies te activeren:

http://localhost:{port}/admin/functions/{function_name}

Als u testgegevens wilt doorgeven aan het beheerderseindpunt van een functie, moet u de gegevens opgeven in de hoofdtekst van een POST-aanvraagbericht. De hoofdtekst van het bericht moet de volgende JSON-indeling hebben:

{
    "input": "<trigger_input>"
}

De <trigger_input> waarde bevat gegevens in een indeling die wordt verwacht door de functie. Het volgende cURL-voorbeeld is een POST naar een QueueTriggerJS functie. In dit geval is de invoer een tekenreeks die gelijk is aan het bericht dat naar verwachting in de wachtrij wordt gevonden.

curl --request POST -H "Content-Type:application/json" --data '{"input":"sample queue data"}' http://localhost:7071/admin/functions/QueueTrigger

Wanneer u een beheerderseindpunt aanroept in uw functie-app in Azure, moet u een toegangssleutel opgeven. Zie Functietoegangssleutels voor meer informatie.

Publiceren naar Azure

De Azure Functions Core Tools ondersteunt twee typen implementatie:

Implementatietype Opdracht Beschrijving
Projectbestanden func azure functionapp publish Hiermee worden functieprojectbestanden rechtstreeks in uw functie-app geïmplementeerd met behulp van zip-implementatie.
Kubernetes-cluster func kubernetes deploy Hiermee wordt uw Linux-functie-app geïmplementeerd als een aangepaste Docker-container in een Kubernetes-cluster.

Voordat u publiceert

Belangrijk

U moet de Azure CLI of Azure PowerShell lokaal geïnstalleerd om vanuit Core Tools naar Azure te kunnen publiceren.

Een projectmap kan taalspecifieke bestanden en mappen bevatten die niet mogen worden gepubliceerd. Uitgesloten items worden weergegeven in een .funcignore-bestand in de hoofdprojectmap.

U moet al een functie-app in uw Azure-abonnement hebben gemaakt, waarop u uw code gaat implementeren. Projecten waarvoor compilatie is vereist, moeten worden gebouwd zodat de binaire bestanden kunnen worden geïmplementeerd.

Zie Een functie-app maken voor serverloze uitvoering voor meer informatie over het maken van een functie-app vanaf de opdrachtprompt of het terminalvenster met behulp van de Azure CLI of Azure PowerShell.

Belangrijk

Wanneer u een functie-app maakt in de Azure Portal, wordt standaard versie 3.x van de Function-runtime gebruikt. Als u de functie-app versie 1.x van de runtime wilt gebruiken, volgt u de instructies in Uitvoeren op versie 1.x. U kunt de runtimeversie niet wijzigen voor een functie-app met bestaande functies.

Projectbestanden implementeren

Als u uw lokale code wilt publiceren in een functie-app in Azure, gebruikt u de opdracht publish:

func azure functionapp publish <FunctionAppName>

De volgende overwegingen zijn van toepassing op dit type implementatie:

  • Als u publiceert, worden bestaande bestanden in de functie-app overschreven.

  • Gebruik de --publish-local-settings optie om automatisch app-instellingen in uw functie-app te maken op basis van waarden in het bestand local.settings.json.

  • Er wordt een externe build uitgevoerd op gecompileerde projecten. Dit kan worden beheerd met behulp van de --no-build optie.

  • Uw project wordt zo geïmplementeerd dat het wordt uitgevoerd vanuit het implementatiepakket. Gebruik de --nozip optie om deze aanbevolen implementatiemodus uit te schakelen.

  • Java gebruikt Maven om uw lokale project te publiceren naar Azure. Gebruik in plaats daarvan de volgende opdracht om naar Azure te publiceren: mvn azure-functions:deploy. Azure-resources worden gemaakt tijdens de eerste implementatie.

  • Er wordt een foutbericht weergegeven als u probeert te publiceren naar een <FunctionAppName> abonnement dat niet bestaat in uw abonnement.

Kubernetes-cluster

Met Functions kunt u ook uw Functions-project definiëren dat moet worden uitgevoerd in een Docker-container. Gebruik de --docker optie om func init een Dockerfile te genereren voor uw specifieke taal. Dit bestand wordt vervolgens gebruikt bij het maken van een container om te implementeren. Zie Een functie maken in Linux met behulp van een aangepaste container voor meer informatie over het publiceren van een aangepaste container naar Azure zonder Kubernetes.

Core Tools kunnen worden gebruikt om uw project te implementeren als een aangepaste containerinstallatiekopieën in een Kubernetes-cluster.

Met de volgende opdracht wordt het Dockerfile gebruikt om een container te genereren en te implementeren in een Kubernetes-cluster.

func kubernetes deploy --name <DEPLOYMENT_NAME> --registry <REGISTRY_USERNAME> 

Zie Een functie-app implementeren in Kubernetes voor meer informatie.

Extensies installeren

Als u geen uitbreidingsbundels kunt gebruiken, kunt u Azure Functions Core Tools lokaal gebruiken om de specifieke uitbreidingspakketten te installeren die vereist zijn voor uw project.

Belangrijk

U kunt extensies niet expliciet installeren in een functie-app waarvoor uitbreidingsbundels zijn ingeschakeld. Verwijder eerst de extensionBundle sectie in host.json voordat u expliciet extensies installeert.

In de volgende items worden enkele redenen beschreven waarom u extensies mogelijk handmatig moet installeren:

  • U moet toegang krijgen tot een specifieke versie van een extensie die niet beschikbaar is in een bundel.
  • U moet toegang krijgen tot een aangepaste extensie die niet beschikbaar is in een bundel.
  • U moet toegang krijgen tot een specifieke combinatie van extensies die niet beschikbaar zijn in één bundel.

Wanneer u expliciet extensies installeert, wordt een .NET-projectbestand met de naam extensions.csproj toegevoegd aan de hoofdmap van uw project. Dit bestand definieert de set NuGet-pakketten die vereist zijn voor uw functies. Hoewel u met de NuGet-pakketverwijzingen in dit bestand kunt werken, kunt u met Core Tools extensies installeren zonder dit C#-projectbestand handmatig te hoeven bewerken.

Er zijn verschillende manieren om Core Tools te gebruiken om de vereiste extensies in uw lokale project te installeren.

Alle extensies installeren

Gebruik de volgende opdracht om automatisch alle uitbreidingspakketten toe te voegen die worden gebruikt door de bindingen in uw lokale project:

func extensions install

Met de opdracht wordt het bestand function.json gelezen om te zien welke pakketten u nodig hebt, installeert en herbouwt u het uitbreidingsproject (extensions.csproj). Er worden nieuwe bindingen toegevoegd in de huidige versie, maar bestaande bindingen worden niet bijgewerkt. Gebruik de --force optie om bestaande bindingen bij te werken naar de nieuwste versie wanneer u nieuwe bindingen installeert. Zie de func extensions install opdracht voor meer informatie.

Als uw functie-app bindingen of NuGet-pakketten gebruikt die Core Tools niet herkent, moet u de specifieke extensie handmatig installeren.

Een specifieke extensie installeren

Gebruik de volgende opdracht om een specifiek extensiepakket te installeren op een specifieke versie, in dit geval de Storage-extensie:

func extensions install --package Microsoft.Azure.WebJobs.Extensions.Storage --version 5.0.0

U kunt deze opdracht gebruiken om elk compatibel NuGet-pakket te installeren. Zie de func extensions install opdracht voor meer informatie.

Functies bewaken

De aanbevolen manier om de uitvoering van uw functies te bewaken, is door te integreren met Azure-toepassing Insights. U kunt ook uitvoeringslogboeken streamen naar uw lokale computer. Zie Azure Functions controleren voor meer informatie.

Application Insights-integratie

Application Insights-integratie moet zijn ingeschakeld wanneer u uw functie-app maakt in Azure. Als uw functie-app om een of andere reden niet is verbonden met een Application Insights-exemplaar, kunt u deze integratie eenvoudig uitvoeren in de Azure Portal. Zie Application Insights-integratie inschakelen voor meer informatie.

Streaminglogboeken inschakelen

U kunt een stroom logboekbestanden bekijken die door uw functies worden gegenereerd in een opdrachtregelsessie op uw lokale computer.

Ingebouwde logboekstreaming

Gebruik de func azure functionapp logstream opdracht om streaminglogboeken te ontvangen van een specifieke functie-app die wordt uitgevoerd in Azure, zoals in het volgende voorbeeld:

func azure functionapp logstream <FunctionAppName>

Notitie

De ingebouwde logboekstreaming is in Core Tools nog niet ingeschakeld voor functie-apps die worden uitgevoerd op Linux in een verbruiksabonnement. Voor deze hostingabonnementen moet u in plaats daarvan Live Metrics Stream gebruiken om de logboeken nagenoeg in realtime weer te geven.

Live Metrics Stream

U kunt de Live Metrics Stream voor uw functie-app in een nieuw browservenster weergeven door de optie --browser op te nemen, zoals in het volgende voorbeeld:

func azure functionapp logstream <FunctionAppName> --browser

Voor dit type streaminglogboeken moet Application Insights-integratie zijn ingeschakeld voor uw functie-app.

Volgende stappen

Meer informatie over het ontwikkelen, testen en publiceren van Azure-functies met behulp van Azure Functions kernhulpprogramma's. Azure Functions Core Tools wordt open source en gehost op GitHub. Als u een bug- of functieaanvraag wilt indienen, opent u een GitHub-probleem.