Справочник разработчика F# по Функциям AzureAzure Functions F# Developer Reference

F# для Функций Azure — это решение для быстрого запуска фрагментов кода (функций) в облаке.F# for Azure Functions is a solution for easily running small pieces of code, or "functions," in the cloud. Данные поступают в функцию F# через аргументы функции.Data flows into your F# function via function arguments. Имена аргументов указываются в function.json, и есть предварительно определенные имена для доступа к таким объектам, как средство ведения журнала функций и маркеры отмены.Argument names are specified in function.json, and there are predefined names for accessing things like the function logger and cancellation tokens.

Важно!

Скрипт F# (.fsx) поддерживается только в среде выполнения функций Azure версии 1.x.F# script (.fsx) is only supported by version 1.x of the Azure Functions runtime. Если вы хотите использовать F# в среде выполнения версии 2. x и более поздних версий, необходимо использовать предварительно скомпилированный проект F# библиотеки классов (. FS).If you want to use F# with version 2.x and later versions of the runtime, you must use a precompiled F# class library project (.fs). Создание, управление и публикация проекта библиотеки классов F# выполняются в Visual Studio точно так же, как и проекта библиотеки классов C#.You create, manage, and publish an F# class library project using Visual Studio as you would a C# class library project. Дополнительные сведения о версиях службы "Функции Azure" см. здесь.For more information about Functions versions, see Azure Functions runtime versions overview.

В этой статье предполагается, что вы уже прочли справочник разработчика по Функциям Azure.This article assumes that you've already read the Azure Functions developer reference.

Принципы работы FSX-файлаHow .fsx works

Файл .fsx — это скрипт F#.An .fsx file is an F# script. Он может рассматриваться как проект F#, содержащийся в одном файле.It can be thought of as an F# project that's contained in a single file. Этот файл содержит код для программы (в этом случае функция Azure) и директивы для управления зависимостями.The file contains both the code for your program (in this case, your Azure Function) and directives for managing dependencies.

При использовании .fsx для функции Azure обычно необходимые сборки добавляются автоматически, что позволяет сосредоточиться на функции, а не на стандартном коде.When you use an .fsx for an Azure Function, commonly required assemblies are automatically included for you, allowing you to focus on the function rather than "boilerplate" code.

Структура папокFolder structure

Структура папок для проекта на F# выглядит следующим образом.The folder structure for an F# script project looks like the following:

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

Существует общий файл host.json, который можно использовать для настройки приложения-функции.There's a shared host.json file that can be used to configure the function app. У каждой функции есть собственный файл кода (.fsx) и файл конфигурации привязки (function.json).Each function has its own code file (.fsx) and binding configuration file (function.json).

Расширения привязки, необходимые в версии 2. x и более поздних версиях среды выполнения функций, определяются в файле extensions.csproj с фактическими файлами библиотеки в папке bin.The binding extensions required in version 2.x and later versions of the Functions runtime are defined in the extensions.csproj file, with the actual library files in the bin folder. При локальной разработке необходимо зарегистрировать расширения привязки.When developing locally, you must register binding extensions. При разработке функций на портале Azure эта регистрация выполняется автоматически.When developing functions in the Azure portal, this registration is done for you.

Привязка к аргументамBinding to arguments

Каждая привязка поддерживает набор аргументов. Это подробно описано в справочнике разработчика по триггерам и привязкам в Функциях Azure.Each binding supports some set of arguments, as detailed in the Azure Functions triggers and bindings developer reference. Например, одной из привязок аргументов, поддерживаемых триггером больших двоичных объектов, выступает POCO. Эту привязку можно представить с помощью записи F#.For example, one of the argument bindings a blob trigger supports is a POCO, which can be expressed using an F# record. Пример.For example:

type Item = { Id: string }

let Run(blob: string, output: byref<Item>) =
    let item = { Id = "Some ID" }
    output <- item

