diff --git a/src/Authentication.Abstractions/Interfaces/IConfigManager.cs b/src/Authentication.Abstractions/Interfaces/IConfigManager.cs new file mode 100644 index 0000000000..3f39fc6ace --- /dev/null +++ b/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 + { + /// + /// Path of the config file. + /// + string ConfigFilePath { get; } + + /// + /// Register a config. + /// + /// Register all the configs before + void RegisterConfig(ConfigDefinition config); + + /// + /// Retrieve data from all the providers and build config values. + /// + void BuildConfig(); + + /// + /// Get the value of a config by key. + /// + /// Type of the value. + /// Key of the config. + /// PowerShell cmdlet invocation info. If not null, the config that matches the module or cmdlet name will be returned. + /// For the list of available keys, see , for those used in service projects, or see 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`. + /// Value of the config, or the default value if never set. + T GetConfigValue(string key, object invocation = null); + + /// + /// List all configs with values. + /// + /// Filter the result by config key or level etc. + IEnumerable ListConfigs(ConfigFilter filter = null); + + /// + /// List all the definitions of all the registered configs. + /// + IEnumerable ListConfigDefinitions(); + + /// + /// Update the value of a config. + /// + /// Key of the config. + /// Value to update. + /// Scope of the config to update. + /// This is a simple version of . + /// The updated config, both definition and value. + ConfigData UpdateConfig(string key, object value, ConfigScope scope); + + /// + /// Update the value of a config. + /// + /// Specify the key, value, and optionally scope and appliesTo etc. to update. + /// The updated config, both definition and value. + ConfigData UpdateConfig(UpdateConfigOptions options); + + /// + /// Clear a config set previously. + /// + /// This is a simple version of . + /// Key of the config to clear. + /// Scope of the config to update. + void ClearConfig(string key, ConfigScope scope); + + /// + /// Clear a config set previously. + /// + /// Specify the key, and optionally scope and appliesTo etc. to update. + void ClearConfig(ClearConfigOptions options); + } +} diff --git a/src/Authentication.Abstractions/Models/AppliesTo.cs b/src/Authentication.Abstractions/Models/AppliesTo.cs new file mode 100644 index 0000000000..76d05c3acd --- /dev/null +++ b/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 +{ + /// + /// General categories of levels that a config applies to. + /// + public enum AppliesTo + { + /// + /// The config can apply to whole Azure PowerShell. + /// + Az, + + /// + /// The config can apply to a certain module. + /// + Module, + + /// + /// The config can apply to a certain cmdlet. + /// + Cmdlet + } +} diff --git a/src/Authentication.Abstractions/Models/ClearConfigOptions.cs b/src/Authentication.Abstractions/Models/ClearConfigOptions.cs new file mode 100644 index 0000000000..8f4f4a029f --- /dev/null +++ b/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; } + + /// + /// Specifies a module or cmdlet that the config applies to. + /// If null, it applies to all. + /// + public string AppliesTo { get; set; } = null; + } +} diff --git a/src/Authentication.Abstractions/Models/ConfigData.cs b/src/Authentication.Abstractions/Models/ConfigData.cs new file mode 100644 index 0000000000..c6fec09434 --- /dev/null +++ b/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 +{ + /// + /// Wrapper for both definition and value of a config. Used as output of some API of . + /// + 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; } + + /// + /// Specifies a module or cmdlet that the config applies to. + /// If null, it applies to all. + /// + public string AppliesTo { get; } + + public ConfigScope Scope { get; } + } +} diff --git a/src/Authentication.Abstractions/Models/ConfigDefinition.cs b/src/Authentication.Abstractions/Models/ConfigDefinition.cs new file mode 100644 index 0000000000..a54de3cfce --- /dev/null +++ b/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 +{ + /// + /// Represents the definition of a config of Azure PowerShell. + /// + public abstract class ConfigDefinition + { + /// + /// Gets the default value of this config. + /// + public abstract object DefaultValue { get; } + + /// + /// Gets the unique key of this config. + /// + /// 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 Parameter Best Practices. + /// + public abstract string Key { get; } + + /// + /// 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. + /// + public abstract string HelpMessage { get; } + + /// + /// Gets the name of the environment variable that can control this config. + /// + public virtual string EnvironmentVariableName { get; } = null; + + /// + /// Gets how the config can be applied to. + /// + public virtual IReadOnlyCollection CanApplyTo => new AppliesTo[] { AppliesTo.Az, AppliesTo.Module, AppliesTo.Cmdlet }; + + /// + /// Gets the type of the value of this config. + /// + public abstract Type ValueType { get; } + + /// + /// Override in derived classes to validate the input value. Throws an exception if not. + /// + /// The value to check. + public virtual void Validate(object value) { } + + /// + /// Override in derived classes to perform side effects of applying the config value. + /// If a exception is thrown, the config will not be updated. + /// + /// Value of the config to apply. + public virtual void Apply(object value) { } + } +} diff --git a/src/Authentication.Abstractions/Models/ConfigFilter.cs b/src/Authentication.Abstractions/Models/ConfigFilter.cs new file mode 100644 index 0000000000..396dee59b4 --- /dev/null +++ b/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 +{ + /// + /// Filter options for listing configurations. Used as input of some API of + /// + public class ConfigFilter + { + /// + /// Represents the global config "applies to" - the config applies to all cmdlets of Azure PowerShell. + /// + public const string GlobalAppliesTo = "Az"; + + /// + /// Keys of the configs to filter. When omitted, all the keys will be used. + /// + public IEnumerable Keys { get; set; } = null; + + /// + /// Specifies what part of Azure PowerShell the config applies to. + /// + /// + /// Possible values are: + /// - null: the config applies to any of above. + /// - ("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". + /// + public string AppliesTo { get; set; } = null; + } +} diff --git a/src/Authentication.Abstractions/Models/ConfigScope.cs b/src/Authentication.Abstractions/Models/ConfigScope.cs new file mode 100644 index 0000000000..3a20fa3c82 --- /dev/null +++ b/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 +{ + /// + /// Scope for the config. + /// + public enum ConfigScope + { + /// + /// Config will be persitent on the disk, available for all the PowerShell sessions initiated by the current user. + /// + CurrentUser, + + /// + /// Config is effective in current PowerShell process. + /// + Process, + + /// + /// Config is never set. + /// + /// This option is not available when updating or clearing a config. + Default + } +} diff --git a/src/Authentication.Abstractions/Models/UpdateConfigOptions.cs b/src/Authentication.Abstractions/Models/UpdateConfigOptions.cs new file mode 100644 index 0000000000..72ae95f5e6 --- /dev/null +++ b/src/Authentication.Abstractions/Models/UpdateConfigOptions.cs @@ -0,0 +1,41 @@ +// ---------------------------------------------------------------------------------- +// +// 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 +{ + /// + /// Options for updating a config. Used as input of + /// + public class UpdateConfigOptions + { + public UpdateConfigOptions(string key, object value, ConfigScope scope) + { + Key = key ?? throw new ArgumentNullException(nameof(key)); + Scope = scope; + Value = value; + } + + public string Key { get; } + public object Value { get; } + public ConfigScope Scope { get; set; } + + /// + /// Specifies a module or cmdlet that the config applies to. + /// If null, it applies to all. + /// + public string AppliesTo { get; set; } = null; + } +}