Uso de Azure Functions Core Tools

Azure Functions Core Tools le permite desarrollar y probar funciones en el equipo local desde el símbolo del sistema o terminal. Las funciones locales pueden conectarse a servicios de Azure en directo, y puede depurar sus funciones en el equipo local con el tiempo de ejecución de Functions completo. Incluso puede implementar una aplicación de función en su suscripción a Azure.

Importante

No mezcle el desarrollo local con el desarrollo del portal en la misma aplicación de función. Cuando cree y publique funciones desde un proyecto local, no debe intentar mantener o modificar el código del proyecto en el portal.

Para desarrollar funciones en el equipo local y publicarlas en Azure utilizando Core Tools siga estos pasos básicos:

Requisitos previos

Azure Functions Core Tools actualmente depende de la CLI de Azure o de Azure PowerShell para la autenticación con su cuenta de Azure. Esto significa que debe instalar alguna de estas herramientas para poder realizar la publicación en Azure desde Azure Functions Core Tools.

Versiones de Core Tools

Hay cuatro versiones de Azure Functions Core Tools. La versión que use depende del entorno de desarrollo local, la elección del lenguaje y el nivel de compatibilidad necesario.

Elija una pestaña de versión a continuación para obtener información sobre cada versión específica y para obtener instrucciones de instalación detalladas:

Admite la versión 4.x del runtime de Functions. Esta versión admite Windows, macOS y Linux, y emplea administradores de paquetes específicos de la plataforma o npm para la instalación. Esta es la versión recomendada del entorno de ejecución de Functions y Core Tools.

Solo puede instalar una versión de Core Tools en un equipo determinado. A menos que se indique lo contrario, los ejemplos de este artículo son para la versión 3.x.

Instalación de Azure Functions Core Tools

Azure Functions Core Tools incluye una versión del mismo tiempo de ejecución de Azure Functions que puede ejecutar en el equipo de desarrollo local. También proporciona comandos para crear funciones, conectarse a Azure e implementar proyectos de funciones.

A partir de la versión 2.x, Core Tools se ejecuta en Windows, macOS y Linux.

En los pasos siguientes se utiliza Windows Installer (MSI) para instalar Core Tools v4.x. Para más información sobre otros instaladores basados en paquetes, consulte el archivo Léame de Core Tools.

Descargue y ejecute el instalador de Core Tools según su versión de Windows:

Cambio de las versiones de Core Tools

Al cambiar a una versión diferente de Core Tools, debe usar el mismo administrador de paquetes que la instalación original para pasar a otra versión del paquete. Por ejemplo, si instaló la versión 2.x de Core Tools mediante npm, debe usar el siguiente comando para actualizar a la versión 3.x:

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

Si usó Windows instalador (MSI) para instalar Core Tools en Windows, debe desinstalar la versión anterior desde Agregar quitar programas antes de instalar otra versión.

Creación de un proyecto local de Functions

Un directorio de proyecto de Functions contiene los siguientes archivos y carpetas, independientemente del lenguaje:

Nombre de archivo Descripción
host.json Para obtener más información, consulte la referencia de host.json.
local.settings.json Configuración que usa Core Tools cuando se ejecuta localmente, incluida la configuración de la aplicación. Para obtener más información, consulte Configuración local.
.gitignore Impide que el archivo local.settings.json se publique accidentalmente en un repositorio de Git. Para obtener más información, consulte Configuración local.
.vscode\extensions.json Archivo de configuración que se usa al abrir la carpeta del proyecto en Visual Studio Code.

Para obtener más información sobre la carpeta del proyecto de Functions, consulte la Guía para desarrolladores de Azure Functions.

En la ventana de terminal o desde un símbolo del sistema, ejecute el siguiente comando para crear el proyecto y el repositorio de Git local:

func init MyFunctionProj

En este ejemplo se crea un proyecto de Functions en una carpeta nueva MyFunctionProj. Se le pedirá que elija un lenguaje predeterminado para el proyecto.