Для функции Azure на F# понадобится один или несколько аргументов.Your F# Azure Function will take one or more arguments. Говоря об аргументах Функций Azure, мы имеем в виду входные и выходные аргументы.When we talk about Azure Functions arguments, we refer to input arguments and output arguments. Входной аргумент соответствует своему названию, так как это входные данные для функции Azure F#.An input argument is exactly what it sounds like: input to your F# Azure Function. Выходной аргумент представлен изменяемыми данными или аргументом byref<>, который используется для передачи данных обратно из этой функции.An output argument is mutable data or a byref<> argument that serves as a way to pass data back out of your function.

В приведенном выше примере blob выступает в качестве входного аргумента, а output — выходного аргумента.In the example above, blob is an input argument, and output is an output argument. Обратите внимание, мы использовали byref<> для output (не нужно добавлять аннотацию [<Out>]).Notice that we used byref<> for output (there's no need to add the [<Out>] annotation). При использовании типа byref<> функция может изменять запись или объект, на который будет ссылаться аргумент.Using a byref<> type allows your function to change which record or object the argument refers to.

Если в качестве типа входных данных используется запись F#, определение записи необходимо пометить атрибутом [<CLIMutable>] , чтобы платформа Функций Azure могла установить поля соответствующим образом перед передачей записи в функцию.When an F# record is used as an input type, the record definition must be marked with [<CLIMutable>] in order to allow the Azure Functions framework to set the fields appropriately before passing the record to your function. "За кулисами" [<CLIMutable>] создает методы задания свойств записи.Under the hood, [<CLIMutable>] generates setters for the record properties. Пример.For example:

[<CLIMutable>]
type TestObject =
    { SenderName : string
      Greeting : string }

let Run(req: TestObject, log: ILogger) =
    { req with Greeting = sprintf "Hello, %s" req.SenderName }

Класс F# можно также использовать для входных и выходных аргументов.An F# class can also be used for both in and out arguments. Для свойств класса обычно требуются методы получения и задания.For a class, properties will usually need getters and setters. Пример.For example:

type Item() =
    member val Id = "" with get,set
    member val Text = "" with get,set

let Run(input: string, item: byref<Item>) =
    let result = Item(Id = input, Text = "Hello from F#!")
    item <- result

Ведение журналаLogging

Для записи выходных данных в потоковые журналы в F# в функции следует использовать аргумент типа ILogger.To log output to your streaming logs in F#, your function should take an argument of type ILogger. Для согласованности мы советуем назвать этот аргумент log.For consistency, we recommend this argument is named log. Пример.For example:

let Run(blob: string, output: byref<string>, log: ILogger) =
    log.LogInformation(sprintf "F# Azure Function processed a blob: %s" blob)
    output <- input

Асинхронный режимAsync

Рабочий процесс async можно использовать, но результат должен возвратить Task.The async workflow can be used, but the result needs to return a Task. Для этого нужно использовать Async.StartAsTask. Например:This can be done with Async.StartAsTask, for example:

let Run(req: HttpRequestMessage) =
    async {
        return new HttpResponseMessage(HttpStatusCode.OK)
    } |> Async.StartAsTask

Токен отменыCancellation Token

Если функция должна правильно обрабатывать завершение работы, ей можно присвоить аргумент CancellationToken.If your function needs to handle shutdown gracefully, you can give it a CancellationToken argument. При этом можно использовать async. Например:This can be combined with async, for example:

let Run(req: HttpRequestMessage, token: CancellationToken)
    let f = async {
        do! Async.Sleep(10)
        return new HttpResponseMessage(HttpStatusCode.OK)
    }
    Async.StartAsTask(f, token)

Импорт пространств именImporting namespaces

Пространства имен можно открывать в обычном режиме.Namespaces can be opened in the usual way:

open System.Net
open System.Threading.Tasks
open Microsoft.Extensions.Logging

let Run(req: HttpRequestMessage, log: ILogger) =
    ...

Следующие пространства имен открываются автоматически:The following namespaces are automatically opened:

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

Ссылки на внешние сборкиReferencing External Assemblies

Ссылки на сборку платформы можно добавить с помощью директивы #r "AssemblyName".Similarly, framework assembly references can be added with the #r "AssemblyName" directive.

#r "System.Web.Http"

open System.Net
open System.Net.Http
open System.Threading.Tasks
open Microsoft.Extensions.Logging

let Run(req: HttpRequestMessage, log: ILogger) =
    ...

Следующие сборки автоматически добавляются средой внешнего размещения Функций Azure:The following assemblies are automatically added by the Azure Functions hosting environment:

  • mscorlib,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.System.Net.Http.Formatting.

Кроме того, следующие сборки представляют собой частные случаи, и к ним можно обращаться по простому имени (например, #r "AssemblyName").In addition, the following assemblies are special cased and may be referenced by simplename (e.g. #r "AssemblyName"):

  • Newtonsoft.Json
  • Microsoft.WindowsAzure.Storage
  • Microsoft.ServiceBus
  • Microsoft.AspNet.WebHooks.Receivers
  • Microsoft.AspNEt.WebHooks.Common.Microsoft.AspNEt.WebHooks.Common.

Если необходимо указать ссылку на закрытую сборку, можно отправить файл сборки в папку bin, связанную с функцией, и указать его по имени файла (например, #r "MyAssembly.dll").If you need to reference a private assembly, you can upload the assembly file into a bin folder relative to your function and reference it by using the file name (e.g. #r "MyAssembly.dll"). Дополнительные сведения о передаче файлов в папку функции см. в следующем разделе.For information on how to upload files to your function folder, see the following section on package management.

Вводная часть редактораEditor Prelude

В редакторе, поддерживающем службы компиляции F#, не будут учитываться пространства имен и сборки, которые Функции Azure автоматически включают в себя.An editor that supports F# Compiler Services will not be aware of the namespaces and assemblies that Azure Functions automatically includes. Таким образом, может быть полезно включить вводную часть, которая помогает редактору найти используемые сборки и явным образом открыть пространства имен.As such, it can be useful to include a prelude that helps the editor find the assemblies you are using, and to explicitly open namespaces. Пример.For example:

#if !COMPILED
#I "../../bin/Binaries/WebJobs.Script.Host"
#r "Microsoft.Azure.WebJobs.Host.dll"
#endif

open System
open Microsoft.Azure.WebJobs.Host
open Microsoft.Extensions.Logging

let Run(blob: string, output: byref<string>, log: ILogger) =
    ...

При выполнении кода Функции Azure обрабатывают источник, для которого определено COMPILED. Таким образом, вводная часть редактора будет игнорироваться.When Azure Functions executes your code, it processes the source with COMPILED defined, so the editor prelude will be ignored.

Управление пакетамиPackage management

Чтобы использовать пакеты NuGet в функции F#, добавьте файл project.json в папку соответствующей функции в файловой системе приложения-функции.To use NuGet packages in an F# function, add a project.json file to the function's folder in the function app's file system. Ниже приведен пример файла project.json, который добавляет ссылку на пакет NuGet в Microsoft.ProjectOxford.Face версии 1.1.0.Here is an example project.json file that adds a NuGet package reference to Microsoft.ProjectOxford.Face version 1.1.0:

{
  "frameworks": {
    "net46":{
      "dependencies": {
        "Microsoft.ProjectOxford.Face": "1.1.0"
      }
    }
   }
}

Поддерживается только версия .NET Framework 4.6, поэтому убедитесь, что ваш файл project.json определяет net46, как показано ниже.Only the .NET Framework 4.6 is supported, so make sure that your project.json file specifies net46 as shown here.

При отправке файла project.json среда выполнения получает пакеты и автоматически добавляет ссылки на сборки пакетов.When you upload a project.json file, the runtime gets the packages and automatically adds references to the package assemblies. Добавлять директивы #r "AssemblyName" не нужно.You don't need to add #r "AssemblyName" directives. Просто добавьте необходимые операторы open в свой файл .fsx.Just add the required open statements to your .fsx file.

Может потребоваться автоматически поместить ссылки на сборки во вводную часть редактора, чтобы улучшить взаимодействие редактора со службами компиляции F#.You may wish to put automatically references assemblies in your editor prelude, to improve your editor's interaction with F# Compile Services.

Добавление файла project.json в функцию AzureHow to add a project.json file to your Azure Function

  1. Сначала убедитесь, что приложение функции запущено, для чего можно открыть эту функцию на портале Azure.Begin by making sure your function app is running, which you can do by opening your function in the Azure portal. Это также обеспечивает доступ к потоковым журналам, где будут отображаться выходные данные установки пакета.This also gives access to the streaming logs where package installation output will be displayed.
  2. Чтобы отправить файл project.json , воспользуйтесь одним из методов, описанных в разделе Как обновить файлы приложения-функции.To upload a project.json file, use one of the methods described in how to update function app files. При использовании непрерывного развертывания для Функций Azure можно добавить файл project.json в промежуточную ветвь, чтобы поэкспериментировать с ним, прежде чем добавлять в ветвь развертывания.If you are using Continuous Deployment for Azure Functions, you can add a project.json file to your staging branch in order to experiment with it before adding it to your deployment branch.
  3. После добавления файла project.json в потоковом журнале функции отобразятся выходные данные, как в следующем примере.After the project.json file is added, you will see output similar to the following example in your function's streaming log:
2016-04-04T19:02:48.745 Restoring packages.
2016-04-04T19:02:48.745 Starting NuGet restore
2016-04-04T19:02:50.183 MSBuild auto-detection: using msbuild version '14.0' from 'D:\Program Files (x86)\MSBuild\14.0\bin'.
2016-04-04T19:02:50.261 Feeds used:
2016-04-04T19:02:50.261 C:\DWASFiles\Sites\facavalfunctest\LocalAppData\NuGet\Cache
2016-04-04T19:02:50.261 https://api.nuget.org/v3/index.json
2016-04-04T19:02:50.261
2016-04-04T19:02:50.511 Restoring packages for D:\home\site\wwwroot\HttpTriggerCSharp1\Project.json...
2016-04-04T19:02:52.800 Installing Newtonsoft.Json 6.0.8.
2016-04-04T19:02:52.800 Installing Microsoft.ProjectOxford.Face 1.1.0.
2016-04-04T19:02:57.095 All packages are compatible with .NETFramework,Version=v4.6.
2016-04-04T19:02:57.189
2016-04-04T19:02:57.189
2016-04-04T19:02:57.455 Packages restored.

Переменные средыEnvironment variables

Чтобы получить значение переменной среды или значение параметра приложения, используйте свойство System.Environment.GetEnvironmentVariable, как в следующем примере:To get an environment variable or an app setting value, use System.Environment.GetEnvironmentVariable, for example:

open System.Environment
open Microsoft.Extensions.Logging

let Run(timer: TimerInfo, log: ILogger) =
    log.LogInformation("Storage = " + GetEnvironmentVariable("AzureWebJobsStorage"))
    log.LogInformation("Site = " + GetEnvironmentVariable("WEBSITE_SITE_NAME"))

Повторное использование кода FSX-файлаReusing .fsx code

Вы можете использовать код из других файлов .fsx с помощью директивы #load.You can use code from other .fsx files by using a #load directive. Пример.For example:

run.fsx

#load "logger.fsx"

let Run(timer: TimerInfo, log: ILogger) =
    mylog log (sprintf "Timer: %s" DateTime.Now.ToString())

logger.fsx

let mylog(log: ILogger, text: string) =
    log.LogInformation(text);

Пути, передаваемые в директиве #load, определены относительно расположения вашего файла .fsx.Paths provides to the #load directive are relative to the location of your .fsx file.

  • #load "logger.fsx" загружает файл, расположенный в папке функции.#load "logger.fsx" loads a file located in the function folder.
  • #load "package\logger.fsx" загружает файл, расположенный в папке package, которая содержится в папке функции.#load "package\logger.fsx" loads a file located in the package folder in the function folder.
  • #load "..\shared\mylogger.fsx" загружает файл, расположенный в папке shared на том же уровне, что и папка функции, то есть непосредственно в разделе wwwroot.#load "..\shared\mylogger.fsx" loads a file located in the shared folder at the same level as the function folder, that is, directly under wwwroot.

Директива #load работает только с файлами .fsx (скрипт F#), а не с файлами .fs.The #load directive only works with .fsx (F# script) files, and not with .fs files.

Дальнейшие действияNext steps

Для получения дополнительных сведений см. следующие ресурсы:For more information, see the following resources: