Create your first PowerShell function in Azure (preview)

Note

PowerShell for Azure Functions is currently in preview. To receive important updates, subscribe to the Azure App Service announcements repository on GitHub.

This quickstart article walks you through how to create your first serverless PowerShell function using Visual Studio Code.

Azure Functions code in a Visual Studio Code project

You use the Azure Functions extension for Visual Studio Code to create a PowerShell function locally and then deployed it to a new function app in Azure. The extension is currently in preview. To learn more, see the Azure Functions extension for Visual Studio Code extension page.

Note

PowerShell support for the Azure Functions extension is currently disabled by default. Enabling PowerShell support is one of the steps in this article.

The following steps are supported on macOS, Windows, and Linux-based operating systems.

Prerequisites

To complete this quickstart:

If you don't have an Azure subscription, create a free account before you begin.

Install the Azure Function extension

The Azure Functions extension is used to create, test, and deploy functions to Azure.

  1. In Visual Studio Code, open Extensions and search for azure functions, or open this link in Visual Studio Code.

  2. Select Install to install the extension to Visual Studio Code.

    Install the extension for Azure Functions

  3. Restart Visual Studio Code and select the Azure icon on the Activity bar. You should see an Azure Functions area in the Side Bar.

    Azure Functions area in the Side Bar

Create a function app project

The Azure Functions project template in Visual Studio Code creates a project that can be published to a function app in Azure. A function app lets you group functions as a logical unit for management, deployment, and sharing of resources.

  1. In Visual Studio Code, select the Azure logo to display the Azure: Functions area, and then select the Create New Project icon.

    Create a function app project

  2. Choose a location for your Functions project workspace and choose Select.

    Note

    This article was designed to be completed outside of a workspace. In this case, do not select a project folder that is part of a workspace.

  3. Select the Powershell (preview) as the language for your function app project and then Azure Functions v2.

  4. Choose HTTP Trigger as the template for your first function, use HTTPTrigger as the function name, and choose an authorization level of Function.

    Note

    The Function authorization level requires a function key value when calling the function endpoint in Azure. This makes it harder for just anyone to call your function.

  5. When prompted, choose Add to workspace.

Visual Studio Code creates the PowerShell function app project in a new workspace. This project contains the host.json and local.settings.json configuration files, which apply to all function in the project. This PowerShell project is the same as a function app running in Azure.

Run the function locally

Azure Functions Core Tools integrates with Visual Studio Code to let you run and debug an Azure Functions project locally.

  1. To debug your function, insert a call to the Wait-Debugger cmdlet in the function code before you want to attach the debugger, then press F5 to start the function app project and attach the debugger. Output from Core Tools is displayed in the Terminal panel.

  2. In the Terminal panel, copy the URL endpoint of your HTTP-triggered function.

    Azure local output

  3. Append the query string ?name=<yourname> to this URL, and then use Invoke-RestMethod to execute the request, as follows:

    PS > Invoke-RestMethod -Method Get -Uri http://localhost:7071/api/HttpTrigger?name=PowerShell
    Hello PowerShell
    

    You can also execute the GET request from a browser.

    When you call the HttpTrigger endpoint without passing a name parameter either as a query parameter or in the body, the function returns a 500 error. When you review the code in run.ps1, you see that this error occurs by design.

  4. To stop debugging, press Shift + F5.

After you've verified that the function runs correctly on your local computer, it's time to publish the project to Azure.

Note

Remember to remove any calls to Wait-Debugger before you publish your functions to Azure.

Note

Creating a Function App in Azure will only prompt for Function App name. Set azureFunctions.advancedCreation to true to be prompted for all other values.

Publish the project to Azure

Visual Studio Code lets you publish your functions project directly to Azure. In the process, you create a function app and related resources in your Azure subscription. The function app provides an execution context for your functions. The project is packaged and deployed to the new function app in your Azure subscription.

This article assumes that you are creating a new function app.

Important

Publishing to an existing function app overwrites the content of that app in Azure.

  1. In the Azure: Functions area, select the Deploy to Function App icon.

    Function app settings

  2. If not signed-in, you are prompted to Sign in to Azure. You can also Create a free Azure account. After successful sign in from the browser, go back to Visual Studio Code.

  3. If you have multiple subscriptions, Select a subscription for the function app, then choose + Create New Function App in Azure.

  4. Type a globally unique name that identifies your function app and press Enter. Valid characters for a function app name are a-z, 0-9, and -.

  5. Choose + Create New Resource Group, type a resource group name, like myResourceGroup, and press enter. You can also use an existing resource group.

  6. Choose + Create New Storage Account, type a globally unique name of the new storage account used by your function app and press Enter. Storage account names must be between 3 and 24 characters in length and may contain numbers and lowercase letters only. You can also use an existing account.

  7. Choose a location in a region near you or near other services your functions access.

    When you press Enter, the following Azure resources are created in your subscription:

    • Resource group: Contains all of the created Azure resources. The name is based on your function app name.
    • Storage account: A standard Storage account is created with a unique name that is based on your function app name.
    • Hosting plan: A consumption plan is created in the West US region to host your serverless function app.
    • Function app: Your project is deployed to and runs in this new function app.

    A notification is displayed after your function app is created and the deployment package is applied. Select View Output in this notification to view the creation and deployment results, including the Azure resources that you created.

  8. Back in the Azure: Functions area, expand the new function app under your subscription. Expand Functions, right-click HttpTrigger, and then choose Copy function URL.

    Copy the function URL for the new HTTP trigger

Run the function in Azure

To verify that your published function runs in Azure, execute the following PowerShell command, replacing the Uri parameter with the URL of the HTTPTrigger function from the previous step. As before, append the query string &name=<yourname> to the URL, as in the following example:

PS > Invoke-WebRequest -Method Get -Uri "https://glengatest-vscode-powershell.azurewebsites.net/api/HttpTrigger?code=nrY05eZutfPqLo0som...&name=PowerShell"

StatusCode        : 200
StatusDescription : OK
Content           : Hello PowerShell
RawContent        : HTTP/1.1 200 OK
                    Content-Length: 16
                    Content-Type: text/plain; charset=utf-8
                    Date: Thu, 25 Apr 2019 16:01:22 GMT

                    Hello PowerShell
Forms             : {}
Headers           : {[Content-Length, 16], [Content-Type, text/plain; charset=utf-8], [Date, Thu, 25 Apr 2019 16:01:22 GMT]}
Images            : {}
InputFields       : {}
Links             : {}
ParsedHtml        : mshtml.HTMLDocumentClass
RawContentLength  : 16

Next steps

You have used Visual Studio Code to create a PowerShell function app with a simple HTTP-triggered function. You may also want to learn more about debugging a PowerShell function locally using the Azure Functions Core Tools. Check out the Azure Functions PowerShell developer guide.