Abstraction for config framework (#313)

* abstractions and models for config API

* revert the changes to Authentication.Abstractions.csproj

Author: isra-fel

src/Authentication.Abstractions/Interfaces/IConfigManager.cs

@@ -0,0 +1,92 @@
+// ----------------------------------------------------------------------------------
+//
+// Copyright Microsoft Corporation
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ----------------------------------------------------------------------------------
+
+using System;
+using System.Collections.Generic;
+
+namespace Microsoft.Azure.PowerShell.Common.Config
+{
+    public interface IConfigManager
+    {
+        /// <summary>
+        /// Path of the config file.
+        /// </summary>
+        string ConfigFilePath { get; }
+
+        /// <summary>
+        /// Register a config.
+        /// </summary>
+        /// <remarks>Register all the configs before <see cref="BuildConfig"/></remarks>
+        void RegisterConfig(ConfigDefinition config);
+
+        /// <summary>
+        /// Retrieve data from all the providers and build config values.
+        /// </summary>
+        void BuildConfig();
+
+        /// <summary>
+        /// Get the value of a config by key.
+        /// </summary>
+        /// <typeparam name="T">Type of the value.</typeparam>
+        /// <param name="key">Key of the config.</param>
+        /// <param name="invocation">PowerShell cmdlet invocation info. If not null, the config that matches the module or cmdlet name will be returned.</param>
+        /// <remarks>For the list of available keys, see <see cref="ConfigKeys"/>, for those used in service projects, or see <see cref="ConfigKeysForCommon"/> for those used in common projects.
+        /// The `invocation` parameter is typed `object` because we don't want Authentication.Abstractions project to take dependency on PowerShell SDK.
+        /// However at runtime it needs to be of type `InvocationInfo`.</remarks>
+        /// <returns>Value of the config, or the default value if never set.</returns>
+        T GetConfigValue<T>(string key, object invocation = null);
+
+        /// <summary>
+        /// List all configs with values.
+        /// </summary>
+        /// <param name="filter">Filter the result by config key or level etc.</param>
+        IEnumerable<ConfigData> ListConfigs(ConfigFilter filter = null);
+
+        /// <summary>
+        /// List all the definitions of all the registered configs.
+        /// </summary>
+        IEnumerable<ConfigDefinition> ListConfigDefinitions();
+
+        /// <summary>
+        /// Update the value of a config.
+        /// </summary>
+        /// <param name="key">Key of the config.</param>
+        /// <param name="value">Value to update.</param>
+        /// <param name="scope">Scope of the config to update.</param>
+        /// <remarks>This is a simple version of <see cref="UpdateConfig(UpdateConfigOptions)"/>.</remarks>
+        /// <returns>The updated config, both definition and value.</returns>
+        ConfigData UpdateConfig(string key, object value, ConfigScope scope);
+
+        /// <summary>
+        /// Update the value of a config.
+        /// </summary>
+        /// <param name="options">Specify the key, value, and optionally scope and appliesTo etc. to update.</param>
+        /// <returns>The updated config, both definition and value.</returns>
+        ConfigData UpdateConfig(UpdateConfigOptions options);
+
+        /// <summary>
+        /// Clear a config set previously.
+        /// </summary>
+        /// <remarks>This is a simple version of <see cref="ClearConfig(ClearConfigOptions)"/>.</remarks>
+        /// <param name="key">Key of the config to clear.</param>
+        /// <param name="scope">Scope of the config to update.</param>
+        void ClearConfig(string key, ConfigScope scope);
+
+        /// <summary>
+        /// Clear a config set previously.
+        /// </summary>
+        /// <param name="options">Specify the key, and optionally scope and appliesTo etc. to update.</param>
+        void ClearConfig(ClearConfigOptions options);
+    }
+}

src/Authentication.Abstractions/Models/AppliesTo.cs

@@ -0,0 +1,37 @@
+// ----------------------------------------------------------------------------------
+//
+// Copyright Microsoft Corporation
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ----------------------------------------------------------------------------------
+
+namespace Microsoft.Azure.PowerShell.Common.Config
+{
+    /// <summary>
+    /// General categories of levels that a config applies to.
+    /// </summary>
+    public enum AppliesTo
+    {
+        /// <summary>
+        /// The config can apply to whole Azure PowerShell.
+        /// </summary>
+        Az,
+
+        /// <summary>
+        /// The config can apply to a certain module.
+        /// </summary>
+        Module,
+
+        /// <summary>
+        /// The config can apply to a certain cmdlet.
+        /// </summary>
+        Cmdlet
+    }
+}

src/Authentication.Abstractions/Models/ClearConfigOptions.cs

@@ -0,0 +1,36 @@
+// ----------------------------------------------------------------------------------
+//
+// Copyright Microsoft Corporation
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ----------------------------------------------------------------------------------
+
+
+namespace Microsoft.Azure.PowerShell.Common.Config
+{
+    public class ClearConfigOptions
+    {
+        public ClearConfigOptions(string key, ConfigScope scope)
+        {
+            Key = key;
+            Scope = scope;
+        }
+
+        public string Key { get; }
+
+        public ConfigScope Scope { get; set; }
+
+        /// <summary>
+        /// Specifies a module or cmdlet that the config applies to.
+        /// If null, it applies to all.
+        /// </summary>
+        public string AppliesTo { get; set; } = null;
+    }
+}

src/Authentication.Abstractions/Models/ConfigData.cs

@@ -0,0 +1,44 @@
+// ----------------------------------------------------------------------------------
+//
+// Copyright Microsoft Corporation
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ----------------------------------------------------------------------------------
+
+using System;
+
+namespace Microsoft.Azure.PowerShell.Common.Config
+{
+    /// <summary>
+    /// Wrapper for both definition and value of a config. Used as output of some API of <see cref="IConfigManager"/>.
+    /// </summary>
+    public class ConfigData
+    {
+        public ConfigData(ConfigDefinition config, object value, ConfigScope scope, string appliesTo)
+        {            
+            Definition = config ?? throw new ArgumentNullException(nameof(config));
+            Value = value;
+            Scope = scope;
+            AppliesTo = appliesTo;
+        }
+
+        public ConfigDefinition Definition { get; }
+
+        public object Value { get; }
+
+        /// <summary>
+        /// Specifies a module or cmdlet that the config applies to.
+        /// If null, it applies to all.
+        /// </summary>
+        public string AppliesTo { get; }
+
+        public ConfigScope Scope { get; }
+    }
+}

src/Authentication.Abstractions/Models/ConfigDefinition.cs

@@ -0,0 +1,71 @@
+// ----------------------------------------------------------------------------------
+//
+// Copyright Microsoft Corporation
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ----------------------------------------------------------------------------------
+
+using System;
+using System.Collections.Generic;
+
+namespace Microsoft.Azure.PowerShell.Common.Config
+{
+    /// <summary>
+    /// Represents the definition of a config of Azure PowerShell.
+    /// </summary>
+    public abstract class ConfigDefinition
+    {
+        /// <summary>
+        /// Gets the default value of this config.
+        /// </summary>
+        public abstract object DefaultValue { get; }
+
+        /// <summary>
+        /// Gets the unique key of this config.
+        /// </summary>
+        /// <remarks>It is also used as the name of the PowerShell parameter which maps to this config, so the key must follow the design guideline and conventions. See <see href="https://github.com/Azure/azure-powershell/blob/main/documentation/development-docs/design-guidelines/parameter-best-practices.md#parameter-best-practices">Parameter Best Practices</see>.</remarks>
+        /// <seealso cref=""/>
+        public abstract string Key { get; }
+
+        /// <summary>
+        /// Gets the help message or description of the config.
+        /// It is also used as the help message of the PowerShell parameter which maps to this config.
+        /// </summary>
+        public abstract string HelpMessage { get; }
+
+        /// <summary>
+        /// Gets the name of the environment variable that can control this config.
+        /// </summary>
+        public virtual string EnvironmentVariableName { get; } = null;
+
+        /// <summary>
+        /// Gets how the config can be applied to.
+        /// </summary>
+        public virtual IReadOnlyCollection<AppliesTo> CanApplyTo => new AppliesTo[] { AppliesTo.Az, AppliesTo.Module, AppliesTo.Cmdlet };
+
+        /// <summary>
+        /// Gets the type of the value of this config.
+        /// </summary>
+        public abstract Type ValueType { get; }
+
+        /// <summary>
+        /// Override in derived classes to validate the input value. Throws an exception if not.
+        /// </summary>
+        /// <param name="value">The value to check.</param>
+        public virtual void Validate(object value) { }
+
+        /// <summary>
+        /// Override in derived classes to perform side effects of applying the config value.
+        /// If a exception is thrown, the config will not be updated.
+        /// </summary>
+        /// <param name="value">Value of the config to apply.</param>
+        public virtual void Apply(object value) { }
+    }
+}

src/Authentication.Abstractions/Models/ConfigFilter.cs

@@ -0,0 +1,46 @@
+// ----------------------------------------------------------------------------------
+//
+// Copyright Microsoft Corporation
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ----------------------------------------------------------------------------------
+
+using System.Collections.Generic;
+
+namespace Microsoft.Azure.PowerShell.Common.Config
+{
+    /// <summary>
+    /// Filter options for listing configurations. Used as input of some API of <see cref="IConfigManager" />
+    /// </summary>
+    public class ConfigFilter
+    {
+        /// <summary>
+        /// Represents the global config "applies to" - the config applies to all cmdlets of Azure PowerShell.
+        /// </summary>
+        public const string GlobalAppliesTo = "Az";
+
+        /// <summary>
+        /// Keys of the configs to filter. When omitted, all the keys will be used.
+        /// </summary>
+        public IEnumerable<string> Keys { get; set; } = null;
+
+        /// <summary>
+        /// Specifies what part of Azure PowerShell the config applies to.
+        /// </summary>
+        /// <remarks>
+        /// Possible values are:
+        /// - null: the config applies to any of above.
+        /// - <see cref="GlobalAppliesTo"/> ("Az"): the config applies to all modules and cmdlets of Azure PowerShell.
+        /// - Name of a module: the config applies to a certain module of Azure PowerShell. For example, "Az.Storage".
+        /// - Name of a cmdlet: the config applies to a certain cmdlet of Azure PowerShell. For example, "Get-AzKeyVault".
+        /// </remarks>
+        public string AppliesTo { get; set; } = null;
+    }
+}

src/Authentication.Abstractions/Models/ConfigScope.cs

@@ -0,0 +1,38 @@
+// ----------------------------------------------------------------------------------
+//
+// Copyright Microsoft Corporation
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ----------------------------------------------------------------------------------
+
+namespace Microsoft.Azure.PowerShell.Common.Config
+{
+    /// <summary>
+    /// Scope for the config.
+    /// </summary>
+    public enum ConfigScope
+    {
+        /// <summary>
+        /// Config will be persitent on the disk, available for all the PowerShell sessions initiated by the current user.
+        /// </summary>
+        CurrentUser,
+
+        /// <summary>
+        /// Config is effective in current PowerShell process.
+        /// </summary>
+        Process,
+
+        /// <summary>
+        /// Config is never set.
+        /// </summary>
+        /// <remarks>This option is not available when updating or clearing a config.</remarks>
+        Default
+    }
+}