.Net: Mark gRPC and OpenAPI Functions as Experimental (#4244)

- Mark gRPC and OpenAPI functions as experimental, to improve them in
v1.
- Enable dynamic payload building by default, aligning with the
functionality of other functions.

---------

Co-authored-by: Roger Barreto <19890735+RogerBarreto@users.noreply.github.com>

dotnet/docs/EXPERIMENTS.md

@@ -45,6 +45,7 @@ You can use the following diagnostic IDs to ignore warnings or errors for a part
 
 - SKEXP0040: GRPC functions
 - SKEXP0041: Markdown functions
+- SKEXP0042: OpenAPI functions
 
 ## Out-of-the-box plugins
 

dotnet/samples/KernelSyntaxExamples/KernelSyntaxExamples.csproj

@@ -9,7 +9,7 @@
     <OutputType>Exe</OutputType>
     <IsPackable>false</IsPackable>
     <!-- Suppress: "Declare types in namespaces", "Require ConfigureAwait", "Experimental" -->
-    <NoWarn>CA1050,CA1707,CA2007,VSTHRD111,CS1591,RCS1110,CA5394,SKEXP0001,SKEXP0002,SKEXP0003,SKEXP0004,SKEXP0010,SKEXP0011,,SKEXP0012,SKEXP0020,SKEXP0021,SKEXP0022,SKEXP0023,SKEXP0024,SKEXP0025,SKEXP0026,SKEXP0027,SKEXP0028,SKEXP0029,SKEXP0030,SKEXP0031,SKEXP0032,SKEXP0040,SKEXP0041,SKEXP0050,SKEXP0051,SKEXP0052,SKEXP0053,SKEXP0054,SKEXP0055,SKEXP0060,SKEXP0061,SKEXP0101,SKEXP0102</NoWarn>
+    <NoWarn>CA1050,CA1707,CA2007,VSTHRD111,CS1591,RCS1110,CA5394,SKEXP0001,SKEXP0002,SKEXP0003,SKEXP0004,SKEXP0010,SKEXP0011,,SKEXP0012,SKEXP0020,SKEXP0021,SKEXP0022,SKEXP0023,SKEXP0024,SKEXP0025,SKEXP0026,SKEXP0027,SKEXP0028,SKEXP0029,SKEXP0030,SKEXP0031,SKEXP0032,SKEXP0040,SKEXP0041,SKEXP0042,SKEXP0050,SKEXP0051,SKEXP0052,SKEXP0053,SKEXP0054,SKEXP0055,SKEXP0060,SKEXP0061,SKEXP0101,SKEXP0102</NoWarn>
   </PropertyGroup>
   <ItemGroup>
     <Compile Remove="Example12_SequentialPlanner.cs" />

dotnet/src/Functions/Functions.Grpc/AssemblyInfo.cs

@@ -0,0 +1,6 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+
+// This assembly is currently experimental.
+[assembly: Experimental("SKEXP0040")]

dotnet/src/Functions/Functions.OpenApi/AssemblyInfo.cs

@@ -0,0 +1,6 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+
+// This assembly is currently experimental.
+[assembly: Experimental("SKEXP0042")]

dotnet/src/Functions/Functions.OpenApi/Extensions/OpenApiFunctionExecutionParameters.cs

@@ -80,7 +80,7 @@ public OpenApiFunctionExecutionParameters(
         Uri? serverUrlOverride = null,
         string userAgent = HttpHeaderValues.UserAgent,
         bool ignoreNonCompliantErrors = false,
-        bool enableDynamicOperationPayload = false,
+        bool enableDynamicOperationPayload = true,
         bool enablePayloadNamespacing = false,
         IList<string>? operationsToExclude = null)
     {

dotnet/src/Functions/Functions.OpenApi/Extensions/OpenApiKernelExtensions.cs

@@ -225,7 +225,7 @@ private static async Task<KernelPlugin> CreateOpenApiPluginAsync(
             httpClient,
             executionParameters?.AuthCallback,
             executionParameters?.UserAgent,
-            executionParameters?.EnableDynamicPayload ?? false,
+            executionParameters?.EnableDynamicPayload ?? true,
             executionParameters?.EnablePayloadNamespacing ?? false);
 
         var functions = new List<KernelFunction>();
@@ -267,7 +267,7 @@ private static KernelFunction CreateRestApiFunction(
         ILoggerFactory? loggerFactory = null)
     {
         IReadOnlyList<RestApiOperationParameter> restOperationParameters = operation.GetParameters(
-            executionParameters?.EnableDynamicPayload ?? false,
+            executionParameters?.EnableDynamicPayload ?? true,
             executionParameters?.EnablePayloadNamespacing ?? false
         );
 

dotnet/src/Functions/Functions.OpenApi/Extensions/RestApiOperationExtensions.cs

@@ -28,7 +28,7 @@ internal static class RestApiOperationExtensions
     /// <returns>The list of parameters.</returns>
     public static IReadOnlyList<RestApiOperationParameter> GetParameters(
         this RestApiOperation operation,
-        bool addPayloadParamsFromMetadata = false,
+        bool addPayloadParamsFromMetadata = true,
         bool enablePayloadNamespacing = false)
     {
         var parameters = new List<RestApiOperationParameter>(operation.Parameters);

dotnet/src/Functions/Functions.OpenApi/OpenAI/OpenAIFunctionExecutionParameters.cs

@@ -23,7 +23,7 @@ public OpenAIFunctionExecutionParameters(
         Uri? serverUrlOverride = null,
         string userAgent = HttpHeaderValues.UserAgent,
         bool ignoreNonCompliantErrors = false,
-        bool enableDynamicOperationPayload = false,
+        bool enableDynamicOperationPayload = true,
         bool enablePayloadNamespacing = false) : base(httpClient, null, serverUrlOverride, userAgent, ignoreNonCompliantErrors, enableDynamicOperationPayload, enablePayloadNamespacing)
     {
         this.AuthCallback = authCallback;

dotnet/src/Functions/Functions.UnitTests/Functions.UnitTests.csproj

@@ -8,7 +8,7 @@
     <Nullable>enable</Nullable>
     <ImplicitUsings>disable</ImplicitUsings>
     <IsPackable>false</IsPackable>
-    <NoWarn>CA2007,VSTHRD111,SKEXP0040,SKEXP0041</NoWarn>
+    <NoWarn>CA2007,VSTHRD111,SKEXP0040,SKEXP0041,SKEXP0042</NoWarn>
   </PropertyGroup>
   <Import Project="$(RepoRoot)/dotnet/src/InternalUtilities/test/TestInternalUtilities.props" />
   <ItemGroup>

dotnet/src/Functions/Functions.UnitTests/OpenApi/Extensions/KernelOpenApiPluginExtensionsTests.cs

@@ -22,6 +22,11 @@ public sealed class KernelOpenApiPluginExtensionsTests : IDisposable
     /// </summary>
     private readonly OpenApiDocumentParser _sut;
 
+    /// <summary>
+    /// OpenAPI function execution parameters.
+    /// </summary>
+    private readonly OpenApiFunctionExecutionParameters _executionParameters;
+
     /// <summary>
     /// OpenAPI document stream.
     /// </summary>
@@ -39,6 +44,8 @@ public KernelOpenApiPluginExtensionsTests()
     {
         this._kernel = new Kernel();
 
+        this._executionParameters = new OpenApiFunctionExecutionParameters() { EnableDynamicPayload = false };
+
         this._openApiDocument = ResourcePluginsProvider.LoadFromResource("documentV2_0.json");
 
         this._sut = new OpenApiDocumentParser();
@@ -48,7 +55,7 @@ public KernelOpenApiPluginExtensionsTests()
     public async Task ItCanIncludeOpenApiOperationParameterTypesIntoFunctionParametersViewAsync()
     {
         // Act
-        var plugin = await this._kernel.ImportPluginFromOpenApiAsync("fakePlugin", this._openApiDocument);
+        var plugin = await this._kernel.ImportPluginFromOpenApiAsync("fakePlugin", this._openApiDocument, this._executionParameters);
 
         // Assert
         var setSecretFunction = plugin["SetSecret"];
@@ -91,11 +98,13 @@ public async Task ItUsesServerUrlOverrideIfProvidedAsync(bool removeServersPrope
         using var messageHandlerStub = new HttpMessageHandlerStub(openApiDocument);
         using var httpClient = new HttpClient(messageHandlerStub, false);
 
-        var executionParameters = new OpenApiFunctionExecutionParameters { HttpClient = httpClient, ServerUrlOverride = new Uri(ServerUrlOverride) };
+        this._executionParameters.HttpClient = httpClient;
+        this._executionParameters.ServerUrlOverride = new Uri(ServerUrlOverride);
+
         var arguments = this.GetFakeFunctionArguments();
 
         // Act
-        var plugin = await this._kernel.ImportPluginFromOpenApiAsync("fakePlugin", new Uri(DocumentUri), executionParameters);
+        var plugin = await this._kernel.ImportPluginFromOpenApiAsync("fakePlugin", new Uri(DocumentUri), this._executionParameters);
         var setSecretFunction = plugin["SetSecret"];
 
         messageHandlerStub.ResetResponse();
@@ -121,11 +130,12 @@ public async Task ItUsesServerUrlFromOpenApiDocumentAsync(string documentFileNam
         using var messageHandlerStub = new HttpMessageHandlerStub(openApiDocument);
         using var httpClient = new HttpClient(messageHandlerStub, false);
 
-        var executionParameters = new OpenApiFunctionExecutionParameters { HttpClient = httpClient };
+        this._executionParameters.HttpClient = httpClient;
+
         var arguments = this.GetFakeFunctionArguments();
 
         // Act
-        var plugin = await this._kernel.ImportPluginFromOpenApiAsync("fakePlugin", new Uri(DocumentUri), executionParameters);
+        var plugin = await this._kernel.ImportPluginFromOpenApiAsync("fakePlugin", new Uri(DocumentUri), this._executionParameters);
         var setSecretFunction = plugin["SetSecret"];
 
         messageHandlerStub.ResetResponse();
@@ -158,11 +168,12 @@ public async Task ItUsesOpenApiDocumentHostUrlWhenServerUrlIsNotProvidedAsync(st
         using var messageHandlerStub = new HttpMessageHandlerStub(content);
         using var httpClient = new HttpClient(messageHandlerStub, false);
 
-        var executionParameters = new OpenApiFunctionExecutionParameters { HttpClient = httpClient };
+        this._executionParameters.HttpClient = httpClient;
+
         var arguments = this.GetFakeFunctionArguments();
 
         // Act
-        var plugin = await this._kernel.ImportPluginFromOpenApiAsync("fakePlugin", new Uri(documentUri), executionParameters);
+        var plugin = await this._kernel.ImportPluginFromOpenApiAsync("fakePlugin", new Uri(documentUri), this._executionParameters);
         var setSecretFunction = plugin["SetSecret"];
 
         messageHandlerStub.ResetResponse();
@@ -183,17 +194,14 @@ public async Task ItShouldRespectRunAsyncCancellationTokenOnExecutionAsync()
 
         using var httpClient = new HttpClient(messageHandlerStub, false);
 
-        var executionParameters = new OpenApiFunctionExecutionParameters
-        {
-            HttpClient = httpClient
-        };
+        this._executionParameters.HttpClient = httpClient;
 
         var fakePlugin = new FakePlugin();
 
         using var registerCancellationToken = new System.Threading.CancellationTokenSource();
         using var executeCancellationToken = new System.Threading.CancellationTokenSource();
 
-        var openApiPlugins = await this._kernel.ImportPluginFromOpenApiAsync("fakePlugin", this._openApiDocument, executionParameters, registerCancellationToken.Token);
+        var openApiPlugins = await this._kernel.ImportPluginFromOpenApiAsync("fakePlugin", this._openApiDocument, this._executionParameters, registerCancellationToken.Token);
 
         var kernel = new Kernel();
 

dotnet/src/Functions/Functions.UnitTests/OpenApi/Extensions/RestApiOperationExtensionsTests.cs

@@ -23,7 +23,7 @@ public void ItShouldAddPayloadAndContentTypeParametersByDefault(string method)
         var operation = CreateTestOperation(method, payload);
 
         //Act
-        var parameters = operation.GetParameters();
+        var parameters = operation.GetParameters(addPayloadParamsFromMetadata: false);
 
         //Assert
         Assert.NotNull(parameters);
@@ -81,7 +81,7 @@ public void ItShouldAddPayloadAndContentTypePropertiesForPlainTextContentType(st
         var operation = CreateTestOperation(method, payload);
 
         //Act
-        var parameters = operation.GetParameters();
+        var parameters = operation.GetParameters(addPayloadParamsFromMetadata: false);
 
         //Assert
         Assert.NotNull(parameters);

dotnet/src/Functions/Functions.UnitTests/OpenApi/OpenApiDocumentParserV20Tests.cs

@@ -107,7 +107,7 @@ public async Task ItCanParsePutOperationMetadataSuccessfullyAsync()
         Assert.Equal(HttpMethod.Put, putOperation.Method);
         Assert.Equal("/secrets/{secret-name}", putOperation.Path);
 
-        var parameters = putOperation.GetParameters();
+        var parameters = putOperation.GetParameters(addPayloadParamsFromMetadata: false);
         Assert.NotNull(parameters);
         Assert.True(parameters.Count >= 5);
 

dotnet/src/Functions/Functions.UnitTests/OpenApi/OpenApiDocumentParserV30Tests.cs

@@ -108,7 +108,7 @@ public async Task ItCanParsePutOperationMetadataSuccessfullyAsync()
         Assert.Equal(HttpMethod.Put, putOperation.Method);
         Assert.Equal("/secrets/{secret-name}", putOperation.Path);
 
-        var parameters = putOperation.GetParameters();
+        var parameters = putOperation.GetParameters(addPayloadParamsFromMetadata: false);
         Assert.NotNull(parameters);
         Assert.True(parameters.Count >= 5);
 

dotnet/src/Functions/Functions.UnitTests/OpenApi/OpenApiDocumentParserV31Tests.cs

@@ -108,7 +108,7 @@ public async Task ItCanParsePutOperationMetadataSuccessfullyAsync()
         Assert.Equal(HttpMethod.Put, putOperation.Method);
         Assert.Equal("/secrets/{secret-name}", putOperation.Path);
 
-        var parameters = putOperation.GetParameters();
+        var parameters = putOperation.GetParameters(addPayloadParamsFromMetadata: false);
         Assert.NotNull(parameters);
         Assert.True(parameters.Count >= 5);
 

dotnet/src/IntegrationTests/IntegrationTests.csproj

@@ -6,7 +6,7 @@
     <RollForward>LatestMajor</RollForward>
     <IsTestProject>true</IsTestProject>
     <IsPackable>false</IsPackable>
-    <NoWarn>CA2007,VSTHRD111,SKEXP0001,SKEXP0002,SKEXP0003,SKEXP0004,SKEXP0010,SKEXP0011,SKEXP0012,SKEXP0020,SKEXP0021,SKEXP0022,SKEXP0023,SKEXP0024,SKEXP0025,SKEXP0026,SKEXP0027,SKEXP0028,SKEXP0029,SKEXP0030,SKEXP0031,SKEXP0032,SKEXP0050,SKEXP0054,SKEXP0060,SKEXP0061</NoWarn>
+    <NoWarn>CA2007,VSTHRD111,SKEXP0001,SKEXP0002,SKEXP0003,SKEXP0004,SKEXP0010,SKEXP0011,SKEXP0012,SKEXP0020,SKEXP0021,SKEXP0022,SKEXP0023,SKEXP0024,SKEXP0025,SKEXP0026,SKEXP0027,SKEXP0028,SKEXP0029,SKEXP0030,SKEXP0031,SKEXP0032,SKEXP0042,SKEXP0050,SKEXP0054,SKEXP0060,SKEXP0061</NoWarn>
     <UserSecretsId>b7762d10-e29b-4bb1-8b74-b6d69a667dd4</UserSecretsId>
   </PropertyGroup>
   <ItemGroup>

dotnet/src/IntegrationTests/Plugins/PluginTests.cs

@@ -127,7 +127,7 @@ public async Task QueryInstacartPluginAsync(
         var plugin = await kernel.ImportPluginFromOpenAIAsync(
             name,
             new Uri(pluginEndpoint),
-            new OpenAIFunctionExecutionParameters(httpClient) { IgnoreNonCompliantErrors = true });
+            new OpenAIFunctionExecutionParameters(httpClient) { IgnoreNonCompliantErrors = true, EnableDynamicPayload = false });
 
         var arguments = new KernelArguments();
         arguments["payload"] = payload;
@@ -158,7 +158,7 @@ public async Task QueryInstacartPluginFromStreamAsync(
             var plugin = await kernel.ImportPluginFromOpenAIAsync(
                 name,
                 stream,
-                new OpenAIFunctionExecutionParameters(httpClient) { IgnoreNonCompliantErrors = true });
+                new OpenAIFunctionExecutionParameters(httpClient) { IgnoreNonCompliantErrors = true, EnableDynamicPayload = false });
 
             var arguments = new KernelArguments();
             arguments["payload"] = payload;
@@ -188,7 +188,7 @@ public async Task QueryInstacartPluginUsingRelativeFilePathAsync(
         var plugin = await kernel.ImportPluginFromOpenAIAsync(
             name,
             pluginFilePath,
-            new OpenAIFunctionExecutionParameters(httpClient) { IgnoreNonCompliantErrors = true });
+            new OpenAIFunctionExecutionParameters(httpClient) { IgnoreNonCompliantErrors = true, EnableDynamicPayload = false });
 
         var arguments = new KernelArguments();
         arguments["payload"] = payload;