Merge branch 'main' into obsolete-planners

Author: SergeyMenshykh

dotnet/samples/Concepts/Plugins/OpenApiPlugin_Filtering.cs

@@ -37,13 +37,15 @@ public async Task ExcludeOperationsBasedOnExclusionListAsync()
     {
         // The RepairService OpenAPI plugin being imported below includes the following operations: `listRepairs`, `createRepair`, `updateRepair`, and `deleteRepair`.
         // However, to meet our business requirements, we need to restrict state-modifying operations such as creating, updating, and deleting repairs, allowing only non-state-modifying operations like listing repairs.
-        // To enforce this restriction, we will exclude the `createRepair`, `updateRepair`, and `deleteRepair` operations from the OpenAPI document prior to importing the plugin.  
+        // To enforce this restriction, we will exclude the `createRepair`, `updateRepair`, and `deleteRepair` operations from the OpenAPI document at the plugin import time.
+        List<string> operationsToExclude = ["createRepair", "updateRepair", "deleteRepair"];
+
         OpenApiFunctionExecutionParameters executionParameters = new()
         {
-            OperationsToExclude = ["createRepair", "updateRepair", "deleteRepair"]
+            OperationSelectionPredicate = (OperationSelectionPredicateContext context) => !operationsToExclude.Contains(context.Id!)
         };
 
-        // Import the RepairService OpenAPI plugin and filter out all operations except `listRepairs` one.
+        // Import the RepairService OpenAPI plugin
         await this._kernel.ImportPluginFromOpenApiAsync(
             pluginName: "RepairService",
             filePath: "Resources/Plugins/RepairServicePlugin/repair-service.json",
@@ -70,25 +72,22 @@ await this._kernel.ImportPluginFromOpenApiAsync(
     [Fact]
     public async Task ImportOperationsBasedOnInclusionListAsync()
     {
-        OpenApiDocumentParser parser = new();
-        using StreamReader reader = System.IO.File.OpenText("Resources/Plugins/RepairServicePlugin/repair-service.json");
-
         // The RepairService OpenAPI plugin, parsed and imported below, has the following operations: `listRepairs`, `createRepair`, `updateRepair`, and `deleteRepair`.  
         // However, for our business scenario, we only want to permit the AI model to invoke the `createRepair` and `updateRepair` operations, excluding all others.
         // To accomplish this, we will define an inclusion list that specifies the allowed operations and filters out the rest.  
         List<string> operationsToInclude = ["createRepair", "updateRepair"];
 
         // The selection predicate is initialized to evaluate each operation in the OpenAPI document and include only those specified in the inclusion list. 
-        OpenApiDocumentParserOptions parserOptions = new()
+        OpenApiFunctionExecutionParameters executionParameters = new()
         {
             OperationSelectionPredicate = (OperationSelectionPredicateContext context) => operationsToInclude.Contains(context.Id!)
         };
 
-        // Parse the OpenAPI document.
-        RestApiSpecification specification = await parser.ParseAsync(stream: reader.BaseStream, options: parserOptions);
-
-        // Import the OpenAPI document specification.
-        this._kernel.ImportPluginFromOpenApi("RepairService", specification);
+        // Import the RepairService OpenAPI plugin
+        await this._kernel.ImportPluginFromOpenApiAsync(
+            pluginName: "RepairService",
+            filePath: "Resources/Plugins/RepairServicePlugin/repair-service.json",
+            executionParameters: executionParameters);
 
         // Tell the AI model not to call any function and show the list of functions it can call instead.
         OpenAIPromptExecutionSettings settings = new() { FunctionChoiceBehavior = FunctionChoiceBehavior.None() };
@@ -114,23 +113,20 @@ public async Task ImportOperationsBasedOnInclusionListAsync()
     [Fact]
     public async Task ImportOperationsBasedOnMethodAsync()
     {
-        OpenApiDocumentParser parser = new();
-        using StreamReader reader = System.IO.File.OpenText("Resources/Plugins/RepairServicePlugin/repair-service.json");
-
         // The parsed RepairService OpenAPI plugin includes operations such as `listRepairs`, `createRepair`, `updateRepair`, and `deleteRepair`.  
         // However, for our business requirements, we only permit non-state-modifying operations like listing repairs, excluding all others.  
         // To achieve this, we set up the selection predicate to evaluate each operation in the OpenAPI document, including only those with the `GET` method.  
         // Note: The selection predicate can assess operations based on operation ID, method, path, and description.  
-        OpenApiDocumentParserOptions parserOptions = new()
+        OpenApiFunctionExecutionParameters executionParameters = new()
         {
             OperationSelectionPredicate = (OperationSelectionPredicateContext context) => context.Method == "Get"
         };
 
-        // Parse the OpenAPI document.
-        RestApiSpecification specification = await parser.ParseAsync(stream: reader.BaseStream, options: parserOptions);
-
-        // Import the OpenAPI document specification.
-        this._kernel.ImportPluginFromOpenApi("RepairService", specification);
+        // Import the RepairService OpenAPI plugin
+        await this._kernel.ImportPluginFromOpenApiAsync(
+            pluginName: "RepairService",
+            filePath: "Resources/Plugins/RepairServicePlugin/repair-service.json",
+            executionParameters: executionParameters);
 
         // Tell the AI model not to call any function and show the list of functions it can call instead.
         OpenAIPromptExecutionSettings settings = new() { FunctionChoiceBehavior = FunctionChoiceBehavior.None() };

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

@@ -62,9 +62,18 @@ public class OpenApiFunctionExecutionParameters
     /// <summary>
     /// Optional list of HTTP operations to skip when importing the OpenAPI document.
     /// </summary>
-    [Experimental("SKEXP0040")]
+    [Obsolete("Use OperationSelectionPredicate instead.")]
     public IList<string> OperationsToExclude { get; set; }
 
+    /// <summary>
+    /// Operation selection predicate to apply to all OpenAPI document operations.
+    /// If set, the predicate will be applied to each operation in the document.
+    /// If the predicate returns true, the operation will be imported; otherwise, it will be skipped.
+    /// This can be used to import or filter operations based on various operation properties: Id, Path, Method, and Description.
+    /// </summary>
+    [Experimental("SKEXP0040")]
+    public Func<OperationSelectionPredicateContext, bool>? OperationSelectionPredicate { get; set; }
+
     /// <summary>
     /// A custom HTTP response content reader. It can be useful when the internal reader
     /// for a specific content type is either missing, insufficient, or when custom behavior is desired.
@@ -128,6 +137,8 @@ public OpenApiFunctionExecutionParameters(
         this.IgnoreNonCompliantErrors = ignoreNonCompliantErrors;
         this.EnableDynamicPayload = enableDynamicOperationPayload;
         this.EnablePayloadNamespacing = enablePayloadNamespacing;
+#pragma warning disable CS0618 // Type or member is obsolete
         this.OperationsToExclude = operationsToExclude ?? [];
+#pragma warning restore CS0618 // Type or member is obsolete
     }
 }

dotnet/src/Functions/Functions.OpenApi/OpenApiKernelPluginFactory.cs

@@ -179,10 +179,7 @@ internal static async Task<KernelPlugin> CreateOpenApiPluginAsync(
             options: new OpenApiDocumentParserOptions
             {
                 IgnoreNonCompliantErrors = executionParameters?.IgnoreNonCompliantErrors ?? false,
-                OperationSelectionPredicate = (context) =>
-                {
-                    return !executionParameters?.OperationsToExclude.Contains(context.Id ?? string.Empty) ?? true;
-                }
+                OperationSelectionPredicate = (context) => SelectOperations(context, executionParameters)
             },
             cancellationToken: cancellationToken).ConfigureAwait(false);
 
@@ -420,6 +417,29 @@ private static string ConvertOperationIdToValidFunctionName(string operationId,
         return result;
     }
 
+    /// <summary>
+    /// Selects operations to parse and import.
+    /// </summary>
+    /// <param name="context">Operation selection context.</param>
+    /// <param name="executionParameters">Execution parameters.</param>
+    /// <returns>True if the operation should be selected; otherwise, false.</returns>
+    private static bool SelectOperations(OperationSelectionPredicateContext context, OpenApiFunctionExecutionParameters? executionParameters)
+    {
+#pragma warning disable CS0618 // Type or member is obsolete
+        if (executionParameters?.OperationSelectionPredicate is not null && executionParameters?.OperationsToExclude is { Count: > 0 })
+        {
+            throw new ArgumentException($"{nameof(executionParameters.OperationSelectionPredicate)} and {nameof(executionParameters.OperationsToExclude)} cannot be used together.");
+        }
+
+        if (executionParameters?.OperationSelectionPredicate is { } predicate)
+        {
+            return predicate(context);
+        }
+
+        return !executionParameters?.OperationsToExclude.Contains(context.Id ?? string.Empty) ?? true;
+#pragma warning restore CS0618 // Type or member is obsolete
+    }
+
     /// <summary>
     /// Converts the parameter type to a C# <see cref="Type"/> object.
     /// </summary>

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

@@ -7,7 +7,7 @@
     <Nullable>enable</Nullable>
     <ImplicitUsings>disable</ImplicitUsings>
     <IsPackable>false</IsPackable>
-    <NoWarn>$(NoWarn);CA2007,CA1861,CA1869,VSTHRD111,CS1591,SKEXP0040,SKEXP0001</NoWarn>
+    <NoWarn>$(NoWarn);CA2007,CA1861,CA1869,VSTHRD111,CS1591,CS0618,SKEXP0040,SKEXP0001</NoWarn>
   </PropertyGroup>
   <Import Project="$(RepoRoot)/dotnet/src/InternalUtilities/test/TestInternalUtilities.props" />
   <ItemGroup>

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

@@ -643,6 +643,38 @@ async Task<RestApiOperationResponse> RestApiOperationResponseFactory(RestApiOper
         Assert.True(restApiOperationResponseFactoryIsInvoked);
     }
 
+    [Fact]
+    public async Task ItCanImportSpecifiedOperationsAsync()
+    {
+        // Arrange
+        string[] operationsToInclude = ["GetSecret", "SetSecret"];
+
+        this._executionParameters.OperationSelectionPredicate = (context) => operationsToInclude.Contains(context.Id);
+
+        // Act
+        var plugin = await OpenApiKernelPluginFactory.CreateFromOpenApiAsync("fakePlugin", this._openApiDocument, this._executionParameters);
+
+        // Assert
+        Assert.Equal(2, plugin.Count());
+        Assert.Contains(plugin, p => p.Name == "GetSecret");
+        Assert.Contains(plugin, p => p.Name == "SetSecret");
+    }
+
+    [Fact]
+    public async Task ItCanFilterOutSpecifiedOperationsAsync()
+    {
+        // Arrange
+        this._executionParameters.OperationsToExclude = ["GetSecret", "SetSecret"];
+
+        // Act
+        var plugin = await OpenApiKernelPluginFactory.CreateFromOpenApiAsync("fakePlugin", this._openApiDocument, this._executionParameters);
+
+        // Assert
+        Assert.True(plugin.Any());
+        Assert.DoesNotContain(plugin, p => p.Name == "GetSecret");
+        Assert.DoesNotContain(plugin, p => p.Name == "SetSecret");
+    }
+
     /// <summary>
     /// Generate theory data for ItAddSecurityMetadataToOperationAsync
     /// </summary>