Referência do desenvolvedor de scripts C# (.csx) do Azure Functions

  • Artigo

Este artigo é uma introdução ao desenvolvimento do Azure Functions usando o script C# ( .csx).

Importante

O script C# é suportado principalmente para fornecer uma experiência conveniente no portal para ajudá-lo a começar rapidamente a criar e executar funções C#. Para aplicativos com qualidade de produção, você deve desenvolver suas funções C# localmente como um projeto de biblioteca de classes C# compilado. Para saber como migrar um projeto de script C# para um projeto de biblioteca de classes C# (trabalhador isolado), consulte Converter um aplicativo de script C# em um projeto C#.

O Azure Functions permite desenvolver funções usando C# de uma das seguintes maneiras:

Tipo Processo de execução Extensão de código Ambiente de desenvolvimento Referência
Script C# no processo .csx Portal
Ferramentas do Core		 Este artigo
Biblioteca de classes C# (trabalhador isolado) Processo de trabalho isolado .cs Visual Studio
Visual Studio Code
Ferramentas do Core		 Funções de processo de trabalho isolado do .NET
Biblioteca de classes C# (em processo) em processo .cs Visual Studio
Visual Studio Code
Ferramentas do Core		 Funções da biblioteca de classes C# em processo

Como o .csx funciona

Fluxos de dados na sua função C# por meio de argumentos de método. Os nomes de argumentos são especificados em um arquivo function.json, e há nomes predefinidos para acessar itens como a função logger e os tokens de cancelamento.

O formato .csx permite escrever menos “texto clichê” e se concentrar apenas em escrever uma função C#. Em vez de encapsular tudo em um namespace e uma classe, basta definir um método Run. Inclua todas as referências de assembly e todos os namespaces no início do arquivo, como de costume.

Arquivos .csx do aplicativo de função são compilados quando uma instância é inicializada. Nessa etapa de compilação, coisas como a inicialização a frio podem levar mais tempo para funções de script C# em comparação a bibliotecas de classes do C#. Essa etapa de compilação também mostra porque funções do script C# são editáveis no portal do Azure enquanto objetos visuais do C# não são.

Estrutura de pastas

A estrutura de pastas para um projeto de script C# é semelhante ao exemplo seguinte:

FunctionsProject
 | - MyFirstFunction
 | | - run.csx
 | | - function.json
 | | - function.proj
 | - MySecondFunction
 | | - run.csx
 | | - function.json
 | | - function.proj
 | - host.json
 | - extensions.csproj
 | - bin

Há um arquivo host.json compartilhado que pode ser usado para configurar o aplicativo de funções. Cada função possui seu próprio arquivo de código (.csx) e arquivo de configuração de associação (function.json).

As extensões de associação necessárias na versão 2.x e versões posteriores do runtime do Functions são definidas no arquivo extensions.csproj, com os arquivos de biblioteca reais na pasta bin. Ao desenvolver localmente, você precisa registrar as extensões de associação. Ao desenvolver funções no portal do Azure, esse registro é feito para você.

Binding para argumentos

Dados de entrada ou de saída são associados a um parâmetro de função de script C# por meio da propriedade name no arquivo de configuração function.json. O exemplo a seguir mostra um arquivo function.json e arquivo run.csx para uma função disparada por fila. O parâmetro que recebe dados da mensagem da fila é chamado de myQueueItem porque esse é o valor de propriedade name.

{
    "disabled": false,
    "bindings": [
        {
            "type": "queueTrigger",
            "direction": "in",
            "name": "myQueueItem",
            "queueName": "myqueue-items",
            "connection":"MyStorageConnectionAppSetting"
        }
    ]
}

#r "Microsoft.WindowsAzure.Storage"

using Microsoft.Extensions.Logging;
using Microsoft.WindowsAzure.Storage.Queue;
using System;

public static void Run(CloudQueueMessage myQueueItem, ILogger log)
{
    log.LogInformation($"C# Queue trigger function processed: {myQueueItem.AsString}");
}

A instrução #r será explicada mais adiante neste artigo.

Tipos com suporte para associações

Cada associação tem seus próprios tipos com suporte. Por exemplo, um gatilho de blob pode ser usado com um parâmetro de cadeia de caracteres, um parâmetro POCO, um parâmetro CloudBlockBlob ou qualquer um dos vários outros tipos com suporte. O artigo de referência de associação para associações de blob lista todos os tipos de parâmetro com suporte para gatilhos de blob. Para obter mais informações, consulte Gatilhos e associações e os documentos de referência de associação para cada tipo de associação.

Dica

Se você planeja usar as ligações HTTP ou WebHook, planeje evitar o esgotamento de porta que pode ser causado pela instanciação incorreta do HttpClient. Para saber mais, confira Como gerenciar conexões no Azure Functions.

Referenciando classes personalizadas

Se precisa usar uma classe de objeto CRL básico (POCO) personalizada, você pode incluir a definição de classe dentro do mesmo arquivo ou colocá-la em um arquivo separado.

O exemplo a seguir mostra um run.csx que inclui uma definição de classe POCO.

public static void Run(string myBlob, out MyClass myQueueItem)
{
    log.Verbose($"C# Blob trigger function processed: {myBlob}");
    myQueueItem = new MyClass() { Id = "myid" };
}

public class MyClass
{
    public string Id { get; set; }
}

Uma classe POCO deve ter getter e setter definidos para cada propriedade.

Reutilização de código .csx

Você pode usar classes e métodos definidos em outros arquivos .csx no seu arquivo run.csx. Para fazer isso, use diretivas #load no arquivo run.csx. No exemplo a seguir, uma rotina de log chamada MyLogger é compartilhada em myLogger.csx e carregada em run.csx usando a diretiva #load:

Exemplo de run.csx:

#load "mylogger.csx"

using Microsoft.Extensions.Logging;

public static void Run(TimerInfo myTimer, ILogger log)
{
    log.LogInformation($"Log by run.csx: {DateTime.Now}");
    MyLogger(log, $"Log by MyLogger: {DateTime.Now}");
}

Exemplo de mylogger.csx:

public static void MyLogger(ILogger log, string logtext)
{
    log.LogInformation(logtext);
}

Usar um arquivo .csx compartilhado é um padrão comum quando você deseja tipar fortemente os argumentos transmitidos entre as funções usando um objeto POCO. No seguinte exemplo simplificado, um gatilho HTTP e um gatilho de fila compartilham um objeto POCO chamado Order para tipar fortemente os dados do pedido:

Exemplo run.csx para o gatilho HTTP:

#load "..\shared\order.csx"

using System.Net;
using Microsoft.Extensions.Logging;

public static async Task<HttpResponseMessage> Run(Order req, IAsyncCollector<Order> outputQueueItem, ILogger log)
{
    log.LogInformation("C# HTTP trigger function received an order.");
    log.LogInformation(req.ToString());
    log.LogInformation("Submitting to processing queue.");

    if (req.orderId == null)
    {
        return new HttpResponseMessage(HttpStatusCode.BadRequest);
    }
    else
    {
        await outputQueueItem.AddAsync(req);
        return new HttpResponseMessage(HttpStatusCode.OK);
    }
}

Exemplo run.csx para o gatilho da fila:

#load "..\shared\order.csx"

using System;
using Microsoft.Extensions.Logging;

public static void Run(Order myQueueItem, out Order outputQueueItem, ILogger log)
{
    log.LogInformation($"C# Queue trigger function processed order...");
    log.LogInformation(myQueueItem.ToString());

    outputQueueItem = myQueueItem;
}

Exemplo order.csx:

public class Order
{
    public string orderId {get; set; }
    public string custName {get; set;}
    public string custAddress {get; set;}
    public string custEmail {get; set;}
    public string cartId {get; set; }

    public override String ToString()
    {
        return "\n{\n\torderId : " + orderId +
                  "\n\tcustName : " + custName +
                  "\n\tcustAddress : " + custAddress +
                  "\n\tcustEmail : " + custEmail +
                  "\n\tcartId : " + cartId + "\n}";
    }
}

Você pode usar um caminho relativo com a diretiva #load :

  • #load "mylogger.csx" carrega um arquivo localizado na pasta de função.
  • #load "loadedfiles\mylogger.csx" carrega um arquivo localizado em uma pasta na pasta de função.
  • #load "..\shared\mylogger.csx" carrega um arquivo localizado em uma pasta no mesmo nível que a pasta de função, ou seja, diretamente em wwwroot.

A diretiva #load só funciona com arquivos .csx, não com arquivos .cs.

Associando ao valor de retorno do método

Use um valor retornado de um método em uma associação de saída, usando o nome $return em function.json.

{
    "name": "$return",
    "type": "blob",
    "direction": "out",
    "path": "output-container/{id}"
}

Aqui está o código de script C#, seguido por um exemplo de assíncrono:

public static string Run(WorkItem input, ILogger log)
{
    string json = string.Format("{{ \"id\": \"{0}\" }}", input.Id);
    log.LogInformation($"C# script processed queue message. Item={json}");
    return json;
}

public static Task<string> Run(WorkItem input, ILogger log)
{
    string json = string.Format("{{ \"id\": \"{0}\" }}", input.Id);
    log.LogInformation($"C# script processed queue message. Item={json}");
    return Task.FromResult(json);
}

Use o valor retornado apenas se uma execução de função com êxito sempre resultar em um valor retornado a ser passado para a associação de saída. Caso contrário, use ICollector ou IAsyncCollector, conforme mostrado na seção a seguir.

Gravando vários valores de saída

Para gravar vários valores em uma associação de saída ou se uma invocação de função com êxito não resultar em nada a ser passado para a associação de saída, use os tipos ICollector ou IAsyncCollector. Esses tipos são coleções somente gravação que são gravadas na associação de saída quando o método é concluído.

Este exemplo grava várias mensagens de fila na mesma fila usando ICollector:

public static void Run(ICollector<string> myQueue, ILogger log)
{
    myQueue.Add("Hello");
    myQueue.Add("World!");
}

Registro em log

A saída de log para logs de streaming em C#, inclue um argumento do tipo ILogger. Recomendamos nomeá-lo como log. Evite usar Console.Write no Azure Functions.

public static void Run(string myBlob, ILogger log)
{
    log.LogInformation($"C# Blob trigger function processed: {myBlob}");
}

Observação

Para saber mais sobre uma estrutura de registros mais recente que você pode usar em vez de TraceWriter, confira a documentação do ILogger no guia do desenvolvedor da biblioteca de classes .NET.

Registro de métricas personalizadas

Você pode usar o método de extensão LogMetric em ILogger para criar métricas personalizadas no Application Insights. Aqui está um exemplo de chamada de método:

logger.LogMetric("TestMetric", 1234);

Esse código é uma alternativa à chamada de TrackMetric usando a API do Application Insights para .NET.

Async

Para tornar uma função assíncrona, use a palavra-chave async e retorne um objeto Task.

public async static Task ProcessQueueMessageAsync(
        string blobName,
        Stream blobInput,
        Stream blobOutput)
{
    await blobInput.CopyToAsync(blobOutput, 4096);
}

Não é possível usar parâmetros out em funções assíncronas. Para associações de saída, use o valor de retorno de função ou um objeto coletor.

Tokens de cancelamento

Uma função pode aceitar um parâmetro CancellationToken que permite ao sistema operacional notificar seu código quando a função está prestes a ser encerrada. Você pode usar essa notificação para certificar-se de que a função não finalize inesperadamente de uma maneira que os dados fiquem em um estado inconsistente.

O exemplo a seguir mostra como verificar o encerramento da função iminente.

using System;
using System.IO;
using System.Threading;

public static void Run(
    string inputText,
    TextWriter logger,
    CancellationToken token)
{
    for (int i = 0; i < 100; i++)
    {
        if (token.IsCancellationRequested)
        {
            logger.WriteLine("Function was cancelled at iteration {0}", i);
            break;
        }
        Thread.Sleep(5000);
        logger.WriteLine("Normal processing for queue message={0}", inputText);
    }
}

Importando namespaces

Se precisar importar namespaces, você poderá fazer como geralmente faz, com a cláusula using .

using System.Net;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging;

public static Task<HttpResponseMessage> Run(HttpRequestMessage req, ILogger log)

Os seguintes namespaces são automaticamente importados e, portanto, são opcionais:

  • System
  • System.Collections.Generic
  • System.IO
  • System.Linq
  • System.Net.Http
  • System.Threading.Tasks
  • Microsoft.Azure.WebJobs
  • Microsoft.Azure.WebJobs.Host

Referenciando assemblies externos

Para assemblies da estrutura, adicione referências usando a diretiva #r "AssemblyName" .

#r "System.Web.Http"

using System.Net;
using System.Net.Http;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging;

public static Task<HttpResponseMessage> Run(HttpRequestMessage req, ILogger log)

Os seguintes assemblies são adicionados automaticamente pelo ambiente de hospedagem do Azure Functions:

  • mscorlib
  • System
  • System.Core
  • System.Xml
  • System.Net.Http
  • Microsoft.Azure.WebJobs
  • Microsoft.Azure.WebJobs.Host
  • Microsoft.Azure.WebJobs.Extensions
  • System.Web.Http
  • System.Net.Http.Formatting

Os seguintes assemblies podem ser referenciados por um nome simples, por versão de runtime:

  • Newtonsoft.Json
  • Microsoft.WindowsAzure.Storage*

*Removido na versão 4.x do runtime.

No código, os assemblies são referenciados como o seguinte exemplo:

#r "AssemblyName"

Referenciando assemblies personalizados

Para referenciar um assembly personalizado, use um assembly compartilhado ou particular:

  • Assemblies compartilhados são compartilhados entre todas as funções em um aplicativo de funções. Para fazer referência a um assembly personalizado, carregue o assembly em uma pasta nomeada como bin na pasta raiz (wwwroot) do seu aplicativo de funções.

  • Assemblies particulares fazem parte do contexto de determinada função e dão suporte ao sideload de versões diferentes. Os assemblies particulares devem ser carregados em uma pasta bin do diretório da função. Referencie os assemblies usando o nome de arquivo, como #r "MyAssembly.dll".

Para obter informações sobre como carregar arquivos na pasta da função, consulte a seção sobre gerenciamento de pacotes.

Diretórios inspecionados

O diretório que contém o arquivo de script da função é inspecionado automaticamente quanto às alterações nos assemblies. Para inspecionar alterações de assembly em outros diretórios, adicione-os à lista watchDirectories em host.json.

Usando pacotes NuGet