Tenga en cuenta lo siguiente al inicializar el proyecto:

  • Si no proporciona la opción --worker-runtime en el comando, se le pedirá que elija el lenguaje. Para obtener más información, consulte la referencia de func init.

  • Si no proporciona un nombre de proyecto, se inicializa la carpeta actual.

  • Si tiene previsto publicar el proyecto en un contenedor de Linux personalizado, use la opción --dockerfile para asegurarse de que se genere un Dockerfile para el proyecto. Para obtener más información, consulte Creación de una función en Linux con una imagen personalizada.

Es posible que deba tener en cuenta otros aspectos con algunos lenguajes:

  • De manera predeterminada, con la versión 2.x y las posteriores de Core Tools se crean proyectos de aplicación de funciones para el entorno de ejecución de .NET como proyectos de clase de C# (.csproj). La versión 3.x también admite la creación de funciones que se ejecuten en .NET 5.0 en un proceso aislado. Estos proyectos de C#, que se pueden usar con Visual Studio o con Visual Studio Code, se compilan durante la depuración y al publicar en Azure.

  • Use el parámetro --csx si desea trabajar localmente con archivos de script de C# (.csx). Estos son los mismos archivos que se obtienen al crear funciones en Azure Portal y cuando se usa la versión 1.x de Core Tools. Para obtener más información, consulte la referencia de func init.

Registro de las extensiones

A partir de la versión 2.x del entorno de ejecución, los desencadenadores y enlaces de Functions se implementan como paquetes (NuGet) con la extensión .NET. En el caso de proyectos de C# compilados, basta con que haga referencia a los paquetes de extensión NuGet de los desencadenadores y enlaces específicos que use. Los enlaces HTTP y los desencadenadores de temporizador no requieren extensiones.

Con el fin de mejorar la experiencia de desarrollo para proyectos que no son de C#, Functions le permite hacer referencia a un conjunto de extensiones con versión en su archivo de proyecto host.json. Los conjuntos de extensiones ponen todas las extensiones a disposición de su aplicación y eliminan la posibilidad de que haya problemas de compatibilidad de paquetes entre extensiones. Los conjuntos de extensiones también eliminan el requisito de instalar el SDK de .NET Core 3.1 y de tener que gestionar el archivo extensions.csproj.

Los conjuntos de extensiones son el enfoque recomendado para los proyectos de Functions que no se han compilado con C#. Para estos proyectos, el valor de conjunto de extensiones se genera en el archivo host.json durante la inicialización. Si este enfoque satisface sus necesidades, puede omitir toda esta sección.

Uso de conjuntos de extensiones

La forma más fácil de instalar extensiones de enlace es habilitar conjuntos de extensiones. Al habilitar agrupaciones, un conjunto predefinido de paquetes de extensiones se instala automáticamente.

Para habilitar las agrupaciones de extensiones, abra el archivo host.json y actualice su contenido para que coincida con el siguiente código:

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

Si el lenguaje lo admite, los conjuntos de extensiones ya deberían estar habilitados después de llamar a func init. Debe agregar los conjuntos de extensiones a host.json antes de agregar enlaces al archivo functions.json. Para obtener más información, consulte Register Azure Functions binding extensions (Registrar las extensiones de enlace de Azure Functions).

Instalación explícita de extensiones

En un proyecto que no sea de .NET, puede haber casos en los que no se puedan usar conjuntos de extensiones, por ejemplo, cuando necesite tener como destino una versión específica de una extensión que no esté en el conjunto. En estos casos excepcionales, puede usar Core Tools para instalar localmente los paquetes de extensión específicos que necesita el proyecto. Para obtener más información, consulte Instalación explícita de extensiones.

Configuración local

Cuando se ejecuta en una aplicación de funciones de Azure, la configuración requerida por las funciones se almacena de forma segura en la configuración de la aplicación. Durante el desarrollo local, esta configuración se agrega en su lugar al objeto Values del archivo local.settings.json. El archivo local.settings.json almacena también la configuración que usan las herramientas locales de desarrollo.

