From bc00d770be5b412d23f98b0a920aad2f156f41bb Mon Sep 17 00:00:00 2001 From: markcowl Date: Fri, 6 Dec 2019 17:05:07 -0800 Subject: [PATCH 1/4] Initial, top-level documentation for common classes --- src/Aks/README.md | 3 +- src/Authentication.Abstractions/README.md | 95 ++++++++++++++++++++++- 2 files changed, 96 insertions(+), 2 deletions(-) diff --git a/src/Aks/README.md b/src/Aks/README.md index bdf239c14c..33e9003d60 100644 --- a/src/Aks/README.md +++ b/src/Aks/README.md @@ -1 +1,2 @@ -# Aks \ No newline at end of file +# Aks +Common management client library for Azure Kubernetes Service. Allows modules to safely take a dependency on a .Net SDK for AKS management functions without causing dependency conflicts with the Az.AKS module. \ No newline at end of file diff --git a/src/Authentication.Abstractions/README.md b/src/Authentication.Abstractions/README.md index 0994c47aa4..6913889fab 100644 --- a/src/Authentication.Abstractions/README.md +++ b/src/Authentication.Abstractions/README.md @@ -1 +1,94 @@ -# Authentication Abstractions \ No newline at end of file +# Authentication Abstractions +Base abstrations library for all Azure PowerShell modules. + +## Restrictions +**This library cannot have API or binary breaking changes**. It is required to be completely backward compatible, this means: +- Interfaces in this library cannot be changed. New base functionality requires using the interface `Extensions` property, or defining a new interface +- For abstract and concrete classes, methods and properties may be added, but may not be changed or removed. +## Target +NetStandard 2.0 +## Dependencies +- Hyak.Commmon (1.0.0.0) +- Microsoft.Azure.Common (2.0.0.0) +- Microsoft.Rest.ClientRuntime (2.0.0.0) +- Newtonsoft.Json (10.0.0.0) +## Interfaces +### IAccessToken +Represents a renwable access token +### IAuthenticationFactory +Abstract factory for authentication classes compatible with .Net autorest-generated libraries +### IAzureAccount +Abstract representation of a logged-in principal +### IAzureContext +Abstract representation of the default target for authentication and Azure PowerzShell commands (Environment, Tenant, Account, Subscription) +### IAzureContextContainer +A dictionary of IAzureContext objects +### IAzureEnvironment +Abstract representation of a particular Azure Cloud +### IAzureSession +### IAzureSubscription +Abstract representation of an ARM subscription. +### IAzureTenant +Abstract represetnation of an AAD Tenant +### IClientAction +Abstract representation of an action that can be performed ona client +### IClientFactory +Abstract factory for .Net Autorest-generated clients +### IDataStore +Methods representing a file store - used to abstract away file system details for testing purposes +### IExtensibleModel +Base interface for all model interfaces - provides a dictionary of extended properties that can be used by any model. Extensions over this interface implemented in this library allow adding basic extension storage and lookup functions once and having them apply ao all implementations of any interface in this library. +### IExtensibleSettings +Base interface for serializable settings classes. Interface allows a single extension implementation that applies to all implementiung interfaces and classes. +### IFileProvider +Base abstration for shared file data - allows implementations that provide thread-safe and process safe file access. +### IHyakAuthenticationFactory +Abstract factory for authentication classes compatible with .Net Hyak generated clients +### IHyakClientAction +Abstract representation of a client configuration action for Hyak-generated clients +### IHyakClientFactory +Abstract factory for Hyak=generated clients +### IProfileProvider +Abstract collection of profile management methods, designed to be combined with an IFileProvider for any concreteimplementation +### IRenewableToken +An abstract type for renewable tokens that are compatible with the ITokenProvider interfaces in autorest-generated clients +### IStorageContext +Abstract representation of an Azure Storage data plane target - provides a single aabstraction for data plane access regardless of authentication method, and regardless of the storage data plane version. +### IStorageContextProvider +Abstract representation of a factory for IStorageContext - allows using a single abstraction regardless of the implementation, which allows using thsi abstraction over multiple different versions of Azure Storage data and nanagement plane APIs. + +## Classes +### AzureAccount +Default implementation of IAzureAccount, includes extention property names for extension properties used in Azure Accounts. +### AzureContext +Default implementation of IAzureContext +### AzureEnvironment +Default implementation of IAzureEnvironment - a collection of properties that defines how to communicate with a particular Azure Cloud. +### AzurePSDataCollectionProfile +Serialization class for data collection settings +### AzureRmProfileProvider +Default ProfileProvider for AzureRM +### AzureSMProfileProvider +Default Profile provider for RDFE +### AzureSubscription +Default implementation of IAzureSubscription, including extension property names typically used with Subscriptions.] +### AzureTenant +Default implementation fo IAzureTenant. +### DataCollectionController +Default im[lementation of client-side telemetry] +### DiskDataStore +Default implementation of IDataStore using the file system. + +## Extensions +## Enumerations +### AzureModule +The kinds of AzureModule (in this case: Profile, ARM, RDFE) +### ContextSaveMode +The modes of context autosave (CurrentUser or Process) +## Static Classes +### AzureEnvironmentConstants +General constants defining the endpoints in the built-in Azure environments +### AzureSession +General constants used at runtime by common code, especially authentication +### EnvironmentName +General constants used in the built-in Azure environments \ No newline at end of file From 0322dc47cd9f1386bd37e63e31c775b324ea5a08 Mon Sep 17 00:00:00 2001 From: markcowl Date: Fri, 6 Dec 2019 17:27:38 -0800 Subject: [PATCH 2/4] Add base readme data for all common code libraries --- src/Authorization/README.md | 3 ++- src/Compute/README.md | 3 ++- src/Graph.Rbac/README.md | 3 ++- src/KeyVault/README.md | 3 ++- src/Monitor/README.md | 2 ++ src/Network/README.md | 3 ++- src/PolicyInsights/README.md | 3 ++- src/Storage.Management/README.md | 3 ++- src/Storage/README.md | 3 ++- src/Strategies/README.md | 3 ++- src/Websites/README.md | 3 ++- 11 files changed, 22 insertions(+), 10 deletions(-) create mode 100644 src/Monitor/README.md diff --git a/src/Authorization/README.md b/src/Authorization/README.md index 02b25f2277..a5b33f23a3 100644 --- a/src/Authorization/README.md +++ b/src/Authorization/README.md @@ -1 +1,2 @@ -# Authorization \ No newline at end of file +# Authorization +Common management client library for Azure Authorization Service. Allows modules to safely take a dependency on a .Net SDK for RBAC functions without causing dependency conflicts with the Az.Resources module. \ No newline at end of file diff --git a/src/Compute/README.md b/src/Compute/README.md index ab97ec9b85..4a55ba2abd 100644 --- a/src/Compute/README.md +++ b/src/Compute/README.md @@ -1 +1,2 @@ -# Compute \ No newline at end of file +# Compute +Common management client library for Azure Compute Service. Allows modules to safely take a dependency on a .Net SDK for Compute management functions without causing dependency conflicts with the Az.Compute module. \ No newline at end of file diff --git a/src/Graph.Rbac/README.md b/src/Graph.Rbac/README.md index 738292dc14..2904916a0a 100644 --- a/src/Graph.Rbac/README.md +++ b/src/Graph.Rbac/README.md @@ -1 +1,2 @@ -# Graph Rbac \ No newline at end of file +# Graph Rbac +Common management client library for AAD Graph Service. Allows modules to safely take a dependency on a .Net SDK for AAD Graph functions without causing dependency conflicts with the Az.Resources module. \ No newline at end of file diff --git a/src/KeyVault/README.md b/src/KeyVault/README.md index 2fe0f29b0d..67c8e2f59d 100644 --- a/src/KeyVault/README.md +++ b/src/KeyVault/README.md @@ -1 +1,2 @@ -# KeyVault \ No newline at end of file +# KeyVault +Common management client library for Azure KeyVault Service. Allows modules to safely take a dependency on a .Net SDK for KeyVault management functions without causing dependency conflicts with the Az.KeyVault module. \ No newline at end of file diff --git a/src/Monitor/README.md b/src/Monitor/README.md new file mode 100644 index 0000000000..66c54227d8 --- /dev/null +++ b/src/Monitor/README.md @@ -0,0 +1,2 @@ +# Monitor +Common management client library for Azure Monitor Service. Allows modules to safely take a dependency on a .Net SDK for Monitor management functions without causing dependency conflicts with the Az.Monitor module. \ No newline at end of file diff --git a/src/Network/README.md b/src/Network/README.md index 56863069be..0d762f61ff 100644 --- a/src/Network/README.md +++ b/src/Network/README.md @@ -1 +1,2 @@ -# Network \ No newline at end of file +# Network +Common management client library for Azure Network Service. Allows modules to safely take a dependency on a .Net SDK for Network management functions without causing dependency conflicts with the Az.Network module. \ No newline at end of file diff --git a/src/PolicyInsights/README.md b/src/PolicyInsights/README.md index 0d0a4f823b..7459b9e392 100644 --- a/src/PolicyInsights/README.md +++ b/src/PolicyInsights/README.md @@ -1 +1,2 @@ -PolicyInsights \ No newline at end of file +# PolicyInsights +Common management client library for Azure PolicyInsights Service. Allows modules to safely take a dependency on a .Net SDK for Policy Insights management functions without causing dependency conflicts with the Az.Policy module. \ No newline at end of file diff --git a/src/Storage.Management/README.md b/src/Storage.Management/README.md index b5143eaeed..fcacb3c5f1 100644 --- a/src/Storage.Management/README.md +++ b/src/Storage.Management/README.md @@ -1 +1,2 @@ -# Storage Management \ No newline at end of file +# Storage Management +Common management client library for Azure Storage Service. Allows modules to safely take a dependency on a .Net SDK for Storage management functions without causing dependency conflicts with the Az.Storage module. \ No newline at end of file diff --git a/src/Storage/README.md b/src/Storage/README.md index 19c72df0c0..c5f3bb3c16 100644 --- a/src/Storage/README.md +++ b/src/Storage/README.md @@ -1 +1,2 @@ -# Storage \ No newline at end of file +# Storage +Base classes for api-version independent abstractions for Storage data plane \ No newline at end of file diff --git a/src/Strategies/README.md b/src/Strategies/README.md index c2c034a55c..df1b364c37 100644 --- a/src/Strategies/README.md +++ b/src/Strategies/README.md @@ -1 +1,2 @@ -# Strategies \ No newline at end of file +# Strategies +Common abstractions for goal-seeking deployment engine. \ No newline at end of file diff --git a/src/Websites/README.md b/src/Websites/README.md index 59251f4739..0433caed5b 100644 --- a/src/Websites/README.md +++ b/src/Websites/README.md @@ -1 +1,2 @@ -# Websites \ No newline at end of file +# Websites +Common management client library for Azure App Service. Allows modules to safely take a dependency on a .Net SDK for ApPService management functions without causing dependency conflicts with the Az.Websites module. \ No newline at end of file From 39620ab6a4728385582c189d9693b474129a8357 Mon Sep 17 00:00:00 2001 From: Mark Cowlishaw Date: Fri, 9 Jul 2021 16:39:18 -0700 Subject: [PATCH 3/4] Apply suggestions from code review --- src/Authentication.Abstractions/README.md | 24 +++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/src/Authentication.Abstractions/README.md b/src/Authentication.Abstractions/README.md index 6913889fab..6f7e11611a 100644 --- a/src/Authentication.Abstractions/README.md +++ b/src/Authentication.Abstractions/README.md @@ -14,32 +14,32 @@ NetStandard 2.0 - Newtonsoft.Json (10.0.0.0) ## Interfaces ### IAccessToken -Represents a renwable access token +Represents a renewable access token ### IAuthenticationFactory Abstract factory for authentication classes compatible with .Net autorest-generated libraries ### IAzureAccount -Abstract representation of a logged-in principal +Abstract representation of a logged-in principal ### IAzureContext -Abstract representation of the default target for authentication and Azure PowerzShell commands (Environment, Tenant, Account, Subscription) +Abstract representation of the default target for authentication and Azure PowerShell commands (Environment, Tenant, Account, Subscription) ### IAzureContextContainer -A dictionary of IAzureContext objects +A dictionary of IAzureContext objects. The default context container will contain all of the possible contexts for the logged-in identities (one context per tenant x subscription, for each logged-in principal). ### IAzureEnvironment -Abstract representation of a particular Azure Cloud +Abstract representation of a particular Azure Cloud. Contains the endpoints, authentication resources (scopes), and domain name suffixes associated with a particular cloud. There are built-in environments for the Azure public clouds, and users may create an environment for any on-premise, private, or air-gapped clouds. ### IAzureSession ### IAzureSubscription Abstract representation of an ARM subscription. ### IAzureTenant -Abstract represetnation of an AAD Tenant +Abstract representation of an AAD Tenant ### IClientAction -Abstract representation of an action that can be performed ona client +Abstract representation of an action that can be performed on a client. This is generally used to alter the shape or processing of all or some requests and responses processed by the client. ### IClientFactory -Abstract factory for .Net Autorest-generated clients +Abstract factory for .Net Autorest-generated clients. This is the main entry point that cmdlets based on management clients will use to create and authenticate their clients. ### IDataStore -Methods representing a file store - used to abstract away file system details for testing purposes +An abstract representation of a file store, used to abstract operations over the file system for items cached, written, or read by PowerShell cmdlets. Used mainly to mock file operations in tests, but could also be used to store PowerShell files on some other medium (like blob storage). ### IExtensibleModel -Base interface for all model interfaces - provides a dictionary of extended properties that can be used by any model. Extensions over this interface implemented in this library allow adding basic extension storage and lookup functions once and having them apply ao all implementations of any interface in this library. +Base interface for all model interfaces - provides a dictionary of extended properties that can be used by any model. Extensions over this interface implemented in this library allow adding basic extension storage and lookup functions once and having them apply to all implementations of any interface in this library. This is used as a mechanism for adding new data, or command-specific data into the metadata caches maintained by PowerShell. ### IExtensibleSettings -Base interface for serializable settings classes. Interface allows a single extension implementation that applies to all implementiung interfaces and classes. +Base interface for serializable settings classes. Interface allows a single extension implementation that applies to all implementing interfaces and classes. ### IFileProvider Base abstration for shared file data - allows implementations that provide thread-safe and process safe file access. ### IHyakAuthenticationFactory @@ -91,4 +91,4 @@ General constants defining the endpoints in the built-in Azure environments ### AzureSession General constants used at runtime by common code, especially authentication ### EnvironmentName -General constants used in the built-in Azure environments \ No newline at end of file +General constants used in the built-in Azure environments From 062a5529b815b64767b982f92050bb22d3a750ad Mon Sep 17 00:00:00 2001 From: Mark Cowlishaw Date: Fri, 9 Jul 2021 16:48:07 -0700 Subject: [PATCH 4/4] Apply suggestions from code review --- src/Authentication.Abstractions/README.md | 16 ++++++++-------- src/Websites/README.md | 2 +- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/src/Authentication.Abstractions/README.md b/src/Authentication.Abstractions/README.md index 6f7e11611a..3340b92193 100644 --- a/src/Authentication.Abstractions/README.md +++ b/src/Authentication.Abstractions/README.md @@ -16,7 +16,7 @@ NetStandard 2.0 ### IAccessToken Represents a renewable access token ### IAuthenticationFactory -Abstract factory for authentication classes compatible with .Net autorest-generated libraries +Abstract factory for authentication classes compatible with .Net autorest-generated libraries. Methods in this interface allow creating abstract self-renewing token-based credentials that could be applied to any client. This is the primary mechanism for authenticating clients in track 2, or other non-management clients that use AAD or MSAL bearer token authentication. ### IAzureAccount Abstract representation of a logged-in principal ### IAzureContext @@ -41,7 +41,7 @@ Base interface for all model interfaces - provides a dictionary of extended prop ### IExtensibleSettings Base interface for serializable settings classes. Interface allows a single extension implementation that applies to all implementing interfaces and classes. ### IFileProvider -Base abstration for shared file data - allows implementations that provide thread-safe and process safe file access. +Base abstraction for shared file data, especially used in IProfileProvider implementations- allows implementations that provide thread-safe and process-safe file access to shared files, or store files in memory. ### IHyakAuthenticationFactory Abstract factory for authentication classes compatible with .Net Hyak generated clients ### IHyakClientAction @@ -49,17 +49,17 @@ Abstract representation of a client configuration action for Hyak-generated clie ### IHyakClientFactory Abstract factory for Hyak=generated clients ### IProfileProvider -Abstract collection of profile management methods, designed to be combined with an IFileProvider for any concreteimplementation +Abstract collection of profile management methods, designed to be combined with an IFileProvider for any concrete implementation. Specific implementations provide thread-safe access to shared files, or cache profiles in memory. ### IRenewableToken -An abstract type for renewable tokens that are compatible with the ITokenProvider interfaces in autorest-generated clients +An abstract type for renewable tokens that are compatible with the ITokenProvider interfaces in autorest-generated and other clients. This is the primary mechanism for adapting authentication to Track 2 or non-autorest clients. ### IStorageContext Abstract representation of an Azure Storage data plane target - provides a single aabstraction for data plane access regardless of authentication method, and regardless of the storage data plane version. ### IStorageContextProvider -Abstract representation of a factory for IStorageContext - allows using a single abstraction regardless of the implementation, which allows using thsi abstraction over multiple different versions of Azure Storage data and nanagement plane APIs. +Abstract representation of a factory for IStorageContext - allows using a single abstraction regardless of the implementation, which allows using this abstraction over multiple different versions of Azure Storage data and management plane APIs. ## Classes ### AzureAccount -Default implementation of IAzureAccount, includes extention property names for extension properties used in Azure Accounts. +Default implementation of IAzureAccount, includes extension property names for extension properties used in Azure Accounts. ### AzureContext Default implementation of IAzureContext ### AzureEnvironment @@ -71,11 +71,11 @@ Default ProfileProvider for AzureRM ### AzureSMProfileProvider Default Profile provider for RDFE ### AzureSubscription -Default implementation of IAzureSubscription, including extension property names typically used with Subscriptions.] +Default implementation of IAzureSubscription, including extension property names typically used with Subscriptions. ### AzureTenant Default implementation fo IAzureTenant. ### DataCollectionController -Default im[lementation of client-side telemetry] +Default implementation of client-side telemetry. ### DiskDataStore Default implementation of IDataStore using the file system. diff --git a/src/Websites/README.md b/src/Websites/README.md index 0433caed5b..a277ad422d 100644 --- a/src/Websites/README.md +++ b/src/Websites/README.md @@ -1,2 +1,2 @@ # Websites -Common management client library for Azure App Service. Allows modules to safely take a dependency on a .Net SDK for ApPService management functions without causing dependency conflicts with the Az.Websites module. \ No newline at end of file +Common management client library for Azure App Service. Allows modules to safely take a dependency on a .Net SDK for AppService management functions without causing dependency conflicts with the Az.Websites module.