A forma como os pacotes de extensão de associação e outros pacotes NuGet são adicionados ao aplicativo de funções conta com a versão de destino do runtime do Functions.

Por padrão, o conjunto com suporte de pacotes NuGet de extensão do Functions são disponibilizados para seu aplicativo de funções de script C# usando pacotes de extensão. Para saber mais, confira Pacotes de extensão.

Se, por algum motivo, você não puder usar pacotes de extensão em seu projeto, também poderá usar o Azure Functions Core Tools para instalar extensões com base em associações definidas nos arquivos function.json em seu aplicativo. Ao usar o Core Tools para registrar extensões, use a opção --csx. Para saber mais, consulte Instalar extensões func.

Por padrão, o Core Tools lê os arquivos function.json e adiciona os pacotes necessários a um arquivo de projeto de biblioteca de classes C# extensions.csproj na raiz do sistema de arquivos do aplicativo de funções (wwwroot). Como o Core Tools usa dotnet.exe, você pode usá-lo para adicionar qualquer referência de pacote NuGet a esse arquivo de extensões. Durante a instalação, o Core Tools compila o extensions.csproj para instalar as bibliotecas necessárias. Aqui está um arquivo extensions.csproj de exemplo que adiciona uma referência ao Microsoft.ProjectOxford.Face versão 1.1.0:

<Project Sdk="Microsoft.NET.Sdk">
    <PropertyGroup>
        <TargetFramework>netstandard2.0</TargetFramework>
    </PropertyGroup>
    <ItemGroup>
        <PackageReference Include="Microsoft.ProjectOxford.Face" Version="1.1.0" />
    </ItemGroup>
</Project>

Observação

Para o script C# (.csx), você deve definir TargetFramework como um valor de netstandard2.0. Não há suporte para outras estruturas de destino, como net6.0.

Para usar um feed do NuGet personalizado, especifique o feed em um arquivo Nuget.Config na pasta raiz do aplicativo de funções. Para obter mais informações, consulte Configurando o comportamento do NuGet.

Se você estiver trabalhando em seu projeto apenas no portal, precisará criar manualmente o arquivo extensions.csproj ou um arquivo Nuget.Config diretamente no site. Para saber mais, consulte Instalar extensões manualmente.

Variáveis de ambiente

Para obter uma variável de ambiente ou um valor de configuração do aplicativo, use System.Environment.GetEnvironmentVariable, conforme mostrado no exemplo de código a seguir:

public static void Run(TimerInfo myTimer, ILogger log)
{
    log.LogInformation($"C# Timer trigger function executed at: {DateTime.Now}");
    log.LogInformation(GetEnvironmentVariable("AzureWebJobsStorage"));
    log.LogInformation(GetEnvironmentVariable("WEBSITE_SITE_NAME"));
}

public static string GetEnvironmentVariable(string name)
{
    return name + ": " +
        System.Environment.GetEnvironmentVariable(name, EnvironmentVariableTarget.Process);
}

Políticas de repetição

O Functions dá suporte a duas políticas de repetição internas. Para mais informações, consulte Políticas de repetição.

Esta é a política de repetição no arquivo function.json:

{
    "disabled": false,
    "bindings": [
        {
            ....
        }
    ],
    "retry": {
        "strategy": "fixedDelay",
        "maxRetryCount": 4,
        "delayInterval": "00:00:10"
    }
}
Propriedade function.json Descrição
estratégia Use fixedDelay.
maxRetryCount Obrigatórios. O número máximo de repetições permitidas por execução de função. -1 significa repetir indefinidamente.
delayInterval O atraso usado entre repetições. Especifique-a como uma cadeia de caracteres com o formato: HH:mm:ss.

Associando no runtime

No C#, e em outras linguagens .NET, você pode usar um padrão de associação obrigatório, em vez de associações declarativas em function.json. A associação obrigatória é útil quando os parâmetros de associação precisam ser calculado no runtime, em vez do tempo de design. Com esse padrão, é possível se vincular a associações de entrada e saída com suporte instantaneamente no código da função.

Defina uma associação obrigatória da seguinte maneira:

  • Não inclua uma entrada em function.json para as associações obrigatórias desejadas.
  • Passe um parâmetro de entrada Binder binder ou IBinder binder.
  • Use o padrão de C# a seguir para realizar a associação de dados.
using (var output = await binder.BindAsync<T>(new BindingTypeAttribute(...)))
{
    ...
}

BindingTypeAttribute é o atributo do .NET que define a associação, e T é um tipo de entrada ou saída com suporte nesse tipo de associação. T não pode ser um tipo de parâmetro out (como out JObject). Por exemplo, a associação de saída de tabela dos Aplicativos Móveis dá suporte a seis tipos de saída, mas você só pode usar ICollector<T> ou IAsyncCollector<T> para T.

Exemplo de atributo único

O código de exemplo a seguir cria uma associação de saída do Armazenamento de Blobs com o caminho do blob definido em tempo de execução e grava uma cadeia de caracteres no blob.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host.Bindings.Runtime;

public static async Task Run(string input, Binder binder)
{
    using (var writer = await binder.BindAsync<TextWriter>(new BlobAttribute("samples-output/path")))
    {
        writer.Write("Hello World!!");
    }
}

BlobAttribute define a associação de entrada ou saída do Armazenamento de Blobs e TextWriter é um tipo de associação de saída com suporte.

Exemplo de atributos múltiplos

O exemplo anterior obtém a configuração do aplicativo para a cadeia de conexão da conta de armazenamento principal do aplicativo de funções (que é AzureWebJobsStorage). É possível especificar uma configuração de aplicativo personalizada a ser usada para a conta de armazenamento adicionando StorageAccountAttribute e passando a matriz de atributos para BindAsync<T>(). Use um parâmetro Binder, não IBinder. Por exemplo:

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host.Bindings.Runtime;

public static async Task Run(string input, Binder binder)
{
    var attributes = new Attribute[]
    {
        new BlobAttribute("samples-output/path"),
        new StorageAccountAttribute("MyStorageAccount")
    };

    using (var writer = await binder.BindAsync<TextWriter>(attributes))
    {
        writer.Write("Hello World!");
    }
}

A tabela a seguir lista os atributos .NET para cada tipo de associação e os pacotes no qual eles são definidos.

Associação Atributo Adicionar referência
Azure Cosmos DB Microsoft.Azure.WebJobs.DocumentDBAttribute #r "Microsoft.Azure.WebJobs.Extensions.CosmosDB"
Hubs de Eventos Microsoft.Azure.WebJobs.ServiceBus.EventHubAttribute, Microsoft.Azure.WebJobs.ServiceBusAccountAttribute #r "Microsoft.Azure.Jobs.ServiceBus"
Aplicativos Móveis Microsoft.Azure.WebJobs.MobileTableAttribute #r "Microsoft.Azure.WebJobs.Extensions.MobileApps"
Hubs de Notificação Microsoft.Azure.WebJobs.NotificationHubAttribute #r "Microsoft.Azure.WebJobs.Extensions.NotificationHubs"
Barramento de Serviço Microsoft.Azure.WebJobs.ServiceBusAttribute, Microsoft.Azure.WebJobs.ServiceBusAccountAttribute #r "Microsoft.Azure.WebJobs.ServiceBus"
Fila de armazenamento Microsoft.Azure.WebJobs.QueueAttribute, Microsoft.Azure.WebJobs.StorageAccountAttribute
Armazenamento de blobs Microsoft.Azure.WebJobs.BlobAttribute, Microsoft.Azure.WebJobs.StorageAccountAttribute
Tabela de armazenamento Microsoft.Azure.WebJobs.TableAttribute, Microsoft.Azure.WebJobs.StorageAccountAttribute
Twilio Microsoft.Azure.WebJobs.TwilioSmsAttribute #r "Microsoft.Azure.WebJobs.Extensions.Twilio"

Converter um aplicativo com script C# em um projeto C#

A maneira mais fácil de converter um aplicativo de funções de script C# em um projeto compilado de biblioteca de classes C# é começar com um novo projeto. Você pode então, para cada função, migrar o código e a configuração de cada arquivo run.csx e function.json em uma pasta de funções para um único novo arquivo de código da biblioteca de classes .cs. Por exemplo, quando você tiver uma função de script C# chamada HelloWorld, terá dois arquivos: HelloWorld/run.csx e HelloWorld/function.json. Para essa função, você cria um arquivo de código chamado HelloWorld.cs em seu novo projeto de biblioteca de classes.

Se você estiver usando scripts C# para a edição do portal, poderá baixar o conteúdo do aplicativo em seu computador local. Escolha a opção Conteúdo do site em vez de Conteúdo e projeto do Visual Studio. Você não precisa gerar um projeto e não inclui as configurações do aplicativo no download. Você está definindo um novo ambiente de desenvolvimento e esse ambiente não deve ter as mesmas permissões que o ambiente do aplicativo hospedado.

Estas instruções mostram como converter funções de script C# (que são executadas em processo com o host do Functions) em funções de biblioteca de classes C# que são executadas em um processo de trabalho isolado.

  1. Conclua a seção Criar um projeto de aplicativo de funções no seu início rápido preferido:

  1. Se o código de script C# original incluir um arquivo extensions.csproj ou arquivos function.proj, copie as referências de pacote desses arquivos e adicione-as ao arquivo .csproj do novo projeto no mesmo ItemGroup com as dependências principais do Functions.

    Dica

    A conversão é uma boa oportunidade para atualizar para as versões mais recentes de suas dependências. Isso pode precisar de mais alterações no código em uma etapa posterior.

  2. Copie o conteúdo do arquivo original host.json para o arquivo host.json do novo projeto, exceto a seção extensionBundles (projetos C# compilados não usam pacotes de extensão e você deve adicionar explicitamente referências a todas as extensões usadas pelas suas funções). Ao mesclar arquivos host.json, lembre-se de que o esquema host.json tem controle de versão, com a maioria dos aplicativos usando a versão 2.0. Os conteúdos da seção extensions podem ser diferentes com base em versões específicas das extensões de associação usadas pelas suas funções. Configura artigos de referência de extensão individuais para saber como configurar corretamente o host.json para suas versões específicas.

  3. Para todos os arquivos compartilhados referenciados por uma diretiva #load, crie um novo arquivo .cs para cada uma dessas referências compartilhadas. É mais simples criar um novo arquivo .cs para cada definição de classe compartilhada. Se houver métodos estáticos sem uma classe, você precisará definir novas classes para esses métodos.

  4. Execute as seguintes tarefas para cada pasta <FUNCTION_NAME> em seu projeto original:

    1. Crie um novo arquivo chamado <FUNCTION_NAME>.cs, substituindo <FUNCTION_NAME> pelo nome da pasta que definiu sua função de script C#. Você pode criar um novo arquivo de código de função de um dos modelos específicos de gatilhos da seguinte forma:

      Usar o comando func new --name <FUNCTION_NAME> e escolhendo o modelo de gatilho correto no prompt.

    2. Copie as instruções using do seu arquivo run.csx e adicione-as ao novo arquivo. Você não precisa de diretivas #r.

    3. Para instruções #load em seu arquivo run.csx, adicione uma nova instrução using para o namespace que você usou no código compartilhado.

    4. No novo arquivo, defina uma classe para sua função no namespace que você está usando para o projeto.

    5. Crie um novo método denominado RunHandler ou algo semelhante. Esse novo método serve como o novo ponto de entrada para a função.

    6. Copie o método estático que representa sua função, bem como todas as funções que ele chama, de run.csx para sua nova classe como um segundo método. No novo método criado na etapa anterior, chame esse método estático. Essa etapa de indireção é útil para navegar por possíveis diferenças à medida que você continua a atualização. Você pode manter o método original exatamente igual e simplesmente controlar suas entradas do novo contexto. Talvez seja necessário criar parâmetros no novo método que serão passados para a chamada de método estático. Depois de confirmar que a migração funcionou corretamente, você poderá remover esse nível extra de indireção.

    7. Para cada associação no arquivo function.json, adicione o atributo correspondente ao novo método. Para encontrar rapidamente exemplos de associação, confira Adicionar associações manualmente com base em exemplos.

    8. Adicione todos os pacotes de extensão exigidos pelas associações ao seu projeto, caso ainda não tenha feito isso.

  5. Recrie as configurações de aplicativo exigidas pelo aplicativo na coleção Values do arquivo local.settings.json.

  6. Verifique se o projeto é executado localmente:

    Use func start para executar seu aplicativo na linha de comando. Para obter mais informações, confira Executar funções localmente.

  7. Publique seu projeto em um novo aplicativo de funções no Azure:

    Crie seus recursos do Azure e implante o projeto de código no Azure usando o comando func azure functionapp publish <APP_NAME>. Para obter mais informações, consulte Implantar arquivos de projeto.

Exemplo de conversão de função

Esta seção mostra um exemplo da migração para uma única função.

A função original no script C# tem dois arquivos:

  • HelloWorld/function.json
  • HelloWorld/run.csx

O conteúdo de HelloWorld/function.json é:

{
  "bindings": [
    {
      "authLevel": "FUNCTION",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    }
  ]
}

O conteúdo de HelloWorld/run.csx é:

#r "Newtonsoft.Json"

using System.Net;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Primitives;
using Newtonsoft.Json;

public static async Task<IActionResult> Run(HttpRequest req, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    string name = req.Query["name"];

    string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
    dynamic data = JsonConvert.DeserializeObject(requestBody);
    name = name ?? data?.name;

    string responseMessage = string.IsNullOrEmpty(name)
        ? "This HTTP triggered function executed successfully. Pass a name in the query string or in the request body for a personalized response."
                : $"Hello, {name}. This HTTP triggered function executed successfully.";

            return new OkObjectResult(responseMessage);
}

Depois de migrar para o modelo de trabalho isolado com a integração do ASP.NET Core, eles são substituídos por um único HelloWorld.cs:

using System.Net;
using Microsoft.Azure.Functions.Worker;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
using Microsoft.AspNetCore.Routing;
using Microsoft.Extensions.Primitives;
using Newtonsoft.Json;

namespace MyFunctionApp
{
    public class HelloWorld
    {
        private readonly ILogger _logger;

        public HelloWorld(ILoggerFactory loggerFactory)
        {
            _logger = loggerFactory.CreateLogger<HelloWorld>();
        }

        [Function("HelloWorld")]
        public async Task<IActionResult> RunHandler([HttpTrigger(AuthorizationLevel.Function, "get")] HttpRequest req)
        {
            return await Run(req, _logger);
        }

        // From run.csx
        public static async Task<IActionResult> Run(HttpRequest req, ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");

            string name = req.Query["name"];

            string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
            dynamic data = JsonConvert.DeserializeObject(requestBody);
            name = name ?? data?.name;

            string responseMessage = string.IsNullOrEmpty(name)
                ? "This HTTP triggered function executed successfully. Pass a name in the query string or in the request body for a personalized response."
                        : $"Hello, {name}. This HTTP triggered function executed successfully.";

            return new OkObjectResult(responseMessage);
        }
    }
}

Configuração de associação e exemplos

Esta seção contém referências e exemplos para definir gatilhos e associações no script C#.

Gatilho de blob

A tabela a seguir explica as propriedades de configuração de associação do script C# que você define no arquivo function.json.

Propriedade function.json Descrição
tipo Deve ser definido como blobTrigger. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
direction Deve ser definido como in. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
name O nome da variável que representa o blob no código de função.
path O contêiner para monitorar. Pode ser um padrão de nome de blob.
connection O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar às Blobs do Azure. Confira a opção Conexões.

O exemplo a seguir mostra uma definição de disparo de blob em um arquivo function.json e o código que usa a ligação. A função grava um log quando um blob é adicionado ou atualizado no samples-workitemssamples-workitems.

Aqui estão os dados de associação no arquivo function.json:

{
    "disabled": false,
    "bindings": [
        {
            "name": "myBlob",
            "type": "blobTrigger",
            "direction": "in",
            "path": "samples-workitems/{name}",
            "connection":"MyStorageAccountAppSetting"
        }
    ]
}

A cadeia de caracteres {name} no caminho do disparador de blob samples-workitems/{name} cria uma {name} que você pode usar no código de função para acessar o nome de arquivo do blob disparando. Para obter mais informações, confira Padrões de nomes do blob.

Aqui está o código script C# que associa a um Stream:

public static void Run(Stream myBlob, string name, ILogger log)
{
   log.LogInformation($"C# Blob trigger function Processed blob\n Name:{name} \n Size: {myBlob.Length} Bytes");
}

Aqui está o código script C# que associa a um CloudBlockBlob:

#r "Microsoft.WindowsAzure.Storage"

using Microsoft.WindowsAzure.Storage.Blob;

public static void Run(CloudBlockBlob myBlob, string name, ILogger log)
{
    log.LogInformation($"C# Blob trigger function Processed blob\n Name:{name}\nURI:{myBlob.StorageUri}");
}

Entrada de blob

A tabela a seguir explica as propriedades de configuração de associação do script C# que você define no arquivo function.json.

Propriedade function.json Descrição
tipo Deve ser definido como blob.
direction Deve ser definido como in.
name O nome da variável que representa o blob no código de função.
path O caminho para o blob.
connection O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar às Blobs do Azure. Confira a opção Conexões.

O exemplo a seguir mostra uma associação de entrada e de saída de blob em um arquivo function.json e um código script C# que usa as associações. A função faz uma cópia de um blob de texto. A função é disparada por uma mensagem da fila que contém o nome do blob para copiar. O novo blob é nomeado {originalblobname}-Copy.

No arquivo function.json, a queueTrigger propriedade de metadados é usada para especificar o nome do blob nas propriedades path:

{
  "bindings": [
    {
      "queueName": "myqueue-items",
      "connection": "MyStorageConnectionAppSetting",
      "name": "myQueueItem",
      "type": "queueTrigger",
      "direction": "in"
    },
    {
      "name": "myInputBlob",
      "type": "blob",
      "path": "samples-workitems/{queueTrigger}",
      "connection": "MyStorageConnectionAppSetting",
      "direction": "in"
    },
    {
      "name": "myOutputBlob",
      "type": "blob",
      "path": "samples-workitems/{queueTrigger}-Copy",
      "connection": "MyStorageConnectionAppSetting",
      "direction": "out"
    }
  ],
  "disabled": false
}

Aqui está o código de script do C#:

public static void Run(string myQueueItem, string myInputBlob, out string myOutputBlob, ILogger log)
{
    log.LogInformation($"C# Queue trigger function processed: {myQueueItem}");
    myOutputBlob = myInputBlob;
}

Saída de blob

A tabela a seguir explica as propriedades de configuração de associação do script C# que você define no arquivo function.json.

Propriedade function.json Descrição
tipo Deve ser definido como blob.
direction Deve ser definido como out.
name O nome da variável que representa o blob no código de função.
path O caminho para o blob.
connection O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar às Blobs do Azure. Confira a opção Conexões.

O exemplo a seguir mostra uma associação de entrada e de saída de blob em um arquivo function.json e um código script C# que usa as associações. A função faz uma cópia de um blob de texto. A função é disparada por uma mensagem da fila que contém o nome do blob para copiar. O novo blob é nomeado {originalblobname}-Copy.

No arquivo function.json, a queueTrigger propriedade de metadados é usada para especificar o nome do blob nas propriedades path:

{
  "bindings": [
    {
      "queueName": "myqueue-items",
      "connection": "MyStorageConnectionAppSetting",
      "name": "myQueueItem",
      "type": "queueTrigger",
      "direction": "in"
    },
    {
      "name": "myInputBlob",
      "type": "blob",
      "path": "samples-workitems/{queueTrigger}",
      "connection": "MyStorageConnectionAppSetting",
      "direction": "in"
    },
    {
      "name": "myOutputBlob",
      "type": "blob",
      "path": "samples-workitems/{queueTrigger}-Copy",
      "connection": "MyStorageConnectionAppSetting",
      "direction": "out"
    }
  ],
  "disabled": false
}

Aqui está o código de script do C#:

public static void Run(string myQueueItem, string myInputBlob, out string myOutputBlob, ILogger log)
{
    log.LogInformation($"C# Queue trigger function processed: {myQueueItem}");
    myOutputBlob = myInputBlob;
}

Gatilho do RabbitMQ

O exemplo a seguir mostra uma associação do gatilho RabbitMQ em um arquivo function.json e uma função de script C# que usa a associação. A função lê e registra a mensagem RabbitMQ.

Aqui estão os dados de associação no arquivo function.json:

{​​
    "bindings": [
        {​​
            "name": "myQueueItem",
            "type": "rabbitMQTrigger",
            "direction": "in",
            "queueName": "queue",
            "connectionStringSetting": "rabbitMQConnectionAppSetting"
        }​​
    ]
}​​

Aqui está o código de script do C#:

using System;

public static void Run(string myQueueItem, ILogger log)
{​​
    log.LogInformation($"C# Script RabbitMQ trigger function processed: {​​myQueueItem}​​");
}​​

Gatilho de Fila

A tabela a seguir explica as propriedades de configuração de associação do script C# que você define no arquivo function.json.

Propriedade function.json Descrição
tipo Deve ser definido como queueTrigger. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
direction Apenas no arquivo function.json. Deve ser definido como in. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
name O nome da variável que contém o conteúdo do item de fila no código da função.
queueName O nome da fila a ser controlada.
connection O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar às Filas do Azure. Confira a opção Conexões.

O exemplo a seguir mostra uma associação de gatilho de fila em um arquivo function.json e código de script C# que usa a associação. A função controla a myqueue-items fila e grava um log cada vez que um item de fila é processado.

Aqui está o arquivo function.json:

{
    "disabled": false,
    "bindings": [
        {
            "type": "queueTrigger",
            "direction": "in",
            "name": "myQueueItem",
            "queueName": "myqueue-items",
            "connection":"MyStorageConnectionAppSetting"
        }
    ]
}

Aqui está o código de script do C#:

#r "Microsoft.WindowsAzure.Storage"

using Microsoft.Extensions.Logging;
using Microsoft.WindowsAzure.Storage.Queue;
using System;

public static void Run(CloudQueueMessage myQueueItem, 
    DateTimeOffset expirationTime, 
    DateTimeOffset insertionTime, 
    DateTimeOffset nextVisibleTime,
    string queueTrigger,
    string id,
    string popReceipt,
    int dequeueCount,
    ILogger log)
{
    log.LogInformation($"C# Queue trigger function processed: {myQueueItem.AsString}\n" +
        $"queueTrigger={queueTrigger}\n" +
        $"expirationTime={expirationTime}\n" +
        $"insertionTime={insertionTime}\n" +
        $"nextVisibleTime={nextVisibleTime}\n" +
        $"id={id}\n" +
        $"popReceipt={popReceipt}\n" + 
        $"dequeueCount={dequeueCount}");
}

Saída da fila

A tabela a seguir explica as propriedades de configuração de associação do script C# que você define no arquivo function.json.

Propriedade function.json Descrição
tipo Deve ser definido como queue. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
direction Deve ser definido como out. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
name O nome da variável que representa a fila no código de função. Definido como $return para referenciar o valor de retorno da função.
queueName O nome da fila.
connection O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar às Filas do Azure. Confira a opção Conexões.

O exemplo a seguir mostra uma associação de gatilho de HTTP em um arquivo function.json e código de script C# que usa a associação. A função cria um item de fila com um conteúdo de objeto CustomQueueMessage para cada solicitação HTTP recebida.

Aqui está o arquivo function.json:

{
  "bindings": [
    {
      "type": "httpTrigger",
      "direction": "in",
      "authLevel": "function",
      "name": "input"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "$return",
      "queueName": "outqueue",
      "connection": "MyStorageConnectionAppSetting"
    }
  ]
}

Aqui está o código script C# que cria uma mensagem de fila única:

public class CustomQueueMessage
{
    public string PersonName { get; set; }
    public string Title { get; set; }
}

public static CustomQueueMessage Run(CustomQueueMessage input, ILogger log)
{
    return input;
}

Você pode enviar várias mensagens ao mesmo tempo usando um parâmetro ICollector ou IAsyncCollector. Aqui está o código de script C# que envia várias mensagens, uma com os dados da solicitação HTTP e outra com valores codificados:

public static void Run(
    CustomQueueMessage input, 
    ICollector<CustomQueueMessage> myQueueItems, 
    ILogger log)
{
    myQueueItems.Add(input);
    myQueueItems.Add(new CustomQueueMessage { PersonName = "You", Title = "None" });
}

Entrada de tabela

Esta seção descreve o suporte apenas para a versão da API de tabelas da extensão .

A tabela a seguir explica as propriedades de configuração de associação do script C# que você define no arquivo function.json.

Propriedade function.json Descrição
tipo Deve ser definido como table. Esse parâmetro é definido automaticamente quando você cria a associação no portal do Azure.
direction Deve ser definido como in. Esse parâmetro é definido automaticamente quando você cria a associação no portal do Azure.
name O nome da variável que representa a tabela ou entidade no código de função.
tableName O nome da tabela.
partitionKey Opcional. Chave de partição da entidade de tabela para leitura.
rowKey Opcional. Chave de linha da entidade de tabela para leitura. Não pode ser usado com take ou filter.
take Opcional. O número máximo de entidades a retornar. Não pode ser usado com rowKey.
filter Opcional. Uma expressão de filtro OData para as entidades retornarem da tabela. Não pode ser usado com rowKey.
connection O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar ao serviço de tabela. Confira a opção Conexões.

O exemplo a seguir mostra uma associação de entrada de tabela em um arquivo function.json e código de script C# que usa a associação. A função usa um gatilho de fila para ler uma linha da tabela.

O arquivo function.json especifica um partitionKey e um rowKey. O valor rowKey{queueTrigger} indica que a chave de linha foi obtida da cadeia de caracteres da mensagem da fila.

{
  "bindings": [
    {
      "queueName": "myqueue-items",
      "connection": "MyStorageConnectionAppSetting",
      "name": "myQueueItem",
      "type": "queueTrigger",
      "direction": "in"
    },
    {
      "name": "personEntity",
      "type": "table",
      "tableName": "Person",
      "partitionKey": "Test",
      "rowKey": "{queueTrigger}",
      "connection": "MyStorageConnectionAppSetting",
      "direction": "in"
    }
  ],
  "disabled": false
}

Aqui está o código de script do C#:

#r "Azure.Data.Tables"
using Microsoft.Extensions.Logging;
using Azure.Data.Tables;

public static void Run(string myQueueItem, Person personEntity, ILogger log)
{
    log.LogInformation($"C# Queue trigger function processed: {myQueueItem}");
    log.LogInformation($"Name in Person entity: {personEntity.Name}");
}

public class Person : ITableEntity
{
    public string Name { get; set; }

    public string PartitionKey { get; set; }
    public string RowKey { get; set; }
    public DateTimeOffset? Timestamp { get; set; }
    public ETag ETag { get; set; }
}

Saída da tabela

Esta seção descreve o suporte apenas para a versão da API de tabelas da extensão .

A tabela a seguir explica as propriedades de configuração de associação do script C# que você define no arquivo function.json.

Propriedade function.json Descrição
tipo Deve ser definido como table. Esse parâmetro é definido automaticamente quando você cria a associação no portal do Azure.
direction Deve ser definido como out. Esse parâmetro é definido automaticamente quando você cria a associação no portal do Azure.
name O nome da variável usada no código da função que representa a tabela ou entidade. Definido como $return para referenciar o valor de retorno da função.
tableName O nome da tabela na qual gravar.
partitionKey Chave de partição da entidade de tabela para gravar.
rowKey A chave de linha da entidade de tabela para gravar.
connection O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar ao serviço de tabela. Confira a opção Conexões.

O exemplo a seguir mostra uma associação de saída de tabela em um arquivo function.json e código script C# que usa a associação. A função escreve múltiplas entidades de tabela.

Aqui está o arquivo function.json:

{
  "bindings": [
    {
      "name": "input",
      "type": "manualTrigger",
      "direction": "in"
    },
    {
      "tableName": "Person",
      "connection": "MyStorageConnectionAppSetting",
      "name": "tableBinding",
      "type": "table",
      "direction": "out"
    }
  ],
  "disabled": false
}

Aqui está o código de script do C#:

public static void Run(string input, ICollector<Person> tableBinding, ILogger log)
{
    for (int i = 1; i < 10; i++)
        {
            log.LogInformation($"Adding Person entity {i}");
            tableBinding.Add(
                new Person() { 
                    PartitionKey = "Test", 
                    RowKey = i.ToString(), 
                    Name = "Name" + i.ToString() }
                );
        }

}

public class Person
{
    public string PartitionKey { get; set; }
    public string RowKey { get; set; }
    public string Name { get; set; }
}

Gatilho de temporizador

A tabela a seguir explica as propriedades de configuração de associação do script C# que você define no arquivo function.json.

Propriedade function.json Descrição
tipo Deve ser definido como timerTrigger. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
direction Deve ser definido como in. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
name O nome da variável que representa o objeto de temporizador no código de função.
schedule Um expressão CRON ou um valor TimeSpan. É possível usar um TimeSpan somente para um aplicativo de função executado em um Plano do Serviço de Aplicativo. Você pode colocar a expressão de agendamento em uma configuração de aplicativo e definir essa propriedade como o nome da configuração do aplicativo envolvido em sinais % , como neste exemplo: "%ScheduleAppSetting%".
runOnStartup Se true, a função será invocada quando o runtime for iniciado. Por exemplo, o runtime inicia quando o aplicativo de função desperta depois de ficar ocioso devido à inatividade. quando o aplicativo de funções é reiniciado devido a alterações de função e quando o aplicativo de funções é escalado horizontalmente. Use com caution.runOnStartup deve ser definido raramente ou nunca como true, principalmente em produção.
useMonitor Definido como true ou false para indicar se o agendamento deve ser monitorado. Agendar o monitoramento persiste as ocorrências de agendamento para ajudar a garantir que o agendamento seja mantido corretamente mesmo quando instâncias do aplicativo de função forem reiniciadas. Se não for definido explicitamente, o padrão será true para agendamentos que têm um intervalo de recorrência maior ou igual a 1 minuto. Para agendamentos que disparam mais de uma vez por minuto, o padrão é false.

O exemplo a seguir mostra uma associação de gatilho de temporizador em um arquivo function.json e uma função C# script que usa a associação. A função grava um log que indica se esta chamada de função deve-se a uma ocorrência de agendamento ausente. O objeto TimerInfo é passado para a função.

Aqui estão os dados de associação no arquivo function.json:

{
    "schedule": "0 */5 * * * *",
    "name": "myTimer",
    "type": "timerTrigger",
    "direction": "in"
}

Aqui está o código de script do C#:

public static void Run(TimerInfo myTimer, ILogger log)
{
    if (myTimer.IsPastDue)
    {
        log.LogInformation("Timer is running late!");
    }
    log.LogInformation($"C# Timer trigger function executed at: {DateTime.Now}" );  
}

Gatilho HTTP

A tabela a seguir explica as propriedades de configuração de gatilho que você define no arquivo function.json:

Propriedade function.json Descrição
tipo Obrigatório – deve ser definido como httpTrigger.
direction Obrigatório – deve ser definido como in.
name Obrigatório – o nome da variável usado no código da função da solicitação ou do corpo da solicitação.
authLevel Determina quais chaves, se houver, precisam estar presentes na solicitação para invocar a função. Para obter os valores com suporte, consulte Nível de autorização.
methods Uma matriz dos métodos HTTP para a qual a função responde. Se não for especificada, a função responderá a todos os métodos HTTP. Confira personalização do ponto de extremidade HTTP.
route Define o modelo da rota, controlando para quais URLs de solicitação sua função responde. O valor padrão se nenhum for fornecido será <functionname>. Para saber mais informações, confira personalização do ponto de extremidade HTTP.
webHookType Com suporte apenas na versão 1.x do runtime.

Configure o gatilho HTTP para atuar como um receptor de webhook para o provedor especificado. Para obter os valores com suporte, consulte Tipo de WebHook.

O exemplo a seguir mostra uma associação de gatilho em um arquivo function.json e uma função de script de C# que usa a associação. A função procura um parâmetro name na cadeia de consulta ou no corpo da solicitação HTTP.

Aqui está o arquivo function.json:

{
    "disabled": false,
    "bindings": [
        {
            "authLevel": "function",
            "name": "req",
            "type": "httpTrigger",
            "direction": "in",
            "methods": [
                "get",
                "post"
            ]
        },
        {
            "name": "$return",
            "type": "http",
            "direction": "out"
        }
    ]
}

Aqui está o código de script C# que associa a um HttpRequest:

#r "Newtonsoft.Json"

using System.Net;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Primitives;
using Newtonsoft.Json;

public static async Task<IActionResult> Run(HttpRequest req, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    string name = req.Query["name"];
    
    string requestBody = String.Empty;
    using (StreamReader streamReader =  new  StreamReader(req.Body))
    {
        requestBody = await streamReader.ReadToEndAsync();
    }
    dynamic data = JsonConvert.DeserializeObject(requestBody);
    name = name ?? data?.name;
    
    return name != null
        ? (ActionResult)new OkObjectResult($"Hello, {name}")
        : new BadRequestObjectResult("Please pass a name on the query string or in the request body");
}

Você pode vincular a um objeto personalizado em vez de HttpRequest. Esse objeto é criado a partir do corpo da solicitação e analisado como JSON. Da mesma forma, um tipo pode ser passado para a associação de saída da resposta HTTP e isso será retornado como o corpo da resposta, com um código de status 200.

using System.Net;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging;

public static string Run(Person person, ILogger log)
{   
    return person.Name != null
        ? (ActionResult)new OkObjectResult($"Hello, {person.Name}")
        : new BadRequestObjectResult("Please pass an instance of Person.");
}

public class Person {
     public string Name {get; set;}
}

Saída HTTP

A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json.

Propriedade Descrição
tipo Deve ser definido como http.
direction Deve ser definido como out.
name O nome da variável usada no código de função para a resposta, ou $return para usar o valor de retorno.

Gatilho dos Hubs de Eventos

A tabela a seguir explica as propriedades de configuração de gatilho que você define no arquivo function.json:

Propriedade function.json Descrição
tipo Deve ser definido como eventHubTrigger. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
direction Deve ser definido como in. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
name O nome da variável que representa o item de evento no código de função.
eventHubName Functions 2.x e posterior. O nome do hub de eventos. Quando o nome do hub de eventos também estiver presente na cadeia de conexão, esse valor substitui essa propriedade em runtime. Pode ser referenciado por meio das configurações de aplicativo%eventHubName%. Na versão 1.x, essa propriedade é denominada path.
consumerGroup É uma propriedade opcional que define o grupo de consumidores usado para assinar eventos no hub. Se omitido, o grupo de consumidores $Default será usado.
connection O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar aos Hubs de Eventos. Confira a opção Conexões.

O exemplo a seguir mostra uma associação de gatilho de Hubs de Eventos em um arquivo function.json e uma função de script C# que usa a associação. A função registra em log o corpo da mensagem do gatilho de Hubs de Eventos.

Os exemplos a seguir mostram dados de vinculação de Hubs de Eventos no arquivo function.json para o runtime do Functions versão 2.x e versões posteriores.

{
  "type": "eventHubTrigger",
  "name": "myEventHubMessage",
  "direction": "in",
  "eventHubName": "MyEventHub",
  "connection": "myEventHubReadConnectionAppSetting"
}

Aqui está o código de script do C#:

using System;

public static void Run(string myEventHubMessage, TraceWriter log)
{
    log.Info($"C# function triggered to process a message: {myEventHubMessage}");
}

Para obter acesso aos metadados no código da função, associe um objeto de EventData. Você também pode acessar as mesmas propriedades usando expressões de associação na assinatura do método. O exemplo a seguir mostra duas formas de obter os mesmos dados:

#r "Microsoft.Azure.EventHubs"

using System.Text;
using System;
using Microsoft.ServiceBus.Messaging;
using Microsoft.Azure.EventHubs;

public void Run(EventData myEventHubMessage,
    DateTime enqueuedTimeUtc,
    Int64 sequenceNumber,
    string offset,
    TraceWriter log)
{
    log.Info($"Event: {Encoding.UTF8.GetString(myEventHubMessage.Body)}");
    log.Info($"EnqueuedTimeUtc={myEventHubMessage.SystemProperties.EnqueuedTimeUtc}");
    log.Info($"SequenceNumber={myEventHubMessage.SystemProperties.SequenceNumber}");
    log.Info($"Offset={myEventHubMessage.SystemProperties.Offset}");

    // Metadata accessed by using binding expressions
    log.Info($"EnqueuedTimeUtc={enqueuedTimeUtc}");
    log.Info($"SequenceNumber={sequenceNumber}");
    log.Info($"Offset={offset}");
}

Para receber eventos em um lote, faça string ou EventData uma matriz:

public static void Run(string[] eventHubMessages, TraceWriter log)
{
    foreach (var message in eventHubMessages)
    {
        log.Info($"C# function triggered to process a message: {message}");
    }
}

Saída dos Hubs de Eventos

A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json.

Propriedade function.json Descrição
tipo Deve ser definido como eventHub.
direction Deve ser definido como out. Esse parâmetro é definido automaticamente quando você cria a associação no portal do Azure.
name É o nome da variável usada no código da função que representa o evento.
eventHubName Functions 2.x e posterior. O nome do hub de eventos. Quando o nome do hub de eventos também estiver presente na cadeia de conexão, esse valor substitui essa propriedade em runtime. No fFnctions 1. x, essa propriedade é denominada path.
connection O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar aos Hubs de Eventos. Para saber mais, confira Conexões.

O exemplo a seguir mostra uma associação de gatilho de hub de eventos em um arquivo function.json e uma função C# script que usa a associação. A função grava uma mensagem em um hub de eventos.

Os exemplos a seguir mostram dados de vinculação de Hubs de Eventos no arquivo function.json para o runtime do Functions versão 2.x e versões posteriores.

{
    "type": "eventHub",
    "name": "outputEventHubMessage",
    "eventHubName": "myeventhub",
    "connection": "MyEventHubSendAppSetting",
    "direction": "out"
}

Este é o código C# script que cria uma mensagem:

using System;
using Microsoft.Extensions.Logging;

public static void Run(TimerInfo myTimer, out string outputEventHubMessage, ILogger log)
{
    String msg = $"TimerTriggerCSharp1 executed at: {DateTime.Now}";
    log.LogInformation(msg);   
    outputEventHubMessage = msg;
}

Este é o código de script C# que cria várias mensagens:

public static void Run(TimerInfo myTimer, ICollector<string> outputEventHubMessage, ILogger log)
{
    string message = $"Message created at: {DateTime.Now}";
    log.LogInformation(message);
    outputEventHubMessage.Add("1 " + message);
    outputEventHubMessage.Add("2 " + message);
}

Gatilho da Grade de Eventos

A tabela a seguir explica as propriedades de configuração de associação do script C# que você define no arquivo function.json. Não há parâmetros ou propriedades do construtor para definir o atributo EventGridTrigger.

Propriedade function.json Descrição
tipo Obrigatório – deve ser definido como eventGridTrigger.
direction Obrigatório – deve ser definido como in.
name Obrigatório - o nome da variável usado no código de função para o parâmetro que recebe os dados de eventos.

O exemplo a seguir mostra um gatilho da Grade de Eventos definido no arquivo function.json.

Aqui estão os dados de associação no arquivo function.json:

{
  "bindings": [
    {
      "type": "eventGridTrigger",
      "name": "eventGridEvent",
      "direction": "in"
    }
  ],
  "disabled": false
}

Veja aqui um exemplo de uma função de script C# que usa um parâmetro de associação EventGridEvent:

#r "Azure.Messaging.EventGrid"
using Azure.Messaging.EventGrid;
using Microsoft.Extensions.Logging;

public static void Run(EventGridEvent eventGridEvent, ILogger log)
{
    log.LogInformation(eventGridEvent.Data.ToString());
}

Veja aqui um exemplo de uma função de script C# que usa um parâmetro de associação JObject:

#r "Newtonsoft.Json"

using Newtonsoft.Json;
using Newtonsoft.Json.Linq;

public static void Run(JObject eventGridEvent, TraceWriter log)
{
    log.Info(eventGridEvent.ToString(Formatting.Indented));
}

Saída da Grade de Eventos

A tabela a seguir explica as propriedades de configuração de associação do script C# que você define no arquivo function.json.

Propriedade function.json Descrição
tipo Deve ser definido como eventGrid.
direction Deve ser definido como out. Esse parâmetro é definido automaticamente quando você cria a associação no portal do Azure.
name É o nome da variável usada no código da função que representa o evento.
topicEndpointUri O nome de uma configuração de aplicativo que contém o URI para o tópico personalizado, como MyTopicEndpointUri.
topicKeySetting O nome de uma configuração de aplicativo que contém uma chave de acesso para o tópico personalizado.

O exemplo a seguir mostra os dados de associação de saída da Grade de Eventos no arquivo function.json.

{
    "type": "eventGrid",
    "name": "outputEvent",
    "topicEndpointUri": "MyEventGridTopicUriSetting",
    "topicKeySetting": "MyEventGridTopicKeySetting",
    "direction": "out"
}

Este é o código C# script que cria um evento:

#r "Microsoft.Azure.EventGrid"
using System;
using Microsoft.Azure.EventGrid.Models;
using Microsoft.Extensions.Logging;

public static void Run(TimerInfo myTimer, out EventGridEvent outputEvent, ILogger log)
{
    outputEvent = new EventGridEvent("message-id", "subject-name", "event-data", "event-type", DateTime.UtcNow, "1.0");
}

Este é o código de script C# que cria vários eventos:

#r "Microsoft.Azure.EventGrid"
using System;
using Microsoft.Azure.EventGrid.Models;
using Microsoft.Extensions.Logging;

public static void Run(TimerInfo myTimer, ICollector<EventGridEvent> outputEvent, ILogger log)
{
    outputEvent.Add(new EventGridEvent("message-id-1", "subject-name", "event-data", "event-type", DateTime.UtcNow, "1.0"));
    outputEvent.Add(new EventGridEvent("message-id-2", "subject-name", "event-data", "event-type", DateTime.UtcNow, "1.0"));
}

Gatilho do Barramento de Serviço

A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json.

Propriedade function.json Descrição
tipo Deve ser definido como serviceBusTrigger. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
direction Deve ser definido como in. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
name O nome da variável que representa a fila ou mensagem de tópico no código de função.
queueName Nome da fila a ser monitorada. Defina somente se for monitorar uma fila, não para um tópico.
topicName Nome do tópico a ser monitorado. Defina somente se for monitorar um tópico, não uma fila.
subscriptionName Nome da assinatura a ser monitorada. Defina somente se for monitorar um tópico, não uma fila.
connection O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar ao Barramento de Serviço. Confira a opção Conexões.
accessRights Direitos de acesso para a cadeia de caracteres de conexão. Os valores disponíveis são manage e listen. O padrão é manage, que indica que o connection tem a permissão manage. Se você usar uma cadeia de conexão que não tenha a permissão Gerenciar, defina accessRights como "escutar". Caso contrário, o runtime do Functions talvez falhe ao tentar executar operações que exigem o gerenciamento de direitos. No Azure Functions versão 2.x e posteriores, essa propriedade não está disponível porque a versão mais recente do SDK de Barramento de Serviço não oferece suporte para operações de gerenciamento.
isSessionsEnabled true se estiver se conectando a true assinatura com conhecimento de sessão. false caso contrário, que é o valor padrão.
autoComplete true quando o gatilho deve chamar concluído automaticamente após o processamento ou se o código da função chamará como concluído manualmente.

Definir como false só tem suporte no C#.

Se definido como true, o gatilho concluirá a mensagem automaticamente se a execução da função for concluída com êxito e abandonará a mensagem se ela falhar.
<br/Quando definido como false, você é responsável por chamar os métodos ServiceBusReceiver para concluir, colocar mensagem na fila de mensagens mortas ou desativar a mensagem, sessão ou lote. Se uma exceção for lançada (e nenhum dos métodos ServiceBusReceiver for chamado), o bloqueio permanecerá. Assim que o bloqueio expirar, a mensagem será colocada novamente na fila com o DeliveryCount incrementado e o bloqueio será renovado automaticamente.

Essa propriedade está disponível somente no Azure Functions 2.x e superior.

O exemplo a seguir mostra uma associação de gatilho de Barramento de Serviço em um arquivo function.json e uma função C# script que usa a associação. A função lê metadados de mensagem e registra uma mensagem de fila do Barramento de Serviço do Microsoft Azure.

Aqui estão os dados de associação no arquivo function.json:

{
"bindings": [
    {
    "queueName": "testqueue",
    "connection": "MyServiceBusConnection",
    "name": "myQueueItem",
    "type": "serviceBusTrigger",
    "direction": "in"
    }
],
"disabled": false
}

Aqui está o código de script do C#:

using System;

public static void Run(string myQueueItem,
    Int32 deliveryCount,
    DateTime enqueuedTimeUtc,
    string messageId,
    TraceWriter log)
{
    log.Info($"C# ServiceBus queue trigger function processed message: {myQueueItem}");

    log.Info($"EnqueuedTimeUtc={enqueuedTimeUtc}");
    log.Info($"DeliveryCount={deliveryCount}");
    log.Info($"MessageId={messageId}");
}

Saída do Barramento de Serviço

A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json.

Propriedade function.json Descrição
tipo Deve ser definido como serviceBus. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
direction Deve ser definido como out. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
name O nome da variável que representa a fila ou mensagem de tópico no código de função. Definido como "$return" para referenciar o valor de retorno da função.
queueName Nome da fila. Defina somente se for enviar mensagens da fila, não para um tópico.
topicName Nome do tópico. Defina somente se for enviar mensagens do tópico, não para uma fila.
connection O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar ao Barramento de Serviço. Confira a opção Conexões.
accessRights (somente v1) Direitos de acesso para a cadeia de caracteres de conexão. Os valores disponíveis são manage e listen. O padrão é manage, que indica que o connection tem a permissão manage. Se você usar uma cadeia de conexão que não tenha a permissão Gerenciar, defina accessRights como "escutar". Caso contrário, o runtime do Functions talvez falhe ao tentar executar operações que exigem o gerenciamento de direitos. No Azure Functions versão 2.x e posteriores, essa propriedade não está disponível porque a versão mais recente do SDK de Barramento de Serviço não oferece suporte para operações de gerenciamento.

O exemplo a seguir mostra uma associação de saída de Barramento de Serviço em um arquivo function.json e uma função script C# que usa a associação. A função usa um gatilho de timer para enviar uma mensagem da fila a cada 15 segundos.

Aqui estão os dados de associação no arquivo function.json:

{
    "bindings": [
        {
            "schedule": "0/15 * * * * *",
            "name": "myTimer",
            "runsOnStartup": true,
            "type": "timerTrigger",
            "direction": "in"
        },
        {
            "name": "outputSbQueue",
            "type": "serviceBus",
            "queueName": "testqueue",
            "connection": "MyServiceBusConnection",
            "direction": "out"
        }
    ],
    "disabled": false
}

Aqui está o código script C# que cria uma mensagem única:

public static void Run(TimerInfo myTimer, ILogger log, out string outputSbQueue)
{
    string message = $"Service Bus queue message created at: {DateTime.Now}";
    log.LogInformation(message); 
    outputSbQueue = message;
}

Este é o código de script C# que cria várias mensagens:

public static async Task Run(TimerInfo myTimer, ILogger log, IAsyncCollector<string> outputSbQueue)
{
    string message = $"Service Bus queue messages created at: {DateTime.Now}";
    log.LogInformation(message); 
    await outputSbQueue.AddAsync("1 " + message);
    await outputSbQueue.AddAsync("2 " + message);
}

Gatilho do Azure Cosmos DB v2

Esta seção descreve o suporte apenas para a versão 4.x+ da extensão .

A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json.

Propriedade function.json Descrição
tipo Deve ser definido como cosmosDBTrigger.
direction Deve ser definido como in. Esse parâmetro é definido automaticamente quando você cria o gatilho no portal do Azure.
name O nome da variável usado no código de função que representa a lista de documentos com alterações.
connection O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar à conta do Azure Cosmos DB que está sendo monitorado. Para mais informações, consulte as Conexões.
databaseName O nome do banco de dados do Azure Cosmos DB com o contêiner que está sendo monitorado.
containerName O nome do contêiner que está sendo monitorado.
leaseConnection (Opcional) O nome de uma configuração de aplicativo ou contêiner de configurações que especifica como se conectar à conta do Azure Cosmos DB que mantém o contêiner de concessão.

Quando não definido, o valor connection é usado. Esse parâmetro é definido automaticamente quando a associação é criada no portal. A cadeia de conexão do contêiner de concessões deve ter permissões de gravação.
leaseDatabaseName (Opcional) O nome do banco de dados que contém o contêiner usado para armazenar as concessões. Quando não definido, o valor da configuração databaseName é usado.
leaseContainerName (Opcional) O nome do contêiner usado para armazenar concessões. Quando não definido, o valor leases é usado.
createLeaseContainerIfNotExists (Opcional) Quando definido como true, a coleção de contêineres é criada automaticamente quando ela ainda não existe. O valor padrão é false. Ao usar identidades do Microsoft Entra, se você definir o valor como true, a criação de contêineres não será uma operação permitida e sua função não poderá ser iniciada.
leasesContainerThroughput (Opcional) Define o número de Unidades de Solicitação que será atribuído quando o contêiner de concessões for criado. Essa configuração é usada apenas quando createLeaseContainerIfNotExists está definido como true. Esse parâmetro é definido automaticamente quando a associação é criada usando o portal.
leaseContainerPrefix (Opcional) Quando definido, o valor é adicionado como um prefixo nas concessões criadas no contêiner de concessões desta função. O uso de um prefixo permite que dois Azure Functions separados compartilhem o mesmo contêiner de concessões usando prefixos diferentes.
feedPollDelay (Opcional) O horário (em milissegundos) do atraso entre a sondagem de uma partição quanto a novas alterações no feed, depois que todas as alterações atuais forem esvaziadas. O padrão é cinco mil milissegundos (ou cinco segundos).
leaseAcquireInterval (Opcional) Quando definido, ele define, em milissegundos, o intervalo para disparar uma tarefa para computar se as partições são distribuídas uniformemente entre as instâncias de host conhecidas. O padrão é 13000 (13 segundos).
leaseExpirationInterval (Opcional), Quando definido, ele define, em milissegundos, o intervalo para o qual a concessão é tomada em uma concessão que representa uma partição. Se a concessão não for renovada dentro deste intervalo, ela será expirada e a propriedade da partição será movida para outra instância. O padrão é 60000 (60 segundos).
leaseRenewInterval (Opcional) Quando definido, ele define, em milissegundos, o intervalo de renovação para todas as concessões para partições atualmente mantidas por uma instância. O padrão é 17000 (17 segundos).
maxItemsPerInvocation (Opcional) Quando definida, essa propriedade define o número máximo de itens recebidos por chamada de função. Se as operações no contêiner monitorado forem executadas por meio de procedimentos armazenados, o escopo da transação será preservado durante a leitura de itens do feed de alterações. Como resultado, o número de itens recebidos pode ser maior que o valor especificado para que os itens alterados pela mesma transação sejam retornados como parte de um lote atômico.
startFromBeginning (Opcional) Essa opção informa que o gatilho deve ler as alterações desde o início do histórico de alterações do contêiner, em vez de iniciar na hora atual. Ler do começo funciona apenas na primeira vez em que gatilho inicia, pois nas execuções subsequentes os pontos de verificação já estão armazenados. Configurar essa opção como true quando já houver concessões já criadas não terá nenhum efeito.
startFromTime (Opcional) Obtém ou define a data e a hora a partir da qual inicializar a operação de leitura do feed de alterações. O formato recomendado é o ISO 8601 com o designador UTC, como 2021-02-16T14:19:29Z. Isso é usado apenas para definir o estado inicial do gatilho. Depois que o gatilho tiver um estado de concessão, a alteração desse valor não terá nenhum efeito.
preferredLocations (Opcional) Define locais (regiões) preferenciais para contas de banco de dados com replicação geográfica no serviço Azure Cosmos DB. Os valores devem ser separados por vírgulas. Por exemplo, "Leste dos EUA, Centro-Sul dos EUA, Norte da Europa".

O exemplo a seguir mostra uma associação de gatilho do Azure Cosmos DB em um arquivo function.json e uma função de script C# que usa a associação. A função grava mensagens de log quando registros do Azure Cosmos DB são adicionados ou modificados.

Aqui estão os dados de associação no arquivo function.json:

{
    "type": "cosmosDBTrigger",
    "name": "documents",
    "direction": "in",
    "leaseContainerName": "leases",
    "connection": "<connection-app-setting>",
    "databaseName": "Tasks",
    "containerName": "Items",
    "createLeaseContainerIfNotExists": true
}

Aqui está o código de script do C#:

    using System;
    using System.Collections.Generic;
    using Microsoft.Extensions.Logging;

    // Customize the model with your own desired properties
    public class ToDoItem
    {
        public string id { get; set; }
        public string Description { get; set; }
    }

    public static void Run(IReadOnlyList<ToDoItem> documents, ILogger log)
    {
      log.LogInformation("Documents modified " + documents.Count);
      log.LogInformation("First document Id " + documents[0].id);
    }

Entrada do Azure Cosmos DB v2

Esta seção descreve o suporte apenas para a versão 4.x+ da extensão .

A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json.

Propriedade function.json Descrição
tipo Deve ser definido como cosmosDB.
direction Deve ser definido como in.
name O nome da variável usado no código de função que representa a lista de documentos com alterações.
connection O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar à conta do Azure Cosmos DB que está sendo monitorada. Para mais informações, consulte as Conexões.
databaseName O nome do banco de dados do Azure Cosmos DB com o contêiner que está sendo monitorado.
containerName O nome do contêiner que está sendo monitorado.
partitionKey Especifica o valor da chave de partição para a pesquisa. Pode incluir parâmetros de associação. É necessário para as pesquisas em coleções particionadas.
id A ID do documento a ser recuperado. Essa propriedade dá suporte a expressões de associação. Não defina ambas as propriedades id e sqlQuery. Se você não definir uma das duas, toda a coleção será recuperada.
sqlQuery Uma consulta SQL do Azure Cosmos DB usada para recuperar vários documentos. A propriedade dá suporte a associações em tempo de execução, como neste exemplo: SELECT * FROM c where c.departmentId = {departmentId}. Não defina ambas as propriedades id e sqlQuery. Se você não definir uma das duas, toda a coleção será recuperada.
preferredLocations (Opcional) Define locais (regiões) preferenciais para contas de banco de dados com replicação geográfica no serviço Azure Cosmos DB. Os valores devem ser separados por vírgulas. Por exemplo, East US,South Central US,North Europe.

Esta seção contém os seguintes exemplos:

Os exemplos de gatilho HTTP se referem a um tipo ToDoItem simples:

namespace CosmosDBSamplesV2
{
    public class ToDoItem
    {
        public string Id { get; set; }
        public string Description { get; set; }
    }
}

Gatilho da fila, pesquisar ID na cadeia de caracteres

O exemplo a seguir mostra uma associação de dados de entrada do Cosmos DB em um arquivo function.json e uma função script C# que usa a associação de dados. A função lê um documento único e atualiza o valor de texto do documento.

Aqui estão os dados de associação no arquivo function.json:

{
    "name": "inputDocument",
    "type": "cosmosDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "id" : "{queueTrigger}",
    "partitionKey": "{partition key value}",
    "connectionStringSetting": "MyAccount_COSMOSDB",
    "direction": "in"
}

Aqui está o código de script do C#:

    using System;

    // Change input document contents using Azure Cosmos DB input binding
    public static void Run(string myQueueItem, dynamic inputDocument)
    {
      inputDocument.text = "This has changed.";
    }

Gatilho da fila, obter vários documentos, usando SqlQuery

O exemplo a seguir mostra uma associação de dados de entrada do Cosmos DB em um arquivo function.json e uma função script C# que usa a associação de dados. A função recupera vários documentos especificados por uma consulta SQL usando um gatilho de fila para personalizar os parâmetros de consulta.

O gatilho de consulta fornece um parâmetro departmentId. Uma mensagem de consulta de { "departmentId" : "Finance" } retornará todos os registros ao departamento financeiro.

Aqui estão os dados de associação no arquivo function.json:

{
    "name": "documents",
    "type": "cosmosDB",
    "direction": "in",
    "databaseName": "MyDb",
    "collectionName": "MyCollection",
    "sqlQuery": "SELECT * from c where c.departmentId = {departmentId}",
    "connectionStringSetting": "CosmosDBConnection"
}

Aqui está o código de script do C#:

    public static void Run(QueuePayload myQueueItem, IEnumerable<dynamic> documents)
    {
        foreach (var doc in documents)
        {
            // operate on each document
        }
    }

    public class QueuePayload
    {
        public string departmentId { get; set; }
    }

Gatilho HTTP, pesquisar ID na cadeia de caracteres de consulta

O exemplo a seguir mostra uma função de script C# que recupera um único documento. A função é disparada por uma solicitação HTTP que usa uma cadeia de caracteres de consulta para especificar a ID e o valor da chave de partição a ser procurada. Essa ID e o valor da chave de partição são usados para recuperar um documento ToDoItem do banco de dados e da coleção especificados.

Aqui está o arquivo function.json:

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "type": "cosmosDB",
      "name": "toDoItem",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connectionStringSetting": "CosmosDBConnection",
      "direction": "in",
      "Id": "{Query.id}",
      "PartitionKey" : "{Query.partitionKeyValue}"
    }
  ],
  "disabled": false
}