Dado que local.settings.json puede contener secretos, como cadenas de conexión, nunca debe almacenarlo en un repositorio remoto. Para más información sobre la configuración local, consulte Archivo de configuración local.

De manera predeterminada, estas opciones de configuración no se migran automáticamente cuando el proyecto se publica en Azure. Use la opción --publish-local-settings cuando publique para asegurarse de que la configuración se agregue a la aplicación de funciones en Azure. Los valores de la sección ConnectionStrings no se publican nunca.

Esta configuración de la aplicación de función también se puede leer en el código como variables de entorno. Para más información, consulte la sección Variables de entorno de estos temas de referencia específicos del lenguaje:

Cuando no se establece ninguna cadena de conexión de almacenamiento válida para AzureWebJobsStorage y no se usa el emulador, se muestra el siguiente mensaje de error:

Missing value for AzureWebJobsStorage in local.settings.json. This is required for all triggers other than HTTP. You can run 'func azure functionapp fetch-app-settings <functionAppName>' or specify a connection string in local.settings.json (Puede ejecutar "func azure functionapp fetch-app-settings" o especificar una cadena de conexión en local settings.json).

Obtención de las cadenas de conexión de almacenamiento

Aunque use el Emulador de Microsoft Azure Storage para tareas de desarrollo, le recomendamos ejecutarlo localmente con una conexión de almacenamiento real. Suponiendo que ya ha creado una cuenta de almacenamiento, puede obtener una cadena de conexión de almacenamiento válida de una de las maneras siguientes:

  1. En Azure Portal, busque y seleccione Cuentas de almacenamiento.

    Selección de cuentas de almacenamiento desde Azure Portal

  2. Seleccione la cuenta de almacenamiento, elija Claves de acceso en Configuración y, a continuación, copie uno de los valores de Cadena de conexión.

    Copia de una cadena de conexión desde Azure Portal

Creación de una función

Para crear una función en un proyecto existente, ejecute el siguiente comando:

func new

En la versión 3.x/2.x, cuando ejecute func new, se le pedirá que elija una plantilla en el lenguaje predeterminado de su aplicación de funciones. A continuación, se le pedirá que elija un nombre para la función. En la versión 1.x, también se le pedirá que elija el lenguaje.

También puede especificar el nombre y la plantilla de la función en el comando func new. En el siguiente ejemplo se usa la opción --template para crear un desencadenador HTTP denominado MyHttpTrigger:

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

En este ejemplo se crea un desencadenador de Queue Storage denominado MyQueueTrigger:

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

Para obtener más información, consulte el comando func new.

Ejecución local de funciones

Para ejecutar un proyecto de Functions, ejecute el host de Functions desde el directorio raíz del proyecto. El host habilita desencadenadores para todas las funciones del proyecto. El comando start varía en función del lenguaje del proyecto.

func start

Nota

En la versión 1.x del runtime de Functions, se requiere func host start. Para obtener más información, consulte Referencia de Azure Functions Core Tools.

Cuando se inicia el host de Functions, devuelve la dirección URL de las funciones desencadenadas por HTTP, como en el siguiente ejemplo:

Found the following functions:
Host.Functions.MyHttpTrigger

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

Importante

Cuando se ejecuta localmente, no se aplica la autorización para puntos de conexión HTTP. Esto significa que todas las solicitudes HTTP locales se tratan como authLevel = "anonymous". Para obtener más información, consulte el artículo sobre enlaces HTTP.

Paso de datos de prueba a una función

Para probar sus funciones localmente, inicie el host de Functions y llame a puntos de conexión del servidor local mediante solicitudes HTTP. El punto de conexión al que llama depende del tipo de función.

Nota

En los ejemplos de este tema se usa la herramienta cURL para enviar solicitudes HTTP desde el terminal o un símbolo del sistema. Puede usar una herramienta de su elección para enviar solicitudes HTTP al servidor local. La herramienta cURL está disponible de forma predeterminada en los sistemas basados en Linux y en la compilación 17063 de Windows 10, y en las posteriores. En las versiones anteriores de Windows, primero debe descargar e instalar la herramienta cURL.

