diff --git a/sdk/appconfiguration/Azure.ApplicationModel.Configuration/README.md b/sdk/appconfiguration/Azure.ApplicationModel.Configuration/README.md index 067a88928aa2..603840507086 100644 --- a/sdk/appconfiguration/Azure.ApplicationModel.Configuration/README.md +++ b/sdk/appconfiguration/Azure.ApplicationModel.Configuration/README.md @@ -1,11 +1,15 @@ # Azure App Configuration client library for .NET -Azure App Configuration is a managed service that helps developers centralize their application configurations simply and securely. -Modern programs, especially programs running in a cloud, generally have many components that are distributed in nature. Spreading configuration settings across these components can lead to hard-to-troubleshoot errors during an application deployment. Use App Configuration to securely store all the settings for your application in one place. +Azure App Configuration is a managed service that helps developers centralize their application configurations in one place, simply and securely. -Use the client library for App Configuration to create and manage application configuration settings. +Use the client library for App Configuration to: -[Source code]() | [Package (NuGet)][package] | [API reference documentation]() | [Product documentation][azconfig_docs] +* Create centrally stored application configuration settings +* Retrieve settings +* Update settings +* Delete settings + +[Package (NuGet)][package] | API reference documentation (coming soon) | [Product documentation][azconfig_docs] ## Getting started @@ -13,7 +17,7 @@ Use the client library for App Configuration to create and manage application co Install the Azure App Configuration client library for .NET with [NuGet][nuget]: -```Powershell +```PowerShell Install-Package Azure.ApplicationModel.Configuration -Version 1.0.0-preview.2 ``` @@ -22,12 +26,14 @@ Install-Package Azure.ApplicationModel.Configuration -Version 1.0.0-preview.2 To create a Configuration Store, you can use the Azure Portal or [Azure CLI][azure_cli]. You need to install the Azure App Configuration CLI extension first by executing the following command: -```Powershell + +```PowerShell az extension add -n appconfig ``` After that, create the Configuration Store: -```Powershell + +```PowerShell az appconfig create --name --resource-group --location eastus ``` @@ -36,8 +42,10 @@ az appconfig create --name --resource-group ``` @@ -54,10 +62,12 @@ var client = new ConfigurationClient(connectionString); ## Key concepts -### Configuration Setting -A Configuration Setting is the fundamental resource within a Configuration Store. In its simplest form it is a key and a value. However, there are additional properties such as the modifiable content type and tags fields that allow the value to be interpreted or associated in different ways. +### Configuration setting + +A Configuration Setting is the fundamental resource within a Configuration Store. In its simplest form, it is a key and a value. However, there are additional properties such as the modifiable content type and tags fields that allow the value to be interpreted or associated in different ways. The Label property of a Configuration Setting provides a way to separate Configuration Settings into different dimensions. These dimensions are user defined and can take any form. Some common examples of dimensions to use for a label include regions, semantic versions, or environments. Many applications have a required set of configuration keys that have varying values as the application exists across different dimensions. + For example, MaxRequests may be 100 in "NorthAmerica", and 200 in "WestEurope". By creating a Configuration Setting named MaxRequests with a label of "NorthAmerica" and another, only with a different value, in the "WestEurope" label, an application can seamlessly retrieve Configuration Settings as it runs in these two dimensions. Properties of a Configuration Setting: @@ -81,15 +91,18 @@ Properties of a Configuration Setting: ``` ## Examples + The following sections provide several code snippets covering some of the most common Configuration Service tasks. Note that there are sync and async methods available for both: -- [Create a Configuration Setting](#create-a-Configuration-Setting) -- [Retrieve a Configuration Setting](#retrieve-a-Configuration-Setting) -- [Update an existing Configuration Setting](#update-an-existing-Configuration-Setting) -- [Delete a Configuration Setting](#delete-a-Configuration-Setting) + +- [Create a Configuration Setting](#create-a-configuration-setting) +- [Retrieve a Configuration Setting](#retrieve-a-configuration-setting) +- [Update an existing Configuration Setting](#update-an-existing-configuration-setting) +- [Delete a Configuration Setting](#delete-a-configuration-setting) ### Create a Configuration Setting -Create a Configuration Setting to be stored in the Configuration Store. -There are two ways to store a Configuration Setting: + +Create a Configuration Setting to be stored in the Configuration Store. There are two ways to store a Configuration Setting: + - Add creates a setting only if the setting does not already exist in the store. - Set creates a setting if it doesn't exist or overrides an existing setting. @@ -101,6 +114,7 @@ client.Set(setting); ``` ### Retrieve a Configuration Setting + Retrieve a previously stored Configuration Setting by calling Get. ```c# @@ -112,6 +126,7 @@ ConfigurationSetting setting = client.Get("some_key"); ``` ### Update an existing Configuration Setting + Update an existing Configuration Setting by calling Update. ```c# @@ -123,6 +138,7 @@ ConfigurationSetting setting = client.Update("some_key", "new_value"); ``` ### Delete a Configuration Setting + Delete an existing Configuration Setting by calling Delete. ```c# @@ -145,11 +161,11 @@ For example, if you try to retrieve a Configuration Setting that doesn't exist i string connectionString = ; var client = new ConfigurationClient(connectionString); ConfigurationSetting setting = client.Get("some_key"); -```` +``` You will notice that additional information is logged, like the Client Request ID of the operation. -```c# +``` Message: Azure.RequestFailedException : StatusCode: 404, ReasonPhrase: 'Not Found', Version: 1.1, Content: System.Net.Http.NoWriteNoSeekStreamContent, Headers: { Connection: keep-alive @@ -166,8 +182,8 @@ Message: Azure.RequestFailedException : StatusCode: 404, ReasonPhrase: 'Not Foun ## Next Steps ### More sample code -The App Configuration client library, also includes additional functionality that can be set when creating the Configuration Client. -These samples provide example of those scenarios: + +The App Configuration client library includes additional functionality that can be set when creating the Configuration Client. These samples provide example of those scenarios: - [Hello world](samples/Sample1_HelloWorld.cs) - [Hello world async extended](samples/Sample2_HelloWorldExtended.cs) @@ -175,23 +191,24 @@ These samples provide example of those scenarios: - [How to configure retry policy](samples/Sample6_ConfiguringRetries.cs) - [How to configure service requests](samples/Sample7_ConfiguringPipeline.cs) -# Contributing +### Project-to-project references + If the changes you are working on span both Azure.Core and Azure.Configuration then you can set this environment variable before launching Visual Studio. That will use Project To Project references between Azure.Configuration and Azure.Core instead of package references. -This will enable the project to project references: -``` +This will enable the project-to-project references: + +```Batchfile set UseProjectReferenceToAzureBase=true ``` ![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-net%2Fsrc%2FSDKs%2FAzure.ApplicationModel.Configuration%2Fdata-plane%2FREADME.png) - -[azconfig_docs]: https://docs.microsoft.com/en-us/azure/azure-app-configuration/ +[azconfig_docs]: https://docs.microsoft.com/azure/azure-app-configuration/ [azconfig_rest]: https://github.com/Azure/AppConfiguration#rest-api-reference [azure_cli]: https://docs.microsoft.com/cli/azure [azure_sub]: https://azure.microsoft.com/free/ [configuration_client_class]: src/ConfigurationClient.cs -[configuration_store]: https://docs.microsoft.com/en-us/azure/azure-app-configuration/quickstart-dotnet-core-app#create-an-app-configuration-store +[configuration_store]: https://docs.microsoft.com/azure/azure-app-configuration/quickstart-dotnet-core-app#create-an-app-configuration-store [nuget]: https://www.nuget.org/ [package]: https://www.nuget.org/packages/Azure.ApplicationModel.Configuration/