diff --git a/src/libraries/Microsoft.PowerFx.Connectors/ConnectorConstants.cs b/src/libraries/Microsoft.PowerFx.Connectors/ConnectorConstants.cs index aec5803278..ef64b6a462 100644 --- a/src/libraries/Microsoft.PowerFx.Connectors/ConnectorConstants.cs +++ b/src/libraries/Microsoft.PowerFx.Connectors/ConnectorConstants.cs @@ -2,33 +2,139 @@ // Licensed under the MIT license. namespace Microsoft.PowerFx.Connectors { + /// + /// Contains constant values for x-ms-* OpenAPI extensions used in connectors. + /// public static class Constants { + /// + /// The x-ms-ai-sensitivity extension name. + /// public const string XMsAiSensitivity = "x-ms-ai-sensitivity"; + + /// + /// The x-bodyName extension name. + /// public const string XMsBodyName = "x-bodyName"; + + /// + /// The x-ms-capabilities extension name. + /// public const string XMsCapabilities = "x-ms-capabilities"; + + /// + /// The x-ms-dynamic-list extension name. + /// public const string XMsDynamicList = "x-ms-dynamic-list"; + + /// + /// The x-ms-dynamic-properties extension name. + /// public const string XMsDynamicProperties = "x-ms-dynamic-properties"; + + /// + /// The x-ms-dynamic-schema extension name. + /// public const string XMsDynamicSchema = "x-ms-dynamic-schema"; + + /// + /// The x-ms-dynamic-values extension name. + /// public const string XMsDynamicValues = "x-ms-dynamic-values"; + + /// + /// The x-ms-enum extension name. + /// public const string XMsEnum = "x-ms-enum"; + + /// + /// The x-ms-enum-display-name extension name. + /// public const string XMsEnumDisplayName = "x-ms-enum-display-name"; + + /// + /// The x-ms-enum-values extension name. + /// public const string XMsEnumValues = "x-ms-enum-values"; + + /// + /// The x-ms-explicit-input extension name. + /// public const string XMsExplicitInput = "x-ms-explicit-input"; + + /// + /// The x-ms-keyOrder extension name. + /// public const string XMsKeyOrder = "x-ms-keyOrder"; + + /// + /// The x-ms-keyType extension name. + /// public const string XMsKeyType = "x-ms-keyType"; + + /// + /// The x-ms-media-kind extension name. + /// public const string XMsMediaKind = "x-ms-media-kind"; + + /// + /// The x-ms-notification-content extension name. + /// public const string XMsNotificationContent = "x-ms-notification-content"; + + /// + /// The x-ms-notification-url extension name. + /// public const string XMsNotificationUrl = "x-ms-notification-url"; + + /// + /// The x-ms-pageable extension name. + /// public const string XMsPageable = "x-ms-pageable"; + + /// + /// The x-ms-permission extension name. + /// public const string XMsPermission = "x-ms-permission"; + + /// + /// The x-ms-property-entity-type extension name. + /// public const string XMsPropertyEntityType = "x-ms-property-entity-type"; + + /// + /// The x-ms-relationships extension name. + /// public const string XMsRelationships = "x-ms-relationships"; + + /// + /// The x-ms-require-user-confirmation extension name. + /// public const string XMsRequireUserConfirmation = "x-ms-require-user-confirmation"; + + /// + /// The x-ms-sort extension name. + /// public const string XMsSort = "x-ms-sort"; + + /// + /// The x-ms-summary extension name. + /// public const string XMsSummary = "x-ms-summary"; + + /// + /// The x-ms-trigger extension name. + /// public const string XMsTrigger = "x-ms-trigger"; + + /// + /// The x-ms-url-encoding extension name. + /// public const string XMsUrlEncoding = "x-ms-url-encoding"; + + /// + /// The x-ms-visibility extension name. + /// public const string XMsVisibility = "x-ms-visibility"; } } diff --git a/src/libraries/Microsoft.PowerFx.Connectors/Public/AiSensitivity.cs b/src/libraries/Microsoft.PowerFx.Connectors/Public/AiSensitivity.cs index a1fc1d0b0a..8bd84bc9e6 100644 --- a/src/libraries/Microsoft.PowerFx.Connectors/Public/AiSensitivity.cs +++ b/src/libraries/Microsoft.PowerFx.Connectors/Public/AiSensitivity.cs @@ -3,18 +3,29 @@ namespace Microsoft.PowerFx.Connectors { + /// + /// "x-ms-ai-sensitivity" enum. + /// public enum AiSensitivity : int { - // "x-ms-ai-sensitivity" is not corresponding to any valid value (normally, only "low", "high") + /// + /// "x-ms-ai-sensitivity" is not corresponding to any valid value (normally, only "low", "high") + /// Unknown = -1, - // "x-ms-ai-sensitivity" is not defined + /// + /// "x-ms-ai-sensitivity" is not defined + /// None = 0, - // "x-ms-ai-sensitivity" is "low" + /// + /// "x-ms-ai-sensitivity" is "low" + /// Low, - // "x-ms-ai-sensitivity" is "high" + /// + /// "x-ms-ai-sensitivity" is "high" + /// High } } diff --git a/src/libraries/Microsoft.PowerFx.Connectors/Public/BaseRuntimeConnectorContext.cs b/src/libraries/Microsoft.PowerFx.Connectors/Public/BaseRuntimeConnectorContext.cs index 4f1b7fa7fc..66ade2fd5b 100644 --- a/src/libraries/Microsoft.PowerFx.Connectors/Public/BaseRuntimeConnectorContext.cs +++ b/src/libraries/Microsoft.PowerFx.Connectors/Public/BaseRuntimeConnectorContext.cs @@ -6,12 +6,24 @@ namespace Microsoft.PowerFx.Connectors { + /// + /// Base class for runtime connector context. + /// public abstract class BaseRuntimeConnectorContext { + /// + /// Gets the HTTP message invoker for the specified namespace. + /// public abstract HttpMessageInvoker GetInvoker(string @namespace); + /// + /// Gets the time zone information. + /// public abstract TimeZoneInfo TimeZoneInfo { get; } + /// + /// Gets a value indicating whether to throw on error. + /// public virtual bool ThrowOnError { get; } = false; internal virtual bool ReturnRawResults { get; } = false; @@ -24,8 +36,14 @@ internal BaseRuntimeConnectorContext WithRawResults() } } + /// + /// Extension methods for runtime connector context. + /// public static class RuntimeConnectorContextExtensions { + /// + /// Adds a runtime context to the service provider. + /// public static BasicServiceProvider AddRuntimeContext(this BasicServiceProvider serviceProvider, BaseRuntimeConnectorContext context) { return serviceProvider.AddService(typeof(BaseRuntimeConnectorContext), context); diff --git a/src/libraries/Microsoft.PowerFx.Connectors/Public/CdpExtensions.cs b/src/libraries/Microsoft.PowerFx.Connectors/Public/CdpExtensions.cs index 545a87cd21..86ed9bb6df 100644 --- a/src/libraries/Microsoft.PowerFx.Connectors/Public/CdpExtensions.cs +++ b/src/libraries/Microsoft.PowerFx.Connectors/Public/CdpExtensions.cs @@ -5,8 +5,14 @@ namespace Microsoft.PowerFx.Connectors { + /// + /// Extension methods for CDP-related types. + /// public static class CdpExtensions { + /// + /// Tries to get the external table name and foreign key for a field in a RecordType. + /// public static bool TryGetFieldExternalTableName(this RecordType recordType, string fieldName, out string tableName, out string foreignKey) { if (recordType is not CdpRecordType cdpRecordType) diff --git a/src/libraries/Microsoft.PowerFx.Connectors/Public/CdpTableValue.cs b/src/libraries/Microsoft.PowerFx.Connectors/Public/CdpTableValue.cs index da311dc3e1..30b138ddc6 100644 --- a/src/libraries/Microsoft.PowerFx.Connectors/Public/CdpTableValue.cs +++ b/src/libraries/Microsoft.PowerFx.Connectors/Public/CdpTableValue.cs @@ -15,10 +15,14 @@ namespace Microsoft.PowerFx.Connectors { - // Created by TabularService.GetTableValue - // Doesn't contain any ServiceProvider which is runtime only + /// + /// Represents a table value created by TabularService.GetTableValue. Does not contain any ServiceProvider which is runtime only. + /// public class CdpTableValue : TableValue, IRefreshable, IDelegatableTableValue { + /// + /// Gets a value indicating whether the table is delegable. + /// public bool IsDelegable => _tabularService.IsDelegable; protected internal readonly CdpService _tabularService; @@ -48,6 +52,9 @@ internal CdpTableValue(IRContext irContext) _cachedRows = null; } + /// + /// Gets the rows of the table, fetching and caching them if necessary. + /// public override IEnumerable> Rows { get @@ -67,6 +74,9 @@ public override IEnumerable> Rows } } + /// + /// Gets the supported delegation features for this table. + /// public DelegationParameterFeatures SupportedFeatures => DelegationParameterFeatures.Filter | DelegationParameterFeatures.Top | DelegationParameterFeatures.Columns | // $select @@ -75,17 +85,26 @@ public override IEnumerable> Rows DelegationParameterFeatures.ApplyTopLevelAggregation | DelegationParameterFeatures.Count; + /// + /// Asynchronously gets the rows of the table. + /// public async Task>> GetRowsAsync(IServiceProvider services, DelegationParameters parameters, CancellationToken cancel) { var rows = await _tabularService.GetItemsAsync(services, parameters, cancel).ConfigureAwait(false); return rows; } + /// + /// Refreshes the cached rows. + /// public void Refresh() { _cachedRows = null; } + /// + /// Asynchronously executes a query and returns the result as a FormulaValue. + /// public async Task ExecuteQueryAsync(IServiceProvider services, DelegationParameters parameters, CancellationToken cancel) { if (parameters == null) diff --git a/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorEnhancedSuggestions.cs b/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorEnhancedSuggestions.cs index 322d04e8de..55b924e9d6 100644 --- a/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorEnhancedSuggestions.cs +++ b/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorEnhancedSuggestions.cs @@ -6,11 +6,19 @@ namespace Microsoft.PowerFx.Connectors { - // Wraps ConnectorSuggestions (defined in PFx.Core) to add ConnectorType (Pfx.Connectors only) + /// + /// Wraps ConnectorSuggestions to add ConnectorType for enhanced suggestions. + /// public class ConnectorEnhancedSuggestions { + /// + /// Gets the connector type associated with the suggestions. + /// public ConnectorType ConnectorType { get; } + /// + /// Gets the connector suggestions. + /// public ConnectorSuggestions ConnectorSuggestions { get; } internal ConnectorEnhancedSuggestions(SuggestionMethod suggestionMethod, IReadOnlyList suggestions, ConnectorType connectorType = null) diff --git a/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorKeyType.cs b/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorKeyType.cs index dca8c6795e..bbb5d54cb8 100644 --- a/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorKeyType.cs +++ b/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorKeyType.cs @@ -3,15 +3,24 @@ namespace Microsoft.PowerFx.Connectors { - // x-ms-keyType + /// + /// Specifies the key type for a connector (x-ms-keyType). + /// public enum ConnectorKeyType { + /// + /// Undefined key type. + /// Undefined = -1, - // "primary" + /// + /// Primary key type. + /// Primary, - // "none" + /// + /// No key type. + /// None } } diff --git a/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorLogger.cs b/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorLogger.cs index 9c60b52427..611499d370 100644 --- a/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorLogger.cs +++ b/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorLogger.cs @@ -5,30 +5,48 @@ namespace Microsoft.PowerFx.Connectors { + /// + /// Logger for connector operations. + /// public abstract class ConnectorLogger { protected abstract void Log(ConnectorLog log); + /// + /// Logs an informational message. + /// public virtual void LogInformation(string message) { Log(new ConnectorLog(LogCategory.Information, message)); } + /// + /// Logs a debug message. + /// public virtual void LogDebug(string message) { Log(new ConnectorLog(LogCategory.Debug, message)); } + /// + /// Logs an error message. + /// public virtual void LogError(string message) { Log(new ConnectorLog(LogCategory.Error, message)); } + /// + /// Logs a warning message. + /// public virtual void LogWarning(string message) { Log(new ConnectorLog(LogCategory.Warning, message)); } + /// + /// Logs an exception with a message. + /// public virtual void LogException(Exception ex, string message) { Log(new ConnectorLog(LogCategory.Exception, message, ex)); diff --git a/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorParameter.cs b/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorParameter.cs index 6058fd5983..d14d655097 100644 --- a/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorParameter.cs +++ b/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorParameter.cs @@ -13,11 +13,19 @@ namespace Microsoft.PowerFx.Connectors [DebuggerDisplay("{Name} {ConnectorType}")] public class ConnectorParameter : ConnectorSchema { + /// + /// Gets the name of the parameter. + /// public string Name { get; private set; } + /// + /// Gets the description of the parameter. + /// public string Description { get; } - // Query, Header, Path or Cookie (not supported yet) + /// + /// Gets the location of the parameter (Query, Header, Path, or Cookie). + /// public ParameterLocation? Location { get; } internal bool IsBodyParameter = false; diff --git a/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorParameterWithSuggestions.cs b/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorParameterWithSuggestions.cs index 48cd10ddb3..6273850d6e 100644 --- a/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorParameterWithSuggestions.cs +++ b/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorParameterWithSuggestions.cs @@ -8,6 +8,9 @@ namespace Microsoft.PowerFx.Connectors { + /// + /// Represents a connector parameter with suggestions and values. + /// public class ConnectorParameterWithSuggestions : ConnectorParameter { /// diff --git a/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorParameters.cs b/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorParameters.cs index d7d70ba8d4..9485cf8bde 100644 --- a/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorParameters.cs +++ b/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorParameters.cs @@ -3,6 +3,9 @@ namespace Microsoft.PowerFx.Connectors { + /// + /// Represents a set of connector parameters. + /// public class ConnectorParameters { /// @@ -10,6 +13,9 @@ public class ConnectorParameters /// public bool IsCompleted { get; internal set; } + /// + /// Gets the parameters with suggestions. + /// public ConnectorParameterWithSuggestions[] ParametersWithSuggestions { get; internal set; } } } diff --git a/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorPermission.cs b/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorPermission.cs index 167588b9ef..e59767f48c 100644 --- a/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorPermission.cs +++ b/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorPermission.cs @@ -3,14 +3,24 @@ namespace Microsoft.PowerFx.Connectors { + /// + /// Defines permission levels for a connector. + /// public enum ConnectorPermission { + /// + /// Undefined permission. + /// Undefined = -1, - // "read-only" + /// + /// Read-only permission. + /// PermissionReadOnly, - // "read-write" + /// + /// Read-write permission. + /// PermissionReadWrite } } diff --git a/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorSchema.cs b/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorSchema.cs index 90b3085d25..1498e683be 100644 --- a/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorSchema.cs +++ b/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorSchema.cs @@ -6,11 +6,20 @@ namespace Microsoft.PowerFx.Connectors { + /// + /// Represents the schema of a connector parameter or type. + /// [DebuggerDisplay("{ConnectorType}")] public class ConnectorSchema : SupportsConnectorErrors { + /// + /// Gets the connector type. + /// public ConnectorType ConnectorType { get; } + /// + /// Gets the default value for the parameter or type. + /// public FormulaValue DefaultValue { get; } internal ISwaggerSchema Schema { get; } @@ -19,20 +28,41 @@ public class ConnectorSchema : SupportsConnectorErrors private bool UseHiddenTypes { get; } + /// + /// Gets the title of the connector. + /// public string Title => Schema.Title; + /// + /// Gets the formula type, considering hidden types if applicable. + /// public FormulaType FormulaType => UseHiddenTypes ? ConnectorType.HiddenRecordType : ConnectorType.FormulaType; internal RecordType HiddenRecordType => ConnectorType.HiddenRecordType; + /// + /// Gets the summary of the connector. + /// public string Summary => ConnectorExtensions.Summary; + /// + /// Indicates whether dynamic intellisense is supported. + /// public bool SupportsDynamicIntellisense => ConnectorType.SupportsDynamicIntellisense; + /// + /// Gets the notification URL, if available. + /// public bool? NotificationUrl => ConnectorType.NotificationUrl; + /// + /// Gets the AI sensitivity level. + /// public AiSensitivity AiSensitivity => ConnectorType.AiSensitivity; + /// + /// Gets the property entity type. + /// public string PropertyEntityType => ConnectorType.PropertyEntityType; internal ConnectorSchema(ISwaggerParameter openApiParameter, ISwaggerExtensions bodyExtensions, bool useHiddenTypes, ConnectorSettings settings) diff --git a/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorSettings.cs b/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorSettings.cs index ccb37e7904..796ba02909 100644 --- a/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorSettings.cs +++ b/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorSettings.cs @@ -1,21 +1,24 @@ -// Copyright (c) Microsoft Corporation. -// Licensed under the MIT license. - -using System; - -namespace Microsoft.PowerFx.Connectors -{ - /// - /// Settings for a connector. +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +using System; + +namespace Microsoft.PowerFx.Connectors +{ + /// + /// Settings for a connector. /// - [ThreadSafeImmutable] - public class ConnectorSettings + [ThreadSafeImmutable] + public class ConnectorSettings { /// /// Default number of rows to return for connector, per page. I.E. $top=1000. /// internal const int DefaultConnectorTop = 1000; + /// + /// Creates a new instance of ConnectorSettings for CDP connectors. + /// public static ConnectorSettings NewCDPConnectorSettings(bool extractSensitivityLabel = false, string purviewAccountName = null, int maxRows = DefaultConnectorTop) { var connectorSettings = new ConnectorSettings(null) @@ -31,19 +34,22 @@ public static ConnectorSettings NewCDPConnectorSettings(bool extractSensitivityL return connectorSettings; } - public ConnectorSettings(string @namespace) - { - Namespace = @namespace; - } - - /// - /// Namespace of the connector. - /// - public string Namespace { get; } - - /// - /// Maximum number of rows to return, per page. - /// + /// + /// Initializes a new instance of the class. + /// + public ConnectorSettings(string @namespace) + { + Namespace = @namespace; + } + + /// + /// Namespace of the connector. + /// + public string Namespace { get; } + + /// + /// Maximum number of rows to return, per page. + /// public int MaxRows { get; init; } = DefaultConnectorTop; /// @@ -51,17 +57,17 @@ public ConnectorSettings(string @namespace) /// internal bool ExtractSensitivityLabel { get; init; } = false; - internal string PurviewAccountName { get; init; } - - /// - /// Unknown extensions in swagger file are ignored by default during the validation process. - /// - public bool FailOnUnknownExtension { get; init; } = false; - - /// - /// Allow using functions that are identified as unsupported. - /// NotSupportedReason property will still be specified. - /// + internal string PurviewAccountName { get; init; } + + /// + /// Unknown extensions in swagger file are ignored by default during the validation process. + /// + public bool FailOnUnknownExtension { get; init; } = false; + + /// + /// Allow using functions that are identified as unsupported. + /// NotSupportedReason property will still be specified. + /// public bool AllowUnsupportedFunctions { get; init; } = false; /// @@ -70,16 +76,16 @@ public ConnectorSettings(string @namespace) /// public bool AllowSuggestionMappingFallback { get; init; } = false; - /// + /// /// Include webhook functions that contain "x-ms-notification-content" in definition. - /// By default these functions won't be accessible by end users. - /// + /// By default these functions won't be accessible by end users. + /// public bool IncludeWebhookFunctions { get; init; } = false; - /// - /// By default these functions won't be accessible by end users. - /// Internally, internal functions will be kept (ConnectorFunction.FunctionList) as some of those are used for dynamic intellisense. - /// + /// + /// By default these functions won't be accessible by end users. + /// Internally, internal functions will be kept (ConnectorFunction.FunctionList) as some of those are used for dynamic intellisense. + /// public bool IncludeInternalFunctions { get; init; } = false; /// @@ -94,12 +100,12 @@ public bool ExposeInternalParamsWithoutDefaultValue } private bool _exposeInternalParamsWithoutDefaultValue = false; - - /// - /// In Power Apps, all record fields which are not declared in the swagger file will not be part of the Power Fx response. - /// ReturnUnknownRecordFieldsAsUntypedObjects modifies this behavior to return all unknown fields as UntypedObjects. - /// This flag is only working when Compatibility is set to ConnectorCompatibility.SwaggerCompatibility or ConnectorCompatibility.CdpCompatibility. - /// + + /// + /// In Power Apps, all record fields which are not declared in the swagger file will not be part of the Power Fx response. + /// ReturnUnknownRecordFieldsAsUntypedObjects modifies this behavior to return all unknown fields as UntypedObjects. + /// This flag is only working when Compatibility is set to ConnectorCompatibility.SwaggerCompatibility or ConnectorCompatibility.CdpCompatibility. + /// public bool ReturnUnknownRecordFieldsAsUntypedObjects { get; init; } = false; /// @@ -112,8 +118,8 @@ public bool ExposeInternalParamsWithoutDefaultValue /// This flag will force all enums to be returns as FormulaType.String or FormulaType.Decimal regardless of x-ms-enum-*. /// This flag is only in effect when SupportXMsEnumValues is true. /// - public bool ReturnEnumsAsPrimitive { get; init; } = false; - + public bool ReturnEnumsAsPrimitive { get; init; } = false; + /// /// This flag enables some special handling for the body parameter, when /// - body name is 'item' @@ -121,28 +127,34 @@ public bool ExposeInternalParamsWithoutDefaultValue /// - there is only one property in inner object /// In that base the body will be fully flattened and we will retain the 'body' name for the parameter. /// - public bool UseItemDynamicPropertiesSpecialHandling { get; init; } = false; - - public ConnectorCompatibility Compatibility { get; init; } = ConnectorCompatibility.Default; - } - - public enum ConnectorCompatibility - { - Default = PowerAppsCompatibility, - - // Power Apps Compatibility - // - required parameters can be reordered based on their locations - // - required internal visible parameters with defaults are required - PowerAppsCompatibility = 1, - - // Swagger File Conformity - // - parameters appear in the order specified in the swagger file - // - internal visible parameters are completely hidden (required/optional, with or without default value) - SwaggerCompatibility = 2, - - // Swagger File Conformity for CDP connectors - // - same as Swagger File Conformity - // - does not require format="enum" for identifying enumerations - CdpCompatibility = 3 - } -} + public bool UseItemDynamicPropertiesSpecialHandling { get; init; } = false; + + public ConnectorCompatibility Compatibility { get; init; } = ConnectorCompatibility.Default; + } + + /// + /// Specifies compatibility modes for connectors. + /// + public enum ConnectorCompatibility + { + /// + /// Default compatibility mode (PowerAppsCompatibility). + /// + Default = PowerAppsCompatibility, + + // Power Apps Compatibility + // - required parameters can be reordered based on their locations + // - required internal visible parameters with defaults are required + PowerAppsCompatibility = 1, + + // Swagger File Conformity + // - parameters appear in the order specified in the swagger file + // - internal visible parameters are completely hidden (required/optional, with or without default value) + SwaggerCompatibility = 2, + + // Swagger File Conformity for CDP connectors + // - same as Swagger File Conformity + // - does not require format="enum" for identifying enumerations + CdpCompatibility = 3 + } +} diff --git a/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorType.cs b/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorType.cs index f2c14d04b0..3f7af3aeba 100644 --- a/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorType.cs +++ b/src/libraries/Microsoft.PowerFx.Connectors/Public/ConnectorType.cs @@ -16,47 +16,72 @@ namespace Microsoft.PowerFx.Connectors { - // Wrapper class around FormulaType and ConnectorType - // FormulaType is used to represent the type of the parameter in the Power Fx expression as used in Power Apps - // ConnectorType contains more details information coming from the swagger file and extensions + /// + /// Wrapper class around FormulaType and ConnectorType. Contains detailed information from the swagger file and extensions. + /// [DebuggerDisplay("{FormulaType._type}")] public class ConnectorType : SupportsConnectorErrors { - // "name" + /// + /// Gets the name of the connector type. + /// public string Name { get; internal set; } - // "x-ms-summary" or "title" + /// + /// Gets the display name ("x-ms-summary" or "title"). + /// public string DisplayName { get; } - // "description" + /// + /// Gets the description. + /// public string Description { get; } - // "required" + /// + /// Gets a value indicating whether the field is required. + /// public bool IsRequired { get; internal set; } - // Only used for RecordType and TableType + /// + /// Gets the fields for RecordType and TableType. + /// public ConnectorType[] Fields { get; } internal ConnectorType[] HiddenFields { get; } - // FormulaType + /// + /// Gets the formula type. + /// public FormulaType FormulaType { get; private set; } - // "x-ms-explicit-input" + /// + /// Gets a value indicating whether the input is explicit ("x-ms-explicit-input"). + /// public bool ExplicitInput { get; } + /// + /// Gets a value indicating whether this type is an enum. + /// public bool IsEnum { get; } - // Enumeration value, only defined if IsEnum is true + /// + /// Gets the enumeration values, only defined if IsEnum is true. + /// public FormulaValue[] EnumValues { get; } - // Enumeration display name ("x-ms-enum-display-name"), only defined if IsEnum is true - // If not defined, this array will be empty + /// + /// Gets the enumeration display names ("x-ms-enum-display-name"), only defined if IsEnum is true. + /// public string[] EnumDisplayNames { get; } + /// + /// Gets the enum dictionary. + /// public Dictionary Enum => GetEnum(); - // Supports x-ms-visibility + /// + /// Gets the visibility (supports x-ms-visibility). + /// public Visibility Visibility { get; internal set; } // Supports x-ms-capabilities @@ -65,41 +90,66 @@ public class ConnectorType : SupportsConnectorErrors // Supports x-ms-relationships internal Dictionary Relationships { get; } - // Supports x-ms-keyType + /// + /// Gets the key type (supports x-ms-keyType). + /// public ConnectorKeyType KeyType { get; } - // Supports x-ms-keyOrder (only valid if KeyType = Primary) + /// + /// Gets the key order (supports x-ms-keyOrder, only valid if KeyType = Primary). + /// public double KeyOrder { get; } + /// + /// Gets the permission. + /// public ConnectorPermission Permission { get; } - // Supports x-ms-notification-url + /// + /// Gets a value indicating whether notification URL is supported (supports x-ms-notification-url). + /// public bool? NotificationUrl { get; } - // Supports x-ms-ai-sensitivity + /// + /// Gets the AI sensitivity (supports x-ms-ai-sensitivity). + /// public AiSensitivity AiSensitivity { get; } - // Supports x-ms-property-entity-type + /// + /// Gets the property entity type (supports x-ms-property-entity-type). + /// public string PropertyEntityType { get; } internal RecordType HiddenRecordType { get; } - // Supports x-ms-dynamic-values or -list locally + /// + /// Gets a value indicating whether dynamic values or list are supported locally. + /// public bool SupportsDynamicValuesOrList => DynamicValues != null || DynamicList != null; - // Supports x-ms-dynamic-values or -list locally or anywhere in the tree + /// + /// Gets a value indicating whether dynamic values or list are supported locally or anywhere in the tree. + /// public bool ContainsDynamicValuesOrList => SupportsDynamicValuesOrList || (Fields != null && Fields.Any(f => f.ContainsDynamicValuesOrList)); - // Supports x-ms-dynamic-schema or -property locally + /// + /// Gets a value indicating whether dynamic schema or property are supported locally. + /// public bool SupportsDynamicSchemaOrProperty => DynamicSchema != null || DynamicProperty != null; - // Supports x-ms-dynamic-schema or -property locally or anywhere in the tree + /// + /// Gets a value indicating whether dynamic schema or property are supported locally or anywhere in the tree. + /// public bool ContainsDynamicSchemaOrProperty => SupportsDynamicSchemaOrProperty || (Fields != null && Fields.Any(f => f.ContainsDynamicSchemaOrProperty)); - // Supports x-ms-dynamic-values, -list, -schema, or -property locally + /// + /// Gets a value indicating whether dynamic intellisense is supported locally. + /// public bool SupportsDynamicIntellisense => SupportsDynamicValuesOrList || SupportsDynamicSchemaOrProperty; - // Supports x-ms-dynamic-values, -list, -schema, or -property locally or anywhere in the tree + /// + /// Gets a value indicating whether dynamic intellisense is supported locally or anywhere in the tree. + /// public bool ContainsDynamicIntellisense => ContainsDynamicValuesOrList || ContainsDynamicSchemaOrProperty; internal ConnectorDynamicSchema DynamicSchema { get; private set; } @@ -112,7 +162,9 @@ public class ConnectorType : SupportsConnectorErrors internal bool Binary { get; private set; } - // Supports x-ms-media-kind + /// + /// Gets the media kind (supports x-ms-media-kind). + /// internal MediaKind MediaKind { get; private set; } internal ISwaggerSchema Schema { get; private set; } = null; diff --git a/src/libraries/Microsoft.PowerFx.Connectors/Public/ICDPAggregateMetadata.cs b/src/libraries/Microsoft.PowerFx.Connectors/Public/ICDPAggregateMetadata.cs index cd2894d184..48e1c60c09 100644 --- a/src/libraries/Microsoft.PowerFx.Connectors/Public/ICDPAggregateMetadata.cs +++ b/src/libraries/Microsoft.PowerFx.Connectors/Public/ICDPAggregateMetadata.cs @@ -7,8 +7,16 @@ namespace Microsoft.PowerFx.Connectors { + /// + /// Interface for CDP aggregate metadata. + /// public interface ICDPAggregateMetadata { + /// + /// Tries to get sensitivity label information. + /// + /// The sensitivity label info if available. + /// True if sensitivity label info is available; otherwise, false. bool TryGetSensitivityLabelInfo(out IEnumerable cdpSensitivityLabelInfo); } } diff --git a/src/libraries/Microsoft.PowerFx.Connectors/Public/MediaKind.cs b/src/libraries/Microsoft.PowerFx.Connectors/Public/MediaKind.cs index ea7a499b26..1493a1c6c1 100644 --- a/src/libraries/Microsoft.PowerFx.Connectors/Public/MediaKind.cs +++ b/src/libraries/Microsoft.PowerFx.Connectors/Public/MediaKind.cs @@ -8,22 +8,34 @@ namespace Microsoft.PowerFx.Connectors /// public enum MediaKind : int { - // "x-ms-media-kind" is not defined / dynamic intellisense, we use a string to store results while all others are byte[] + /// + /// Not a binary media kind (dynamic intellisense, string results). + /// NotBinary = -2, - // "x-ms-media-kind" is not corresponding to any valid value (normally, only "audio", "video" or "image") + /// + /// Unknown media kind. + /// Unknown = -1, - // "x-ms-media-kind" is not defined, defaulting to "File" + /// + /// File media kind (default). + /// File = 0, - // "x-ms-media-kind" is "audio" + /// + /// Audio media kind. + /// Audio, - // "x-ms-media-kind" is "video" + /// + /// Video media kind. + /// Video, - // "x-ms-media-kind" is "image" + /// + /// Image media kind. + /// Image } } diff --git a/src/libraries/Microsoft.PowerFx.Connectors/Public/PowerFxConnectorException.cs b/src/libraries/Microsoft.PowerFx.Connectors/Public/PowerFxConnectorException.cs index d658cd0c6d..48f6bd35d6 100644 --- a/src/libraries/Microsoft.PowerFx.Connectors/Public/PowerFxConnectorException.cs +++ b/src/libraries/Microsoft.PowerFx.Connectors/Public/PowerFxConnectorException.cs @@ -7,25 +7,43 @@ namespace Microsoft.PowerFx.Connectors { + /// + /// Represents errors that occur during Power Fx connector operations. + /// [Serializable] public class PowerFxConnectorException : Exception { + /// + /// Gets the status code associated with the exception. + /// public int StatusCode { get; init; } = 0; + /// + /// Initializes a new instance of the class. + /// public PowerFxConnectorException() { } + /// + /// Initializes a new instance of the class with a specified error message. + /// public PowerFxConnectorException(string message) : base(message) { } + /// + /// Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. + /// public PowerFxConnectorException(string message, Exception innerException) : base(message, innerException) { } + /// + /// Initializes a new instance of the class with serialized data. + /// protected PowerFxConnectorException(SerializationInfo info, StreamingContext context) : base(info, context) { diff --git a/src/libraries/Microsoft.PowerFx.Connectors/Public/SupportsConnectorErrors.cs b/src/libraries/Microsoft.PowerFx.Connectors/Public/SupportsConnectorErrors.cs index 9f597fd3f6..7b7b809541 100644 --- a/src/libraries/Microsoft.PowerFx.Connectors/Public/SupportsConnectorErrors.cs +++ b/src/libraries/Microsoft.PowerFx.Connectors/Public/SupportsConnectorErrors.cs @@ -5,14 +5,29 @@ namespace Microsoft.PowerFx.Connectors { + /// + /// Base class for supporting connector errors and warnings. + /// public class SupportsConnectorErrors { + /// + /// Gets a value indicating whether there are errors. + /// public bool HasErrors => _errors != null && _errors.Count != 0; + /// + /// Gets a value indicating whether there are warnings. + /// public bool HasWarnings => _warnings != null && _warnings.Count != 0; + /// + /// Gets the collection of errors. + /// public IReadOnlyCollection Errors => _errors; + /// + /// Gets the collection of warnings. + /// public IReadOnlyCollection Warnings => _warnings; protected HashSet _errors = null; diff --git a/src/libraries/Microsoft.PowerFx.Connectors/Public/Visibility.cs b/src/libraries/Microsoft.PowerFx.Connectors/Public/Visibility.cs index 4341f2437c..ce6f461087 100644 --- a/src/libraries/Microsoft.PowerFx.Connectors/Public/Visibility.cs +++ b/src/libraries/Microsoft.PowerFx.Connectors/Public/Visibility.cs @@ -8,19 +8,29 @@ namespace Microsoft.PowerFx.Connectors /// public enum Visibility : int { - // "x-ms-visibility" is not corresponding to any valid value (normally, only "important", "advanced" or "internal") + /// + /// "x-ms-visibility" is not corresponding to any valid value (normally, only "important", "advanced" or "internal") + /// Unknown = -1, - // "x-ms-visibility" is not defined + /// + /// "x-ms-visibility" is not defined + /// None = 0, - // "x-ms-visibility" is "important" + /// + /// "x-ms-visibility" is "important" + /// Important, - // "x-ms-visibility" is "advanced" + /// + /// "x-ms-visibility" is "advanced" + /// Advanced, - // "x-ms-visibility" is "internal" + /// + /// "x-ms-visibility" is "internal" + /// Internal } }