Aqui está o código de script do C#:

using System.Net;
using Microsoft.Extensions.Logging;

public static HttpResponseMessage Run(HttpRequestMessage req, ToDoItem toDoItem, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    if (toDoItem == null)
    {
         log.LogInformation($"ToDo item not found");
    }
    else
    {
        log.LogInformation($"Found ToDo item, Description={toDoItem.Description}");
    }
    return req.CreateResponse(HttpStatusCode.OK);
}

Gatilho HTTP, pesquisar ID nos dados da rota

O exemplo a seguir mostra uma função de script C# que recupera um único documento. A função é disparada por uma solicitação HTTP que usa dados de rota para especificar a ID e o valor da chave de partição a ser procurada. Essa ID e o valor da chave de partição são usados para recuperar um documento ToDoItem do banco de dados e da coleção especificados.

Aqui está o arquivo function.json:

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": [
        "get",
        "post"
      ],
      "route":"todoitems/{partitionKeyValue}/{id}"
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "type": "cosmosDB",
      "name": "toDoItem",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connectionStringSetting": "CosmosDBConnection",
      "direction": "in",
      "id": "{id}",
      "partitionKey": "{partitionKeyValue}"
    }
  ],
  "disabled": false
}

Aqui está o código de script do C#:

using System.Net;
using Microsoft.Extensions.Logging;

