.NET 5 支持 Azure Functions OpenAPI 擴展啦!

語言: CN / TW / HK

我們很高興地宣佈.NET 5 支持 Azure Functions OpenAPI 擴展啦!

今年 5 月,在 Build大會 上,Azure Functions OpenAPI的功能支持(預覽版)正式宣佈。當時,它最高支持 v3 運行時——.NET Core 3.1 版本。最近,它發佈了 .NET 5 隔離工作器支持包作為預覽。在這篇文章中,我將回顧如何使用它並將其部署到 Azure。

注意:您可以在此 GitHub 存儲庫中找到本文中使用的示例代碼: https://github.com/justinyoo/...

在 .NET 5 中創建 Azure Functions應用程序

讓我們使用Visual Studio來完成這個練習。在創建應用程序時,使用“.NET 5(隔離)"運行時和"Http觸發器"。

然後您將找到帶有默認代碼的HTTP端點。現在,在解決方案資源管理器上選擇NuGet包管理器菜單。

在NuGet包管理器屏幕中,勾選“包括預發佈”複選框,然後搜索Microsoft.Azure.Functions.Worker.Extensions.OpenApi包。在撰寫本文時,NuGet打包程序版本是v0.8.1-preview。

OpenAPI擴展現在已經安裝。

配置HostBuilder

安裝OpenAPI擴展之後,讓我們配置HostBuilder。首先,打開Program.cs文件並刪除現有的ConfigureFunctionsWorkerDefaults()方法。這是因為該方法默認使用System.Text.Json,我們不會使用它。

public static void Main(){
        var host = new HostBuilder()
            // :point_down::point_down::point_down::point_down::point_down: 刪除以下這行 :point_down::point_down::point_down::point_down::point_down:
            .ConfigureFunctionsWorkerDefaults()
            // :point_up_2::point_up_2::point_up_2::point_up_2::point_up_2: 刪除以上這行 :point_up_2::point_up_2::point_up_2::point_up_2::point_up_2:
            .Build(); 
        host.Run();
    }

然後,按此順序添加ConfigureFunctionsWorkerDefaults(worker => worker. usenewtonsoftjson())和ConfigureOpenApi()方法。第一個方法明確聲明要使用Newtonsoft.Json包,下一個導入額外的OpenAPI相關端點。

public static void Main() 
{
        var host = new HostBuilder()
            // :point_down::point_down::point_down::point_down::point_down: Add these lines below :point_down::point_down::point_down::point_down::point_down:
            .ConfigureFunctionsWorkerDefaults(worker => worker.UseNewtonsoftJson())
            .ConfigureOpenApi()
           // :point_up_2::point_up_2::point_up_2::point_up_2::point_up_2: Add these lines above :point_up_2::point_up_2::point_up_2::point_up_2::point_up_2:
           .Build();
        host.Run();
}

注意:目前,使用 System.Text.Json 並不能保證應用程序是否正常工作。因此,強烈推薦使用 Newtonsoft.Json。

至此,配置完畢。讓我們繼續。

添加OpenAPI修飾符

添加 OpenAPI 相關的修飾符,如下所示。這與現有方法完全相同,所以我不會講得太深。

// :point_down::point_down::point_down::point_down::point_down: 在下面添加OpenAPI 相關的修飾符:point_down::point_down::point_down::point_down::point_down:
    [OpenApiOperation(operationId: "greeting", tags: new[] { "greeting" }, Summary = "Greetings", Description = "This shows a welcome message.", Visibility = OpenApiVisibilityType.Important)]
    [OpenApiSecurity("function_key", SecuritySchemeType.ApiKey, Name = "code", In = OpenApiSecurityLocationType.Query)]
    [OpenApiResponseWithBody(statusCode: HttpStatusCode.OK, contentType: "text/plain", bodyType: typeof(string), Summary = "The response", Description = "This returns the response")]
    // :point_up_2::point_up_2::point_up_2::point_up_2::point_up_2: 在上面添加OpenAPI 相關的修飾符 :point_up_2::point_up_2::point_up_2::point_up_2::point_up_2:
    [Function("Function1")]
    public static HttpResponseData Run([HttpTrigger(AuthorizationLevel.Function, "get", "post")] HttpRequestData req,
        FunctionContext executionContext)
    {
        ...
    }

一旦你完成了修飾符的添加,你就完成了!讓我們運行這個應用程序。

運行Swagger UI

通過輸入 F5 鍵或單擊 Visual Studio 上的調試按鈕運行Function應用程序。

您將看到控制枱中添加了OpenAPI相關的端點。

在web瀏覽器上運行 http://localhost:7071/api/swa... 端點,您將看到Swagger UI頁面。

現在已正確實施具有 OpenAPI 功能的 Azure Function 應用。

部署Azure Fuuction APP-Windows

你確認你的 Azure Function 應用工作正常。現在需要部署該項目。 首先,單擊解決方案資源管理器中的“發佈”菜單。

選擇“Azure”,然後選擇“Azure Functions App (Windows)”。

您可以使用現有的 Function 應用程序實例或通過單擊按鈕來創建一個新的應用程序實例。這一次,讓我們使用當前實例。

一旦部署完成,在web瀏覽器上打開Azure Functions URL,你就會看到Swagger UI頁面。

部署Azure Function應用- Linux

這一次,讓我們將相同的應用程序部署到Linux實例。除此之外,讓我們使用GitHub Actions。為了做到這一點,你必須將這個應用程序上傳到GitHub存儲庫。因此,移動到“Git Changes”窗格並創建一個Git倉庫。

如果你已經在Visual Studio中登錄了GitHub,你就可以創建一個存儲庫並推送代碼。

一旦推送了所有代碼,請訪問 GitHub 以檢查您的存儲庫是否已實際上傳所有代碼。

讓我們回到發佈屏幕,點擊“New”按鈕來創建一個新的發佈配置文件。

然後會出現一個類似的彈出窗口。這次讓我們使用“Azure Function App (Linux)”菜單。

如前所述,您可以使用現有的實例或創建新的實例。我們就用現有的吧。

在前面的部署練習中,我們沒有GitHub存儲庫。因此,我們不得不使用本地部署的方法。但這一次,我們有GitHub存儲庫,這意味着我們有選擇。因此,這次我們不選擇相同的部署方法,而是選擇GitHub Actions。

GitHub Actions 工作流現已自動生成。但這需要一個新的commit。

移至“Git Changes”窗格,輸入如下所示的提交消息,單擊“Commit All”按鈕,然後推送更改。

當您實際訪問您的 GitHub 存儲庫時,您的 GitHub 操作工作流會運行buil和部署。

一旦部署結束,打開一個新的web瀏覽器,訪問Azure Functions應用程序URL,並發現Swagger UI頁面被正確地呈現。

到目前為止,我們已經學習瞭如何創建一個支持OpenAPI的Azure Functions應用程序,在.Net 5隔離的工作環境中運行,並無需離開Visual Studio就將其部署到Azure。我猜理論上它也可以在.Net 6上很好運行。如果你好奇,請部署它,並在 https://github.com/Azure/azur... 上吿訴我們!

參考資料

  • 進入GitHub搜索: Azure Functions OpenAPI擴展
  • 進入Microsoft Docs搜索:在Visual Studio中使用Azure Function和API管理集成創建無服務器API(預覽版)
  • 進入MS Learn平台搜索:Azure Functions: 發現OpenAPI和Power應用

參考鏈接

Build大會鏈接地址:

https://mybuild.microsoft.com...

Azure Functions OpenAPI的功能支持(預覽版)正式宣佈鏈接地址:

https://docs.microsoft.com/en...

.NET 5 隔離工作器支持包鏈接地址:

https://github.com/Azure/azur...

Visual Studio鏈接地址:

https://visualstudio.microsof...

支持OpenAPI鏈接地址:

https://github.com/Azure/azur...

Azure Functions鏈接地址:

https://docs.microsoft.com/en...

Azure Functions OpenAPI擴展鏈接地址:

https://github.com/Azure/azur...

在Visual Studio中使用Azure Function和API管理集成創建無服務器API(預覽版)鏈接地址:

https://docs.microsoft.com/en...

Azure Functions: 發現OpenAPI和Power應用鏈接地址:

https://www.youtube.com/playl...

掃碼關注微軟MSDN,獲取更多微軟一手技術信息和官方學習資料!