Microsoft Power Fx Documentation

The Power Fx IR is a refined Intermediate Representation designed to simplify backend consumption (such as SQL for CDS or JSTranslator). It normalizes complex Power Fx logic into explicit nodes to prevent backends from having to reimplement core logic like coercion matrices or operator overloading.

Key normalization features include:

• Explicit Coercion: Coercion is represented as an explicit node using a single flattened enum, rather than requiring backends to implement a complex coercion matrix.
• Operator Normalization: Operators that can function as both operators and functions (e.g., And, Or, Power, Concatenate) are normalized to function representations.
• Symbol Binding: The As keyword is treated as a symbol binding mechanism that does not impact code generation.
• Lazy Evaluation: Function parameters that are not always evaluated are represented using Lambda nodes.

When a Power Fx formula calls an action connector function, the following pipeline is executed:

1. Parameter Binding: HttpFunctionInvoker.ConvertToNamedParameters converts positional FormulaValue[] arguments into a Dictionary<string, FormulaValue>, handling optional arguments and defaults.
2. Request Building: HttpFunctionInvoker.BuildRequest constructs the HttpRequestMessage:
   • Parameters: Places values in Path, Query, Header, or Cookie based on the OpenAPI spec.
   • Formatting: Converts DateTimeValue to ISO 8601 UTC (yyyy-MM-ddTHH:mm:ss.fffZ) and DateValue to yyyy-MM-dd.
   • Body: Selects a FormulaValueSerializer based on the Content-Type (JSON, Form, Text, or Multipart).
   • Placeholders: Substitutes {connectionId}-style placeholders using GlobalContext.ConnectorValues.
3. Execution: The request is sent via _httpClient.SendAsync.
4. Decoding: HttpFunctionInvoker.DecodeResponseAsync inspects the status code. If successful, it uses FormulaValueJSON.FromJson to materialize the response against the function's ReturnType. On HTTP errors, it returns an ErrorValue containing an HttpExpressionError (unless throwOnError is configured).

This example demonstrates how to load an OpenAPI document, register it as an action connector in a PowerFxConfig, set up the required RuntimeConfig with a custom BaseRuntimeConnectorContext, and evaluate a formula using the RecalcEngine.

using System;
using System.IO;
using System.Net.Http;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.OpenApi.Readers;
using Microsoft.PowerFx;
using Microsoft.PowerFx.Connectors;
using Microsoft.PowerFx.Types;

public static class ActionConnectorSample
{
    public static async Task RunAsync()
    {
        // 1. Load the swagger.
        using var stream = File.OpenRead("MyConnector.swagger.json");
        var openApiDoc = new OpenApiStreamReader().Read(stream, out _);

        // 2. Create a PowerFxConfig and register the connector.
        var config = new PowerFxConfig();
        var settings = new ConnectorSettings("MyConnector")
        {
            IncludeInternalFunctions = false,
            AllowUnsupportedFunctions = false,
        };

        // OpenApiParser.GetFunctions is called under the hood by AddActionConnector.
        IReadOnlyList<ConnectorFunction> functions =
            config.AddActionConnector(settings, openApiDoc, new ConsoleLogger());

        // 3. Build an HttpMessageInvoker that will actually make the network call.
        using var httpClient = new HttpClient();

        // 4. Create a RuntimeConfig with the connector runtime context.
        var runtimeCtx = new MyConnectorRuntimeContext("MyConnector", httpClient);
        var runtimeConfig = new RuntimeConfig().AddRuntimeContext(runtimeCtx);

        // 5. Evaluate a Power Fx expression that uses the generated function.
        var engine = new RecalcEngine(config);
        var result = await engine.EvalAsync(
            @"MyConnector.SendEmail({ to: ""a@b.com"", subject: ""Hi"" })",
            CancellationToken.None,
            options: new ParserOptions { AllowsSideEffects = true },
            runtimeConfig: runtimeConfig);

        Console.WriteLine(result.ToObject());
    }

    private sealed class MyConnectorRuntimeContext : BaseRuntimeConnectorContext
    {
        private readonly string _ns;
        private readonly HttpMessageInvoker _invoker;
        public MyConnectorRuntimeContext(string ns, HttpMessageInvoker invoker) { _ns = ns; _invoker = invoker; }
        public override HttpMessageInvoker GetInvoker(string @namespace) => _invoker;
        public override TimeZoneInfo TimeZoneInfo => TimeZoneInfo.Utc;
    }
}