public static HttpResponseMessage Run(HttpRequestMessage req, ToDoItem toDoItem, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    if (toDoItem == null)
    {
         log.LogInformation($"ToDo item not found");
    }
    else
    {
        log.LogInformation($"Found ToDo item, Description={toDoItem.Description}");
    }
    return req.CreateResponse(HttpStatusCode.OK);
}

Gatilho HTTP, obter vários documentos, usando SqlQuery

O exemplo a seguir mostra uma função de script C# que recupera uma lista de documentos. A função é disparada por uma solicitação HTTP. A consulta é especificada na propriedade do atributo SqlQuery.

Aqui está o arquivo function.json:

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "type": "cosmosDB",
      "name": "toDoItems",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connectionStringSetting": "CosmosDBConnection",
      "direction": "in",
      "sqlQuery": "SELECT top 2 * FROM c order by c._ts desc"
    }
  ],
  "disabled": false
}

Aqui está o código de script do C#:

using System.Net;
using Microsoft.Extensions.Logging;

public static HttpResponseMessage Run(HttpRequestMessage req, IEnumerable<ToDoItem> toDoItems, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    foreach (ToDoItem toDoItem in toDoItems)
    {
        log.LogInformation(toDoItem.Description);
    }
    return req.CreateResponse(HttpStatusCode.OK);
}

Gatilho HTTP, obter vários documentos, usando DocumentClient

O exemplo a seguir mostra uma função de script C# que recupera uma lista de documentos. A função é disparada por uma solicitação HTTP. O código usa uma instância DocumentClient fornecida pela associação do Azure Cosmos DB para ler uma lista de documentos. A instância DocumentClient também pode ser usada para as operações de gravação.

Aqui está o arquivo function.json:

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "type": "cosmosDB",
      "name": "client",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connectionStringSetting": "CosmosDBConnection",
      "direction": "inout"
    }
  ],
  "disabled": false
}

Aqui está o código de script do C#:

#r "Microsoft.Azure.Documents.Client"

using System.Net;
using Microsoft.Azure.Documents.Client;
using Microsoft.Azure.Documents.Linq;
using Microsoft.Extensions.Logging;

public static async Task<HttpResponseMessage> Run(HttpRequestMessage req, DocumentClient client, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    Uri collectionUri = UriFactory.CreateDocumentCollectionUri("ToDoItems", "Items");
    string searchterm = req.GetQueryNameValuePairs()
        .FirstOrDefault(q => string.Compare(q.Key, "searchterm", true) == 0)
        .Value;

    if (searchterm == null)
    {
        return req.CreateResponse(HttpStatusCode.NotFound);
    }

    log.LogInformation($"Searching for word: {searchterm} using Uri: {collectionUri.ToString()}");
    IDocumentQuery<ToDoItem> query = client.CreateDocumentQuery<ToDoItem>(collectionUri)
        .Where(p => p.Description.Contains(searchterm))
        .AsDocumentQuery();

    while (query.HasMoreResults)
    {
        foreach (ToDoItem result in await query.ExecuteNextAsync())
        {
            log.LogInformation(result.Description);
        }
    }
    return req.CreateResponse(HttpStatusCode.OK);
}

Saída do Azure Cosmos DB v2

Esta seção descreve o suporte apenas para a versão 4.x+ da extensão .

A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json.

Propriedade function.json Descrição
connection O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar à conta do Azure Cosmos DB que está sendo monitorado. Para mais informações, consulte as Conexões.
databaseName O nome do banco de dados do Azure Cosmos DB com o contêiner que está sendo monitorado.
containerName O nome do contêiner que está sendo monitorado.
createIfNotExists É um valor booliano para indicar se o contêiner será criado caso não exista. O padrão é false, porque os contêineres são criados com a taxa de transferência reservada, o que tem implicações de preço. Para saber mais, confira a página de preço.
partitionKey Quando createIfNotExists for true, ele definirá o caminho da chave de partição para o contêiner criado. Pode incluir parâmetros de associação.
containerThroughput Quando createIfNotExists for true, ele definirá a taxa de transferência do contêiner criado.
preferredLocations (Opcional) Define locais (regiões) preferenciais para contas de banco de dados com replicação geográfica no serviço Azure Cosmos DB. Os valores devem ser separados por vírgulas. Por exemplo, East US,South Central US,North Europe.

Esta seção contém os seguintes exemplos:

Gatilho da fila, gravar um documento

O exemplo a seguir mostra uma associação de saída do Azure Cosmos DB em um arquivo function.json e uma função de script C# que usa a associação. A função usa uma associação de entrada de fila para uma fila que recebe o JSON no seguinte formato:

{
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

A função cria documentos do Azure Cosmos DB no formato a seguir para cada registro:

{
    "id": "John Henry-123456",
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

Aqui estão os dados de associação no arquivo function.json:

{
    "name": "employeeDocument",
    "type": "cosmosDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "createIfNotExists": true,
    "connectionStringSetting": "MyAccount_COSMOSDB",
    "direction": "out"
}

Aqui está o código de script do C#:

    #r "Newtonsoft.Json"

    using Microsoft.Azure.WebJobs.Host;
    using Newtonsoft.Json.Linq;
    using Microsoft.Extensions.Logging;

    public static void Run(string myQueueItem, out object employeeDocument, ILogger log)
    {
      log.LogInformation($"C# Queue trigger function processed: {myQueueItem}");

      dynamic employee = JObject.Parse(myQueueItem);

      employeeDocument = new {
        id = employee.name + "-" + employee.employeeId,
        name = employee.name,
        employeeId = employee.employeeId,
        address = employee.address
      };
    }

Gatilho da fila, gravar documentos usando IAsyncCollector

Para criar vários documentos, você também pode associar a ICollector<T> ou IAsyncCollector<T>, sendo T um dos tipos com suporte.

Este exemplo se refere a um tipo ToDoItem simples:

namespace CosmosDBSamplesV2
{
    public class ToDoItem
    {
        public string id { get; set; }
        public string Description { get; set; }
    }
}

Aqui está o arquivo function.json:

{
  "bindings": [
    {
      "name": "toDoItemsIn",
      "type": "queueTrigger",
      "direction": "in",
      "queueName": "todoqueueforwritemulti",
      "connectionStringSetting": "AzureWebJobsStorage"
    },
    {
      "type": "cosmosDB",
      "name": "toDoItemsOut",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connectionStringSetting": "CosmosDBConnection",
      "direction": "out"
    }
  ],
  "disabled": false
}

Aqui está o código de script do C#:

using System;
using Microsoft.Extensions.Logging;

public static async Task Run(ToDoItem[] toDoItemsIn, IAsyncCollector<ToDoItem> toDoItemsOut, ILogger log)
{
    log.LogInformation($"C# Queue trigger function processed {toDoItemsIn?.Length} items");

    foreach (ToDoItem toDoItem in toDoItemsIn)
    {
        log.LogInformation($"Description={toDoItem.Description}");
        await toDoItemsOut.AddAsync(toDoItem);
    }
}

Gatilho do Azure Cosmos DB v1

O exemplo a seguir mostra uma associação de gatilho do Azure Cosmos DB em um arquivo function.json e uma função de script C# que usa a associação. A função grava mensagens de log quando registros do Azure Cosmos DB são modificados.

Aqui estão os dados de associação no arquivo function.json:

{
    "type": "cosmosDBTrigger",
    "name": "documents",
    "direction": "in",
    "leaseCollectionName": "leases",
    "connectionStringSetting": "<connection-app-setting>",
    "databaseName": "Tasks",
    "collectionName": "Items",
    "createLeaseCollectionIfNotExists": true
}

Aqui está o código de script do C#:

    #r "Microsoft.Azure.Documents.Client"
    
    using System;
    using Microsoft.Azure.Documents;
    using System.Collections.Generic;
    

    public static void Run(IReadOnlyList<Document> documents, TraceWriter log)
    {
        log.Info("Documents modified " + documents.Count);
        log.Info("First document Id " + documents[0].Id);
    }

Entrada do Azure Cosmos DB v1

Esta seção contém os seguintes exemplos:

Os exemplos de gatilho HTTP se referem a um tipo ToDoItem simples:

namespace CosmosDBSamplesV1
{
    public class ToDoItem
    {
        public string Id { get; set; }
        public string Description { get; set; }
    }
}

Gatilho da fila, pesquisar ID na cadeia de caracteres

O exemplo a seguir mostra uma associação de dados de entrada do Cosmos DB em um arquivo function.json e uma função script C# que usa a associação de dados. A função lê um documento único e atualiza o valor de texto do documento.

Aqui estão os dados de associação no arquivo function.json:

{
    "name": "inputDocument",
    "type": "documentDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "id" : "{queueTrigger}",
    "partitionKey": "{partition key value}",
    "connection": "MyAccount_COSMOSDB",
    "direction": "in"
}

Aqui está o código de script do C#:

    using System;

    // Change input document contents using Azure Cosmos DB input binding
    public static void Run(string myQueueItem, dynamic inputDocument)
    {
        inputDocument.text = "This has changed.";
    }

Gatilho da fila, obter vários documentos, usando SqlQuery

O exemplo a seguir mostra uma associação de dados de entrada do Cosmos DB em um arquivo function.json e uma função script C# que usa a associação de dados. A função recupera vários documentos especificados por uma consulta SQL usando um gatilho de fila para personalizar os parâmetros de consulta.

O gatilho de consulta fornece um parâmetro departmentId. Uma mensagem de consulta de { "departmentId" : "Finance" } retornará todos os registros ao departamento financeiro.

Aqui estão os dados de associação no arquivo function.json:

{
    "name": "documents",
    "type": "documentdb",
    "direction": "in",
    "databaseName": "MyDb",
    "collectionName": "MyCollection",
    "sqlQuery": "SELECT * from c where c.departmentId = {departmentId}",
    "connection": "CosmosDBConnection"
}

Aqui está o código de script do C#:

    public static void Run(QueuePayload myQueueItem, IEnumerable<dynamic> documents)
    {
        foreach (var doc in documents)
        {
            // operate on each document
        }
    }

    public class QueuePayload
    {
        public string departmentId { get; set; }
    }

Gatilho HTTP, pesquisar ID na cadeia de caracteres de consulta

O exemplo a seguir mostra uma função de script C# que recupera um único documento. A função é disparada por uma solicitação HTTP que usa uma cadeia de consulta para especificar a ID a ser pesquisada. Essa ID é usada para recuperar um documento ToDoItem no banco de dados e na coleção especificados.

Aqui está o arquivo function.json:

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "type": "documentDB",
      "name": "toDoItem",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connection": "CosmosDBConnection",
      "direction": "in",
      "Id": "{Query.id}"
    }
  ],
  "disabled": true
}

Aqui está o código de script do C#:

using System.Net;

public static HttpResponseMessage Run(HttpRequestMessage req, ToDoItem toDoItem, TraceWriter log)
{
    log.Info("C# HTTP trigger function processed a request.");

    if (toDoItem == null)
    {
        log.Info($"ToDo item not found");
    }
    else
    {
        log.Info($"Found ToDo item, Description={toDoItem.Description}");
    }
    return req.CreateResponse(HttpStatusCode.OK);
}

Gatilho HTTP, pesquisar ID nos dados da rota

O exemplo a seguir mostra uma função de script C# que recupera um único documento. A função é disparada por uma solicitação HTTP que usa os dados da rota para especificar a ID a pesquisar. Essa ID é usada para recuperar um documento ToDoItem no banco de dados e na coleção especificados.

Aqui está o arquivo function.json:

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": [
        "get",
        "post"
      ],
      "route":"todoitems/{id}"
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "type": "documentDB",
      "name": "toDoItem",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connection": "CosmosDBConnection",
      "direction": "in",
      "Id": "{id}"
    }
  ],
  "disabled": false
}

Aqui está o código de script do C#:

using System.Net;

public static HttpResponseMessage Run(HttpRequestMessage req, ToDoItem toDoItem, TraceWriter log)
{
    log.Info("C# HTTP trigger function processed a request.");

    if (toDoItem == null)
    {
        log.Info($"ToDo item not found");
    }
    else
    {
        log.Info($"Found ToDo item, Description={toDoItem.Description}");
    }
    return req.CreateResponse(HttpStatusCode.OK);
}

Gatilho HTTP, obter vários documentos, usando SqlQuery

O exemplo a seguir mostra uma função de script C# que recupera uma lista de documentos. A função é disparada por uma solicitação HTTP. A consulta é especificada na propriedade do atributo SqlQuery.

