Руководство. Начало работы с Функциями Azure и Visual Studio для Mac

Внимание

Visual Studio для Mac планируется выйти на пенсию 31 августа 2024 г. в соответствии с корпорацией Майкрософт Современная политика жизненного цикла. Хотя вы можете продолжать работать с Visual Studio для Mac, есть несколько других вариантов для разработчиков на Mac, таких как предварительная версия нового расширения комплекта разработки C# для VS Code.

Дополнительные сведения о поддержке временная шкала и альтернативах.

В этом руководстве вы узнаете, как приступить к созданию функций Azure с помощью Visual Studio для Mac. Вы также интегрируетесь с таблицами служба хранилища Azure, которые представляют собой один из многих видов привязок и триггеров, доступных для Функции Azure разработчиков.

Задачи

• Создание и отладка локальных функций Azure
• Интеграция с веб-ресурсами и служба хранилища Azure
• Управление ходом рабочего процесса, в который входит несколько функций Azure

Требования

• Visual Studio для Mac 7.5 или более поздней версии.
• Подписка Azure (доступна бесплатно по адресу https://azure.com/free).

Упражнение 1. Создание проекта функций Azure

1. Запустите Visual Studio для Mac.

2. Щелкните Файл > Новое решение.

3. В категории Облако > Общие выберите шаблон Функции Azure. Вы будете использовать C# для создания библиотеки классов .NET, в которой размещаются функции Azure. Нажмите кнопку Далее.

   

4. Задайте имя проектаAzureFunctionsLab и нажмите Создать.

   

5. Разверните узлы в окне решения. Шаблон проекта по умолчанию включает ссылки NuGet на различные пакеты AzureWebJobs, а также на пакет Newtonsoft.Json.

   Также существует три файла: — host.json для описания глобальных параметров конфигурации для узла. — local.settings.json для настройки параметров службы. — Шаблон проекта также создает HttpTrigger по умолчанию. В целях этого руководства удалите файл HttpTrigger.cs из проекта.

   Откройте файл local.settings.json. По умолчанию в нем имеется два параметра пустой строки подключения.

   

Упражнение 2. Создание учетной записи служба хранилища Azure

1. Войдите в учетную запись Azure по адресу https://portal.azure.com.

2. В разделе Избранное, расположенном в левой части экрана, выберите Учетная запись хранения:

   

3. Нажмите Добавить, чтобы создать новую учетную запись хранения:

   

4. Введите глобальное уникальное имя для поля Имя и используйте его повторно для группы ресурсов. Оставьте значения остальных элементов по умолчанию.

   

5. Нажмите кнопку Создать. Создание учетной записи хранения может занять несколько минут. Вы получите уведомление об успешном создании.

   

6. Нажмите на кнопку Перейти к ресурсу в уведомлении.

7. Выберите вкладку Ключи доступа.

   

8. Скопируйте первую строку подключения. Эта строка используется для интеграции служба хранилища Azure с функциями Azure позже.

   

9. Вернитесь в Visual Studio для Mac и вставьте полную строку подключения как параметр AzureWebJobsStorage в файле local.settings.json. Теперь можно ссылаться на имя параметра в атрибутах для функций, которым требуется доступ к его ресурсам.

   

Пример 3. Создание и отладка функции Azure

1. Теперь вы готовы приступить к добавлению кода. При работе с библиотекой классов .NET функции Azure добавляются как статические методы. В окне решения щелкните правой кнопкой мыши узел проекта AzureFunctions и выберите Добавить > Добавить функцию.

   

2. В диалоговом окне "Новые функции Azure" выберите шаблон универсального веб-перехватчика. Укажите для параметра Имя значение Добавить и нажмите кнопку ОК для создания функции:

   

3. В начале нового файла добавьте следующие директивы using:

   using Microsoft.Azure.WebJobs.Extensions.Http;
   using System.Web;
   using Microsoft.WindowsAzure.Storage.Table;
   

4. Удалите существующий Run метод и добавьте следующий метод в класс в качестве функции Azure:

   [FunctionName("Add")]
   public static int Run(
   [HttpTrigger(AuthorizationLevel.Function, "get", Route = null)]
   HttpRequestMessage req,
   TraceWriter log)
   {
       int x = 1;
       int y = 2;
   
       return x + y;
   }
   

5. Давайте подробно рассмотрим определение метода.

   Первое, что вы увидите, это атрибут FunctionName , который помечает этот метод как функцию Azure. Этот атрибут определяет открытое имя функции. Имя атрибута не должно соответствовать имени фактического метода.

   

6. Затем метод помечается как метод public static, который является обязательным. Вы также заметите, что возвращаемое значение является int. Если иное не указано с помощью атрибутов метода, любое возвращаемое значение непустой функции Azure возвращается клиенту в виде текста. По умолчанию они возвращаются как XML, но позднее мы рассмотрим, как изменить формат на JSON.

   

7. Первый параметр помечается атрибутом HttpTrigger, который указывает, что этот метод вызывается HTTP-запросом. Атрибут также указывает уровень авторизации данного метода и поддерживаемые им команды (только GET в данном случае). Кроме того, можно также определить маршрут , который переопределяет путь к методу и предлагает способ автоматического извлечения переменных из пути. Поскольку в данном случае Route имеет значение NULL, будет использоваться путь к этому методу по умолчанию — /api/Add.

   

8. Последний параметр метода — это TraceWriter, который может использоваться для записи сообщений о диагностике и ошибках.

   

9. Установите точку останова в строке return этого метода, нажав на поле строки:

   

10. Скомпилируйте и запустите проект в сеансе отладки, нажав F5 или выбрав Запустить > Начать отладку. Или нажмите на кнопку Запуск. Все варианты выполняют одну задачу. Далее в инструкциях будет упоминаться клавиша F5, но вы можете использовать наиболее удобный метод.

    

11. При запуске проекта будет автоматически открыто приложение терминала.

12. В проекте выполняется процесс обнаружения функций Azure на основе атрибутов метода и соглашения для файлов, которые будут рассматриваться далее в этой статье. В этом случае он обнаруживает одну функцию Azure и "создает" 1 функцию задания.

    

13. В нижней части сообщения о запуске узел функций Azure выводит URL-адреса API триггеров HTTP. Там должен быть только один адрес. Скопируйте его и вставьте в новой вкладке браузера.

    

14. Сразу должна сработать точка останова. Веб-запрос был направлен в функцию и теперь готов для отладки. Наведите указатель мыши на переменную x для просмотра ее значения.

    

15. Удалите точку останова, используя тот же метод, который вы применяли для ее добавления (щелкните на поле или выберите строку и нажмите клавишу F9).

16. Чтобы продолжить выполнение, нажмите клавишу F5.

17. В браузере будут отображаться результаты метода в формате XML. Как и ожидалось, жестко закодированная операция сложения выдает достоверную сумму. Обратите внимание, что если в Safari отображается только "3", перейдите в раздел "Дополнительные параметры > Safari>" и проверка поле "Показать меню разработки в строке меню" проверка и перезагрузите страницу.

18. В Visual Studio для Mac нажмите кнопку Остановить, чтобы завершить сеанс отладки. Чтобы применить изменения, перезапустите (остановите и снова запустите) сеанс отладки.

    

19. В методе Run замените определения x и y следующим кодом. Этот код извлекает значения из строки запроса URL-адреса, чтобы операция сложения выполнялась динамически в зависимости от предоставленных параметров.

    var query = HttpUtility.ParseQueryString(req.RequestUri.Query);
    
    int x = int.Parse(query["x"]);
    
    int y = int.Parse(query["y"]);
    
    return x + y;
    

20. Запустите приложение.

21. Вернитесь в окно браузера и добавьте строку /?x=2&y=3 в URL-адрес. Теперь URL-адрес должен выглядеть следующим образом: http://localhost:7071/api/Add?x=2&y=3. Перейдите по новому URL-адресу.

22. На этот раз результат должен отражать новые параметры. Вы можете запустить проект с другими значениями. Проверка ошибок не выполняется, поэтому в случае недопустимых или отсутствующих параметров возникнет ошибка.

23. Остановите сеанс отладки.

Упражнение 4. Работа с function.json

1. В предыдущем упражнении было упоминание, что Visual Studio для Mac "создало" функцию задания для функции Azure, определенной в библиотеке. Дело в том, что функции Azure не используют атрибуты метода в среде выполнения, но используют соглашение для файловой системы во время компиляции для настройки времени и способа предоставления функций Azure. В окне решения щелкните правой кнопкой мыши узел проекта и выберите Отобразить в средстве поиска.

   

2. Перейдите к файловой системе до пункта bin/Debug/netstandard2.0. Найдите папку с именем Add. Эта папка была создана по атрибуту имени функции в коде C#. Разверните папку Add. Там находится один файл function.json. Этот файл используется средой выполнения для размещения и управления функцией Azure. Для других языковых моделей без поддержки среды компиляции (например, скрипт C# или JavaScript) эти папки необходимо создать вручную. Для разработчиков C# они создаются автоматически из метаданных атрибута при сборке. Щелкните правой кнопкой мыши файл function.json и откройте его в Visual Studio.

   

3. Учитывая уже выполненные шаги в этом руководстве, вы имеете общее представление об атрибутах C#. Так что этот файл JSON должен быть вам знаком. Но следует обсудить еще несколько аспектов, о которых мы не говорили ранее. Например, для каждого элемента привязки binding необходимо задать направление direction. Очевидно, что in означает входной параметр, а out — это либо возвращаемое значение (через $return), либо параметр out для метода. В сборке также необходимо указать scriptFile (относительно этого конечного расположения) и метод entryPoint (открытый и статический). В следующих шагах мы добавим пользовательский путь к функции с помощью этой модели, поэтому скопируйте содержимое этого файла в буфер обмена.

   

4. В окне решения щелкните правой кнопкой мыши узел проекта AzureFunctionsLab и выберите Добавить > Новая папка. Назовите папку Adder. В соответствии с соглашением по умолчанию имя этой папки будет определять путь к API, например api/Adder.

   

5. Щелкните правой кнопкой мыши папку Adder и выберите Добавить > Новый файл.

   

6. Выберите категорию Веб и шаблон Пустой файл JSON. Задайте Имяfunction и нажмите Создать.

   

7. Вставьте содержимое из другого файла function.json (из шага 3), чтобы заменить содержимое по умолчанию только что созданного файла.

8. Удалите следующие строки в верхней части файла json:

   "configurationSource":"attributes",
   "generatedBy":"Microsoft.NET.Sdk.Functions-1.0.13",
   

9. В конце первой привязки (после строки name: req) добавьте следующие свойства. Не забудьте поставить запятую в предыдущей строке. Это свойство переопределяет маршрут по умолчанию. Теперь он извлечет параметры int из пути и поместит их в параметры метода с именами x и y.

   "direction": "in",
   "route": "Adder/{x:int?}/{y:int?}"
   

10. Добавьте другую привязку под первой. Эта привязка обрабатывает возвращаемое значение функции. Не забудьте поставить запятую в предыдущей строке:

    {
    "name": "$return",
    "type": "http",
    "direction": "out"
    }
    

11. Обновите свойство entryPoint в нижней части файла, чтобы использовать метод Add2, как показано ниже. Это показывает, что путь api/Adder... можно сопоставить с соответствующим методом с любым именем (в данном случае — Add2).

    "entryPoint": "<project-name>.<function-class-name>.Add2"
    

12. Окончательный файл function.json должен выглядеть следующим образом:

    {
    "bindings": [
        {
        "type": "httpTrigger",
        "methods": [
            "get"
        ],
        "authLevel": "function",
        "direction": "in",
        "name": "req",
        "route": "Adder/{x:int?}/{y:int?}"
        },
        {
        "name": "$return",
        "type": "http",
        "direction": "out"
        }
    ],
    "disabled": false,
    "scriptFile": "../bin/AzureFunctionsProject.dll",
    "entryPoint": "AzureFunctionsProject.Add.Add2"
    }
    

13. Чтобы все это работало, необходимо сделать последний шаг — дать Visual Studio для Mac указание копировать этот файл в тот же относительный путь в выходном каталоге при каждом изменении. Выберите файл, откройте вкладку свойств на правой панели и для пункта Копировать в выходной каталог выберите Копировать более позднюю версию:

    

14. В Add.cs замените метод Run (включая атрибут) следующим методом для выполнения ожидаемой функции. Это очень похоже на метод Run, только он не использует атрибуты и имеет явные параметры для x и y.

    public static int Add2(
        HttpRequestMessage req,
        int x,
        int y,
        TraceWriter log)
    {
        return x + y;
    }
    

15. Нажмите клавишу F5 для сборки и запуска проекта.

16. После завершения сборки и запуска платформы вы увидите, что существует второй маршрут для запросов, сопоставляемый с добавленным методом:

    

17. Вернитесь в окно браузера и перейдите к http://localhost:7071/api/Adder/3/5.

18. На этот раз метод сработает снова, извлекая параметры из пути и рассчитывая сумму.

19. Вернитесь в Visual Studio для Mac и завершите сеанс отладки.

Упражнение 5. Работа с таблицами служба хранилища Azure

Часто сборка службы может быть гораздо сложнее, чем то, что мы создали до сих пор, и требует значительного количества времени или инфраструктуры для выполнения. В этом случае эффективнее будет принимать запросы, помещенные в очередь на обработку, когда ресурсы будут доступны. Функции Azure поддерживают такой вариант. В других случаях необходимо централизованно хранить данные. Для этого удобно использовать таблицы хранилища Azure.

1. Добавьте следующий класс в Add.cs. Он добавляется в пространство имен, но за пределами существующего класса.

   public class TableRow : TableEntity
   {
       public int X { get; set; }
       public int Y { get; set; }
       public int Sum { get; set; }
   }
   

2. В классе Add добавьте следующий код, чтобы ввести другую функцию. Этот код уникален, поскольку не содержит HTTP-ответов. Последняя строка возвращает новый объект TableRow, содержащий ключевую информацию, которую будет легко извлечь позже (PartitionKey и RowKey), а также его параметры и сумму. Код в этом методе также использует TraceWriter, чтобы вам было проще понимать, когда функция выполняется.

   [FunctionName("Process")]
   [return: Table("Results")]
   public static TableRow Process(
       [HttpTrigger(AuthorizationLevel.Function, "get",
           Route = "Process/{x:int}/{y:int}")]
       HttpRequestMessage req,
       int x,
       int y,
       TraceWriter log)
   {
       log.Info($"Processing {x} + {y}");
   
       return new TableRow()
       {
           PartitionKey = "sums",
           RowKey = $"{x}_{y}",
           X = x,
           Y = y,
           Sum = x + y
       };
   }
   

3. Нажмите клавишу F5 для сборки и запуска проекта.

4. На вкладке браузера перейдите по адресу http://localhost:7071/api/Process/4/6. В результате в очередь встанет еще одно сообщение, и в конечном итоге в таблицу будет добавлена еще одна строка.

5. Вернитесь в терминал и следите за входящим запросом для 4 + 6.

   

6. Вернитесь в браузер и обновите запрос, указав тот же URL-адрес. На этот раз вы увидите ошибку после метода Process. Дело в том, что код пытается добавить строку в таблицу хранилища таблиц Azure с помощью комбинации ключа раздела и строки, которая уже существует.

   System.Private.CoreLib: Exception while executing function: Process. Microsoft.Azure.WebJobs.Host: Error while handling parameter $return after function returned:. Microsoft.Azure.WebJobs.Host: The specified entity already exists.

7. Остановите сеанс отладки.

8. Чтобы устранить ошибку, добавьте следующий параметр в определение метода непосредственно перед параметром TraceWriter. Этот параметр дает платформе функций Azure указание попытаться извлечь TableRow из таблицы Results в PartitionKey, который мы использовали для хранения результатов. Настоящее волшебство происходит тогда, когда вы заметите, что RowKey создается динамически на основе других параметров x и y для этого же метода. Если эта строка уже существует, tableRow получит ее при запуске метода без дополнительных усилий со стороны разработчика. Если строка не существует, она будет иметь значение NULL. Благодаря этой возможности разработчики могут сосредоточиться на важной бизнес-логике, а не на инфраструктуре.

   [Table("Results", "sums", "{x}_{y}")]
   TableRow tableRow,
   

9. Добавьте следующий код в начало метода. Если tableRow не имеет значение NULL, значит, у нас уже есть результаты для запрашиваемой операции и мы можем получить их незамедлительно. В противном случае функция будет работать, как раньше. Хотя это может быть не самый надежный способ возврата данных, он иллюстрирует точку, в которую можно управлять невероятно сложными операциями на нескольких масштабируемых уровнях с очень небольшим кодом.

   if (tableRow != null)
   {
       log.Info($"{x} + {y} already exists");
       return null;
   }
   

10. Нажмите клавишу F5 для сборки и запуска проекта.

11. На вкладке браузера измените URL-адрес: http://localhost:7071/api/Process/4/6. Поскольку для этой записи уже существует строка в таблице, она будет возвращена немедленно и без ошибок. Раз выходных данных HTTP нет, результат можно увидеть в терминале.

    

12. Обновите URL-адрес, указав еще не протестированную комбинацию, например http://localhost:7071/api/Process/5/7. Обратите внимание на сообщение в терминале, которое указывает, что строка таблицы не найдена (как и ожидалось).

    

13. Вернитесь в Visual Studio для Mac и завершите сеанс отладки.

Итоги

В этом руководстве вы узнали, как приступить к созданию функций Azure с помощью Visual Studio для Mac.