Para obtener información más general sobre cómo probar funciones, consulte Estrategias para probar el código en Azure Functions.

Funciones desencadenadas por HTTP y webhook

Llama al siguiente punto de conexión para ejecutar de forma local funciones desencadenadas por HTTP y webhook:

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

Asegúrese de usar el mismo nombre del servidor y puerto en el que escucha el host de Functions. Puede ver esto en la salida generada al iniciar el host de Functions. Puede llamar a esta dirección URL mediante cualquier método HTTP admitido por el desencadenador.

El siguiente comando cURL desencadena la función de inicio rápido MyHttpTrigger desde una solicitud GET con el parámetro name transferido en la cadena de consulta.

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

En el siguiente ejemplo está la misma función a la que se llama desde una solicitud POST que transfiere name en el cuerpo de la solicitud:

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

Puede realizar solicitudes GET desde un explorador que transfiere datos en la cadena de consulta. Para todos los demás métodos HTTP, debe usar cURL, Fiddler, Postman o una herramienta de pruebas HTTP similar que admita solicitudes POST.

Funciones no desencadenadas por HTTP

Para todas las funciones que no sean desencadenadores HTTP y Event Grid, puede probar sus funciones localmente mediante REST llamando a un punto de conexión especial denominado punto de conexión de administración. Al llamar a este punto de conexión con una solicitud HTTP POST en el servidor local se desencadena esta función.

Para probar las funciones de Event Grid desencadenadas localmente, consulte Pruebas locales con la aplicación web de visor.

Opcionalmente, puede transferir los datos de prueba a la ejecución en el cuerpo de la solicitud POST. Esta funcionalidad es similar a la pestaña Prueba de Azure Portal.

Se llama al siguiente punto de conexión de administrador para desencadenar funciones ajenas a HTTP:

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

Para transferir datos de prueba al punto de conexión de administrador de una función, debe proporcionar los datos en el cuerpo de un mensaje de solicitud POST. Es necesario que el cuerpo del mensaje tenga el siguiente formato JSON:

{
    "input": "<trigger_input>"
}

El valor <trigger_input> contiene datos en un formato esperado por la función. El siguiente ejemplo de cURL es una solicitud POST dirigida a una función QueueTriggerJS. En este caso, la entrada es una cadena que equivale al mensaje que se espera encontrar en la cola.

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

Al llamar a un punto de conexión de administración en su aplicación de funciones de Azure, debe proporcionar una clave de acceso. Para obtener más información, consulte Claves de acceso de función.

Publicación en Azure

Azure Functions Core Tools admite tres tipos de implementación:

Tipo de implementación Get-Help Descripción
Archivos de proyecto func azure functionapp publish Implementa los archivos de proyecto de función directamente en su aplicación de funciones usando la implementación mediante ZIP.
Contenedor personalizado func deploy Implementa SU proyecto en una aplicación de funciones de Linux como contenedor de Docker personalizado.
Clúster de Kubernetes func kubernetes deploy Implementa la aplicación de funciones de Linux como contenedor de Docker de cliente en un clúster de Kubernetes.

Antes de publicar

Importante

Debe tener la CLI de Azure o Azure PowerShell instalados localmente para poder realizar la publicación en Azure desde Core Tools.

Una carpeta de proyecto puede contener archivos y directorios específicos del idioma que no deben publicarse. Los elementos excluidos se enumeran en un archivo .funcignore en la carpeta raíz del proyecto.

Tiene que tener creada una aplicación de funciones en su suscripción de Azure para implementar su código. Se deben compilar los proyectos que lo requieran para poder implementar los archivos binarios.

Para obtener información sobre cómo crear una aplicación de función desde el símbolo del sistema o la ventana de Terminal mediante la CLI de Azure o Azure PowerShell, vea Creación de una aplicación de función para la ejecución de código sin servidor.

Importante

Cuando se crea una aplicación de función en Azure Portal, se usa la versión 3.x del entorno de ejecución de Functions de forma predeterminada. Para hacer que la aplicación de función utilice la versión 1.x del entorno de ejecución, siga las instrucciones de Ejecución en la versión 1.x. No se puede cambiar la versión del entorno de ejecución de una aplicación de función que tiene funciones existentes.

Implementación de los archivos de proyecto

Para publicar su código local en una aplicación de funciones en Azure, use el comando publish:

func azure functionapp publish <FunctionAppName>

Tenga en cuenta los siguientes aspectos con relación a este tipo de implementación:

  • Al publicar, se sobrescriben los archivos existentes en la aplicación de funciones.

  • Use la opción --publish-local-settings para crear automáticamente la configuración de aplicación en su aplicación de funciones a partir de los valores del archivo local.settings.json.

  • En proyectos compilados se lleva a cabo una compilación remota. Esta acción se puede controlar usando la opción --no-build.

  • Su proyecto se implementa de tal forma que se ejecute desde el paquete de implementación. Para deshabilitar este modo de implementación recomendado, use la opción --nozip.

  • Java utiliza Maven para publicar el proyecto local en Azure. Para publicar proyectos en Azure, use en su lugar el siguiente comando: mvn azure-functions:deploy. Durante la implementación inicial se crean recursos de Azure.

  • Obtendrá un error si intenta publicarla en un <FunctionAppName> que no exista en su suscripción.

Clúster de Kubernetes

Functions también le permite definir su proyecto de la plataforma para que se ejecute en un contenedor de Docker. Use la opción --docker de func init con el fin de generar un Dockerfile para su lenguaje específico. Este archivo se usa posteriormente al crear un contenedor para implementar.

Core Tools se puede usar para implementar el proyecto como una imagen de contenedor personalizada en un clúster de Kubernetes. El comando necesario depende del tipo de escalador usado en el clúster.

El siguiente comando usa el Dockerfile para generar un contenedor e implementarlo en un clúster de Kubernetes.

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

Para obtener más información, consulte Implementación de una aplicación de funciones en Kubernetes.

Para obtener información sobre cómo publicar un contenedor personalizado en Azure sin Kubernetes, consulte Creación de una función en Linux con un contenedor personalizado.

Supervisión de funciones

La forma recomendada de supervisar la ejecución de sus funciones, es usar la integración con Azure Application Insights. También puede transmitir los registros de ejecución al equipo local. Para más información, consulte Supervisión de Azure Functions.

Integración de Application Insights

Al crear la aplicación de funciones en Azure, la integración de Application Insights debe estar habilitada. Si, por alguna razón, la aplicación de funciones no está conectada a una instancia de Application Insights, es fácil llevar a cabo esta integración en Azure Portal. Para más información, consulte Habilitación de la integración de Application Insights.

Habilitación de los registros de streaming

Puede ver una secuencia de archivos de registro que generan las funciones en una sesión de línea de comandos en el equipo local.

Streaming integrado de registros

Use el comando func azure functionapp logstream para empezar a recibir registros de streaming de una aplicación de funciones específica que se ejecuta en Azure, como en el ejemplo siguiente:

func azure functionapp logstream <FunctionAppName>

Nota

El streaming de registro integrado aún no se ha habilitado en Core Tools para las aplicaciones de funciones que se ejecutan en Linux en un plan de consumo. En estos planes de hospedaje, es preciso usar Live Metrics Stream para ver los registros casi en tiempo real.

Secuencia de métricas en directo

La información de Live Metrics Stream de una aplicación de funciones se puede ver en una ventana nueva del explorador. Para ello, hay que incluir la opción --browser, como se hace en el ejemplo siguiente:

func azure functionapp logstream <FunctionAppName> --browser

Este tipo de registros de streaming requiere que se habilite la integración de Application Insights para la aplicación de funciones.

Pasos siguientes

Aprenda a desarrollar, probar y publicar funciones de Azure Functions mediante el módulo de aprendizaje de Microsoft de Azure Functions Core Tools. Azure Functions Core Tools es de código abierto y se hospeda en GitHub.
Para notificar un error o realizar una solicitud de característica, abra un problema de GitHub.