Aqui está o arquivo function.json:

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "type": "documentDB",
      "name": "toDoItems",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connection": "CosmosDBConnection",
      "direction": "in",
      "sqlQuery": "SELECT top 2 * FROM c order by c._ts desc"
    }
  ],
  "disabled": false
}

Aqui está o código de script do C#:

using System.Net;

public static HttpResponseMessage Run(HttpRequestMessage req, IEnumerable<ToDoItem> toDoItems, TraceWriter log)
{
    log.Info("C# HTTP trigger function processed a request.");

    foreach (ToDoItem toDoItem in toDoItems)
    {
        log.Info(toDoItem.Description);
    }
    return req.CreateResponse(HttpStatusCode.OK);
}

Gatilho HTTP, obter vários documentos, usando DocumentClient

O exemplo a seguir mostra uma função de script C# que recupera uma lista de documentos. A função é disparada por uma solicitação HTTP. O código usa uma instância DocumentClient fornecida pela associação do Azure Cosmos DB para ler uma lista de documentos. A instância DocumentClient também pode ser usada para as operações de gravação.

Aqui está o arquivo function.json:

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "type": "documentDB",
      "name": "client",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connection": "CosmosDBConnection",
      "direction": "inout"
    }
  ],
  "disabled": false
}

Aqui está o código de script do C#:

#r "Microsoft.Azure.Documents.Client"

using System.Net;
using Microsoft.Azure.Documents.Client;
using Microsoft.Azure.Documents.Linq;

public static async Task<HttpResponseMessage> Run(HttpRequestMessage req, DocumentClient client, TraceWriter log)
{
    log.Info("C# HTTP trigger function processed a request.");

    Uri collectionUri = UriFactory.CreateDocumentCollectionUri("ToDoItems", "Items");
    string searchterm = req.GetQueryNameValuePairs()
        .FirstOrDefault(q => string.Compare(q.Key, "searchterm", true) == 0)
        .Value;

    if (searchterm == null)
    {
        return req.CreateResponse(HttpStatusCode.NotFound);
    }

    log.Info($"Searching for word: {searchterm} using Uri: {collectionUri.ToString()}");
    IDocumentQuery<ToDoItem> query = client.CreateDocumentQuery<ToDoItem>(collectionUri)
        .Where(p => p.Description.Contains(searchterm))
        .AsDocumentQuery();

    while (query.HasMoreResults)
    {
        foreach (ToDoItem result in await query.ExecuteNextAsync())
        {
            log.Info(result.Description);
        }
    }
    return req.CreateResponse(HttpStatusCode.OK);
}

Saída do Azure Cosmos DB v1

Esta seção contém os seguintes exemplos:

  • Gatilho da fila, gravar um documento
  • Gatilho da fila, gravar documentos usando IAsyncCollector

Gatilho da fila, gravar um documento

O exemplo a seguir mostra uma associação de saída do Azure Cosmos DB em um arquivo function.json e uma função de script C# que usa a associação. A função usa uma associação de entrada de fila para uma fila que recebe o JSON no seguinte formato:

{
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

A função cria documentos do Azure Cosmos DB no formato a seguir para cada registro:

{
    "id": "John Henry-123456",
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

Aqui estão os dados de associação no arquivo function.json:

{
    "name": "employeeDocument",
    "type": "documentDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "createIfNotExists": true,
    "connection": "MyAccount_COSMOSDB",
    "direction": "out"
}

Aqui está o código de script do C#:

    #r "Newtonsoft.Json"

    using Microsoft.Azure.WebJobs.Host;
    using Newtonsoft.Json.Linq;

    public static void Run(string myQueueItem, out object employeeDocument, TraceWriter log)
    {
        log.Info($"C# Queue trigger function processed: {myQueueItem}");

        dynamic employee = JObject.Parse(myQueueItem);

        employeeDocument = new {
            id = employee.name + "-" + employee.employeeId,
            name = employee.name,
            employeeId = employee.employeeId,
            address = employee.address
        };
    }

Gatilho da fila, gravar documentos usando IAsyncCollector

Para criar vários documentos, você também pode associar a ICollector<T> ou IAsyncCollector<T>, sendo T um dos tipos com suporte.

Este exemplo se refere a um tipo ToDoItem simples:

namespace CosmosDBSamplesV1
{
    public class ToDoItem
    {
        public string Id { get; set; }
        public string Description { get; set; }
    }
}

Aqui está o arquivo function.json:

{
  "bindings": [
    {
      "name": "toDoItemsIn",
      "type": "queueTrigger",
      "direction": "in",
      "queueName": "todoqueueforwritemulti",
      "connection": "AzureWebJobsStorage"
    },
    {
      "type": "documentDB",
      "name": "toDoItemsOut",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connection": "CosmosDBConnection",
      "direction": "out"
    }
  ],
  "disabled": false
}

Aqui está o código de script do C#:

using System;

public static async Task Run(ToDoItem[] toDoItemsIn, IAsyncCollector<ToDoItem> toDoItemsOut, TraceWriter log)
{
    log.Info($"C# Queue trigger function processed {toDoItemsIn?.Length} items");

    foreach (ToDoItem toDoItem in toDoItemsIn)
    {
        log.Info($"Description={toDoItem.Description}");
        await toDoItemsOut.AddAsync(toDoItem);
    }
}

Gatilho do SQL do Azure

Há mais exemplos para o gatilho do SQL do Azure disponíveis no Repositório do GitHub.

O exemplo refere-se a uma classe ToDoItem e a uma tabela de banco de dados correspondente:

namespace AzureSQL.ToDo
{
    public class ToDoItem
    {
        public Guid Id { get; set; }
        public int? order { get; set; }
        public string title { get; set; }
        public string url { get; set; }
        public bool? completed { get; set; }
    }
}

CREATE TABLE dbo.ToDo (
    [Id] UNIQUEIDENTIFIER PRIMARY KEY,
    [order] INT NULL,
    [title] NVARCHAR(200) NOT NULL,
    [url] NVARCHAR(200) NOT NULL,
    [completed] BIT NOT NULL
);

O controle de alterações está habilitado no banco de dados e na tabela:

ALTER DATABASE [SampleDatabase]
SET CHANGE_TRACKING = ON
(CHANGE_RETENTION = 2 DAYS, AUTO_CLEANUP = ON);

ALTER TABLE [dbo].[ToDo]
ENABLE CHANGE_TRACKING;

O gatilho do SQL se vincula a uma IReadOnlyList<SqlChange<T>>, uma lista de objetos de SqlChange, cada um com duas propriedades:

  • Item: o item que foi alterado. O tipo do item deve seguir o esquema de tabela, conforme visto na classe ToDoItem.
  • Operação: um valor de enumeração SqlChangeOperation. Os valores possíveis são Insert, Update e Delete.

O exemplo a seguir mostra um gatilho SQL em um arquivo function.json e uma função de script C# que é invocada quando há alterações na tabela ToDo:

Veja a seguir os dados de associação no arquivo function.json:

{
    "name": "todoChanges",
    "type": "sqlTrigger",
    "direction": "in",
    "tableName": "dbo.ToDo",
    "connectionStringSetting": "SqlConnectionString"
}

A seguir está a função de script C#:

#r "Newtonsoft.Json"

using System.Net;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Primitives;
using Newtonsoft.Json;

public static void Run(IReadOnlyList<SqlChange<ToDoItem>> todoChanges, ILogger log)
{
    log.LogInformation($"C# SQL trigger function processed a request.");

    foreach (SqlChange<ToDoItem> change in todoChanges)
    {
        ToDoItem toDoItem = change.Item;
        log.LogInformation($"Change operation: {change.Operation}");
        log.LogInformation($"Id: {toDoItem.Id}, Title: {toDoItem.title}, Url: {toDoItem.url}, Completed: {toDoItem.completed}");
    }
}

Entrada do SQL do Azure

Mais exemplos para a associação de entrada do SQL do Azure estão disponíveis no repositório do GitHub.

Esta seção contém os seguintes exemplos:

Os exemplos se referem a uma classe ToDoItem e a uma tabela de banco de dados correspondente:

namespace AzureSQL.ToDo
{
    public class ToDoItem
    {
        public Guid Id { get; set; }
        public int? order { get; set; }
        public string title { get; set; }
        public string url { get; set; }
        public bool? completed { get; set; }
    }
}

CREATE TABLE dbo.ToDo (
    [Id] UNIQUEIDENTIFIER PRIMARY KEY,
    [order] INT NULL,
    [title] NVARCHAR(200) NOT NULL,
    [url] NVARCHAR(200) NOT NULL,
    [completed] BIT NOT NULL
);

Gatilho HTTP, obter linha por ID na cadeia de caracteres de consulta

O exemplo a seguir mostra uma associação de dados de entrada do SQL do Azure em um arquivo function.json e uma função script em C# que usa a associação de dados. A função é disparada por uma solicitação HTTP que usa uma cadeia de caracteres de consulta para especificar a ID. Essa ID é usada para recuperar um ToDoItem registro com a consulta especificada.

Observação

O parâmetro de cadeia de caracteres de consulta HTTP diferencia maiusculas de minúsculas.

Aqui estão os dados de associação no arquivo function.json:

{
    "authLevel": "anonymous",
    "type": "httpTrigger",
    "direction": "in",
    "name": "req",
    "methods": [
        "get"
    ]
},
{
    "type": "http",
    "direction": "out",
    "name": "res"
},
{
    "name": "todoItem",
    "type": "sql",
    "direction": "in",
    "commandText": "select [Id], [order], [title], [url], [completed] from dbo.ToDo where Id = @Id",
    "commandType": "Text",
    "parameters": "@Id = {Query.id}",
    "connectionStringSetting": "SqlConnectionString"
}

Aqui está o código de script do C#:

#r "Newtonsoft.Json"

using System.Net;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Primitives;
using Newtonsoft.Json;
using System.Collections.Generic;

public static IActionResult Run(HttpRequest req, ILogger log, IEnumerable<ToDoItem> todoItem)
{
    return new OkObjectResult(todoItem);
}

Gatilho HTTP, excluir linhas

O exemplo a seguir mostra uma associação de dados de entrada do SQL do Azure em um arquivo function.json e uma função script em C# que usa a associação de dados para executar um procedimento armazenado com entrada de dados do parâmetro de consulta da solicitação HTTP. Neste exemplo, o procedimento armazenado exclui um único registro ou todos os registros, dependendo do valor do parâmetro.

O procedimento armazenado dbo.DeleteToDo deve ser criado no banco de dados SQL.

CREATE PROCEDURE [dbo].[DeleteToDo]
    @Id NVARCHAR(100)
AS
    DECLARE @UID UNIQUEIDENTIFIER = TRY_CAST(@ID AS UNIQUEIDENTIFIER)
    IF @UId IS NOT NULL AND @Id != ''
    BEGIN
        DELETE FROM dbo.ToDo WHERE Id = @UID
    END
    ELSE
    BEGIN
        DELETE FROM dbo.ToDo WHERE @ID = ''
    END

    SELECT [Id], [order], [title], [url], [completed] FROM dbo.ToDo
GO

Aqui estão os dados de associação no arquivo function.json:

{
    "authLevel": "anonymous",
    "type": "httpTrigger",
    "direction": "in",
    "name": "req",
    "methods": [
        "get"
    ]
},
{
    "type": "http",
    "direction": "out",
    "name": "res"
},
{
    "name": "todoItems",
    "type": "sql",
    "direction": "in",
    "commandText": "DeleteToDo",
    "commandType": "StoredProcedure",
    "parameters": "@Id = {Query.id}",
    "connectionStringSetting": "SqlConnectionString"
}

using System;
using System.Collections.Generic;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Logging;

namespace AzureSQL.ToDo
{
    public static class DeleteToDo
    {
        // delete all items or a specific item from querystring
        // returns remaining items
        // uses input binding with a stored procedure DeleteToDo to delete items and return remaining items
        [FunctionName("DeleteToDo")]
        public static IActionResult Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "delete", Route = "DeleteFunction")] HttpRequest req,
            ILogger log,
            [Sql(commandText: "DeleteToDo", commandType: System.Data.CommandType.StoredProcedure, 
                parameters: "@Id={Query.id}", connectionStringSetting: "SqlConnectionString")] 
                IEnumerable<ToDoItem> toDoItems)
        {
            return new OkObjectResult(toDoItems);
        }
    }
}

Aqui está o código de script do C#:

#r "Newtonsoft.Json"

using System.Net;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Primitives;
using Newtonsoft.Json;
using System.Collections.Generic;

public static IActionResult Run(HttpRequest req, ILogger log, IEnumerable<ToDoItem> todoItems)
{
    return new OkObjectResult(todoItems);
}

Saída do SQL do Azure

Mais exemplos para a associação de saída SQL do Azure estão disponíveis no repositório do GitHub.

Esta seção contém os seguintes exemplos:

Os exemplos se referem a uma classe ToDoItem e a uma tabela de banco de dados correspondente:

namespace AzureSQL.ToDo
{
    public class ToDoItem
    {
        public Guid Id { get; set; }
        public int? order { get; set; }
        public string title { get; set; }
        public string url { get; set; }
        public bool? completed { get; set; }
    }
}

CREATE TABLE dbo.ToDo (
    [Id] UNIQUEIDENTIFIER PRIMARY KEY,
    [order] INT NULL,
    [title] NVARCHAR(200) NOT NULL,
    [url] NVARCHAR(200) NOT NULL,
    [completed] BIT NOT NULL
);

Gatilho HTTP, gravar registros em uma tabela

O exemplo a seguir mostra uma associação de saída SQL em um arquivo function.json e uma função de script C# que adiciona registros a uma tabela, usando dados fornecidos em uma solicitação HTTP POST como um corpo JSON.

Veja a seguir os dados de associação no arquivo function.json:

{
    "authLevel": "anonymous",
    "type": "httpTrigger",
    "direction": "in",
    "name": "req",
    "methods": [
        "post"
    ]
},
{
    "type": "http",
    "direction": "out",
    "name": "res"
},
{
    "name": "todoItem",
    "type": "sql",
    "direction": "out",
    "commandText": "dbo.ToDo",
    "connectionStringSetting": "SqlConnectionString"
}

Veja a seguir o código de script C# de exemplo:

#r "Newtonsoft.Json"

using System.Net;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Primitives;
using Newtonsoft.Json;

public static IActionResult Run(HttpRequest req, ILogger log, out ToDoItem todoItem)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    string requestBody = new StreamReader(req.Body).ReadToEnd();
    todoItem = JsonConvert.DeserializeObject<ToDoItem>(requestBody);

    return new OkObjectResult(todoItem);
}

Gatilho HTTP, gravação em duas tabelas

O exemplo a seguir mostra uma associação de saída SQL em um arquivo function.json e uma função de script C# que adiciona registros a um banco de dados em duas tabelas diferentes (dbo.ToDo e dbo.RequestLog), usando dados fornecidos em uma solicitação HTTP POST como um corpo JSON e várias associações de saída.

A segunda tabela, dbo.RequestLog, corresponde à seguinte definição:

CREATE TABLE dbo.RequestLog (
    Id int identity(1,1) primary key,
    RequestTimeStamp datetime2 not null,
    ItemCount int not null
)

Veja a seguir os dados de associação no arquivo function.json:

{
    "authLevel": "anonymous",
    "type": "httpTrigger",
    "direction": "in",
    "name": "req",
    "methods": [
        "post"
    ]
},
{
    "type": "http",
    "direction": "out",
    "name": "res"
},
{
    "name": "todoItem",
    "type": "sql",
    "direction": "out",
    "commandText": "dbo.ToDo",
    "connectionStringSetting": "SqlConnectionString"
},
{
    "name": "requestLog",
    "type": "sql",
    "direction": "out",
    "commandText": "dbo.RequestLog",
    "connectionStringSetting": "SqlConnectionString"
}

Veja a seguir o código de script C# de exemplo:

#r "Newtonsoft.Json"

using System.Net;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Primitives;
using Newtonsoft.Json;

public static IActionResult Run(HttpRequest req, ILogger log, out ToDoItem todoItem, out RequestLog requestLog)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    string requestBody = new StreamReader(req.Body).ReadToEnd();
    todoItem = JsonConvert.DeserializeObject<ToDoItem>(requestBody);

    requestLog = new RequestLog();
    requestLog.RequestTimeStamp = DateTime.Now;
    requestLog.ItemCount = 1;

    return new OkObjectResult(todoItem);
}

public class RequestLog {
    public DateTime RequestTimeStamp { get; set; }
    public int ItemCount { get; set; }
}

Saída do RabbitMQ

O exemplo a seguir mostra uma associação de saída do RabbitMQ em um arquivo function.json e uma função de script C# que usa a associação. A função lê a mensagem de um gatilho HTTP e a gera na fila do RabbitMQ.

Aqui estão os dados de associação no arquivo function.json:

{
    "bindings": [
        {
            "type": "httpTrigger",
            "direction": "in",
            "authLevel": "function",
            "name": "input",
            "methods": [
                "get",
                "post"
            ]
        },
        {
            "type": "rabbitMQ",
            "name": "outputMessage",
            "queueName": "outputQueue",
            "connectionStringSetting": "rabbitMQConnectionAppSetting",
            "direction": "out"
        }
    ]
}

Aqui está o código de script do C#:

using System;
using Microsoft.Extensions.Logging;

public static void Run(string input, out string outputMessage, ILogger log)
{
    log.LogInformation(input);
    outputMessage = input;
}

Saída do SendGrid

O exemplo a seguir mostra uma associação de saída de SendGrid em um arquivo function.json e uma função script C# que usa a associação.

Aqui estão os dados de associação no arquivo function.json:

{
    "bindings": [
        {
          "type": "queueTrigger",
          "name": "mymsg",
          "queueName": "myqueue",
          "connection": "AzureWebJobsStorage",
          "direction": "in"
        },
        {
          "type": "sendGrid",
          "name": "$return",
          "direction": "out",
          "apiKey": "SendGridAPIKeyAsAppSetting",
          "from": "{FromEmail}",
          "to": "{ToEmail}"
        }
    ]
}

Aqui está o código de script do C#:

#r "SendGrid"

using System;
using SendGrid.Helpers.Mail;
using Microsoft.Azure.WebJobs.Host;

public static SendGridMessage Run(Message mymsg, ILogger log)
{
    SendGridMessage message = new SendGridMessage()
    {
        Subject = $"{mymsg.Subject}"
    };
    
    message.AddContent("text/plain", $"{mymsg.Content}");

    return message;
}
public class Message
{
    public string ToEmail { get; set; }
    public string FromEmail { get; set; }
    public string Subject { get; set; }
    public string Content { get; set; }
}

Gatilho do SignalR

Aqui estão os dados de associação de exemplo no arquivo function.json:

{
    "type": "signalRTrigger",
    "name": "invocation",
    "hubName": "SignalRTest",
    "category": "messages",
    "event": "SendMessage",
    "parameterNames": [
        "message"
    ],
    "direction": "in"
}

O código é o seguinte:

#r "Microsoft.Azure.WebJobs.Extensions.SignalRService"
using System;
using Microsoft.Azure.WebJobs.Extensions.SignalRService;
using Microsoft.Extensions.Logging;

public static void Run(InvocationContext invocation, string message, ILogger logger)
{
    logger.LogInformation($"Receive {message} from {invocationContext.ConnectionId}.");
}

Entrada do SignalR

O exemplo a seguir mostra uma associação de entrada de informações de conexão do SignalR em um arquivo function.json e uma função C# Script que usa a associação para retornar as informações de conexão.

Aqui estão os dados de associação no arquivo function.json:

function.json de exemplo:

{
    "type": "signalRConnectionInfo",
    "name": "connectionInfo",
    "hubName": "chat",
    "connectionStringSetting": "<name of setting containing SignalR Service connection string>",
    "direction": "in"
}

Este é o código de script do C#:

#r "Microsoft.Azure.WebJobs.Extensions.SignalRService"
using Microsoft.Azure.WebJobs.Extensions.SignalRService;

public static SignalRConnectionInfo Run(HttpRequest req, SignalRConnectionInfo connectionInfo)
{
    return connectionInfo;
}

Você pode definir a propriedade userId da associação como o valor do cabeçalho usando uma userId: {headers.x-ms-client-principal-id} ou {headers.x-ms-client-principal-name}.

function.json de exemplo:

{
    "type": "signalRConnectionInfo",
    "name": "connectionInfo",
    "hubName": "chat",
    "userId": "{headers.x-ms-client-principal-id}",
    "connectionStringSetting": "<name of setting containing SignalR Service connection string>",
    "direction": "in"
}

Este é o código de script do C#:

#r "Microsoft.Azure.WebJobs.Extensions.SignalRService"
using Microsoft.Azure.WebJobs.Extensions.SignalRService;

public static SignalRConnectionInfo Run(HttpRequest req, SignalRConnectionInfo connectionInfo)
{
    // connectionInfo contains an access key token with a name identifier
    // claim set to the authenticated user
    return connectionInfo;
}

Saída do SignalR

Aqui estão os dados de associação no arquivo function.json:

function.json de exemplo:

{
  "type": "signalR",
  "name": "signalRMessages",
  "hubName": "<hub_name>",
  "connectionStringSetting": "<name of setting containing SignalR Service connection string>",
  "direction": "out"
}

Este é o código de script do C#:

#r "Microsoft.Azure.WebJobs.Extensions.SignalRService"
using Microsoft.Azure.WebJobs.Extensions.SignalRService;

public static Task Run(
    object message,
    IAsyncCollector<SignalRMessage> signalRMessages)
{
    return signalRMessages.AddAsync(
        new SignalRMessage
        {
            Target = "newMessage",
            Arguments = new [] { message }
        });
}

Você só pode enviar uma mensagem para as conexões autenticadas como um usuário configurando a ID de usuário na mensagem do SignalR.

function.json de exemplo:

{
  "type": "signalR",
  "name": "signalRMessages",
  "hubName": "<hub_name>",
  "connectionStringSetting": "<name of setting containing SignalR Service connection string>",
  "direction": "out"
}

Aqui está o código de script do C#:

#r "Microsoft.Azure.WebJobs.Extensions.SignalRService"
using Microsoft.Azure.WebJobs.Extensions.SignalRService;

public static Task Run(
    object message,
    IAsyncCollector<SignalRMessage> signalRMessages)
{
    return signalRMessages.AddAsync(
        new SignalRMessage
        {
            // the message will only be sent to this user ID
            UserId = "userId1",
            Target = "newMessage",
            Arguments = new [] { message }
        });
}

Você só pode enviar uma mensagem para as conexões que foram adicionadas a um grupo configurando o nome do grupo na mensagem do SignalR.

function.json de exemplo:

{
  "type": "signalR",
  "name": "signalRMessages",
  "hubName": "<hub_name>",
  "connectionStringSetting": "<name of setting containing SignalR Service connection string>",
  "direction": "out"
}

Este é o código de script do C#:

#r "Microsoft.Azure.WebJobs.Extensions.SignalRService"
using Microsoft.Azure.WebJobs.Extensions.SignalRService;

public static Task Run(
    object message,
    IAsyncCollector<SignalRMessage> signalRMessages)
{
    return signalRMessages.AddAsync(
        new SignalRMessage
        {
            // the message will be sent to the group with this name
            GroupName = "myGroup",
            Target = "newMessage",
            Arguments = new [] { message }
        });
}

O Serviço do SignalR permite a adição de usuários ou conexões aos grupos. Em seguida, é possível enviar mensagens a um grupo. Você pode usar a associação de saída de SignalR para gerenciar grupos.

O exemplo a seguir adiciona um usuário a um grupo.

Exemplo function.json

{
    "type": "signalR",
    "name": "signalRGroupActions",
    "connectionStringSetting": "<name of setting containing SignalR Service connection string>",
    "hubName": "chat",
    "direction": "out"
}

Run.csx

#r "Microsoft.Azure.WebJobs.Extensions.SignalRService"
using Microsoft.Azure.WebJobs.Extensions.SignalRService;

public static Task Run(
    HttpRequest req,
    ClaimsPrincipal claimsPrincipal,
    IAsyncCollector<SignalRGroupAction> signalRGroupActions)
{
    var userIdClaim = claimsPrincipal.FindFirst(ClaimTypes.NameIdentifier);
    return signalRGroupActions.AddAsync(
        new SignalRGroupAction
        {
            UserId = userIdClaim.Value,
            GroupName = "myGroup",
            Action = GroupAction.Add
        });
}

O exemplo a seguir remove um usuário de um grupo.

Exemplo function.json

{
    "type": "signalR",
    "name": "signalRGroupActions",
    "connectionStringSetting": "<name of setting containing SignalR Service connection string>",
    "hubName": "chat",
    "direction": "out"
}

Run.csx

#r "Microsoft.Azure.WebJobs.Extensions.SignalRService"
using Microsoft.Azure.WebJobs.Extensions.SignalRService;

public static Task Run(
    HttpRequest req,
    ClaimsPrincipal claimsPrincipal,
    IAsyncCollector<SignalRGroupAction> signalRGroupActions)
{
    var userIdClaim = claimsPrincipal.FindFirst(ClaimTypes.NameIdentifier);
    return signalRGroupActions.AddAsync(
        new SignalRGroupAction
        {
            UserId = userIdClaim.Value,
            GroupName = "myGroup",
            Action = GroupAction.Remove
        });
}

Saída do Twilio

O exemplo a seguir mostra uma associação de saída de Twilio em um arquivo function.json e uma função script C# que usa a associação. A função usa um parâmetro out para enviar uma mensagem de texto.

Aqui estão os dados de associação no arquivo function.json:

function.json de exemplo:

{
  "type": "twilioSms",
  "name": "message",
  "accountSidSetting": "TwilioAccountSid",
  "authTokenSetting": "TwilioAuthToken",
  "from": "+1425XXXXXXX",
  "direction": "out",
  "body": "Azure Functions Testing"
}

Aqui está o código de script do C#:

#r "Newtonsoft.Json"
#r "Twilio"
#r "Microsoft.Azure.WebJobs.Extensions.Twilio"

using System;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;
using Microsoft.Azure.WebJobs.Extensions.Twilio;
using Twilio.Rest.Api.V2010.Account;
using Twilio.Types;

public static void Run(string myQueueItem, out CreateMessageOptions message,  ILogger log)
{
    log.LogInformation($"C# Queue trigger function processed: {myQueueItem}");

    // In this example the queue item is a JSON string representing an order that contains the name of a
    // customer and a mobile number to send text updates to.
    dynamic order = JsonConvert.DeserializeObject(myQueueItem);
    string msg = "Hello " + order.name + ", thank you for your order.";

    // You must initialize the CreateMessageOptions variable with the "To" phone number.
    message = new CreateMessageOptions(new PhoneNumber("+1704XXXXXXX"));

    // A dynamic message can be set instead of the body in the output binding. In this example, we use
    // the order information to personalize a text message.
    message.Body = msg;
}

Você não pode usar os parâmetros em código assíncrono. Aqui está um exemplo de código de script C# assíncrono:

#r "Newtonsoft.Json"
#r "Twilio"
#r "Microsoft.Azure.WebJobs.Extensions.Twilio"

using System;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;
using Microsoft.Azure.WebJobs.Extensions.Twilio;
using Twilio.Rest.Api.V2010.Account;
using Twilio.Types;

public static async Task Run(string myQueueItem, IAsyncCollector<CreateMessageOptions> message,  ILogger log)
{
    log.LogInformation($"C# Queue trigger function processed: {myQueueItem}");

    // In this example the queue item is a JSON string representing an order that contains the name of a
    // customer and a mobile number to send text updates to.
    dynamic order = JsonConvert.DeserializeObject(myQueueItem);
    string msg = "Hello " + order.name + ", thank you for your order.";

    // You must initialize the CreateMessageOptions variable with the "To" phone number.
    CreateMessageOptions smsText = new CreateMessageOptions(new PhoneNumber("+1704XXXXXXX"));

    // A dynamic message can be set instead of the body in the output binding. In this example, we use
    // the order information to personalize a text message.
    smsText.Body = msg;

    await message.AddAsync(smsText);
}

Gatilho de aquecimento

O exemplo a seguir mostra um gatilho de aquecimento em um arquivo function.json e uma função de script C# que é executada em cada nova instância quando o gatilho é adicionado ao seu aplicativo.

Não é compatível com a versão 1.x do runtime do Functions.

Aqui está o arquivo function.json:

{
    "bindings": [
        {
            "type": "warmupTrigger",
            "direction": "in",
            "name": "warmupContext"
        }
    ]
}

public static void Run(WarmupContext warmupContext, ILogger log)
{
    log.LogInformation("Function App instance is warm.");  
}

Próximas etapas

Saiba mais sobre gatilhos e associações

Saiba mais sobre práticas recomendadas do Azure Functions