diff --git a/doc/mgmt_preview_quickstart.md b/doc/mgmt_preview_quickstart.md new file mode 100644 index 000000000000..277e203f26f6 --- /dev/null +++ b/doc/mgmt_preview_quickstart.md @@ -0,0 +1,338 @@ + +Quickstart Tutorial - Resource Management (Preview Libraries) +============================================================= + +We are excited to announce that a new set of management libraries are +now in Public Preview. Those packages share a number of new features +such as Azure Identity support, HTTP pipeline, error-handling.,etc, and +they also follow the new Azure SDK guidelines which create easy-to-use +APIs that are idiomatic, compatible, and dependable. + +You can find the details of those new libraries +[here](https://azure.github.io/azure-sdk/releases/latest/#dotnet) + +In this basic quickstart guide, we will walk you through how to +authenticate to Azure using the preview libraries and start interacting +with Azure resources. There are several possible approaches to +authentication. This document illustrates the most common scenario + +Prerequisites +------------- + +You will need the following values to authenticate to Azure + +- **Subscription ID** +- **Client ID** +- **Client Secret** +- **Tenant ID** + +These values can be obtained from the portal, here's the instructions: + +### Get Subscription ID + +1. Login into your Azure account +2. Select Subscriptions in the left sidebar +3. Select whichever subscription is needed +4. Click on Overview +5. Copy the Subscription ID + +### Get Client ID / Client Secret / Tenant ID + +For information on how to get Client ID, Client Secret, and Tenant ID, +please refer to [this +document](https://docs.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal) + +### Setting Environment Variables + +After you obtained the values, you need to set the following values as +your environment variables + +- `AZURE_CLIENT_ID` +- `AZURE_CLIENT_SECRET` +- `AZURE_TENANT_ID` +- `AZURE_SUBSCRIPTION_ID` + +To set the following environment variables on your development system: + +Windows (Note: Administrator access is required) + +1. Open the Control Panel +2. Click System Security, then System +3. Click Advanced system settings on the left +4. Inside the System Properties window, click the Environment + Variables… button. +5. Click on the property you would like to change, then click the Edit… + button. If the property name is not listed, then click the New… + button. + +Linux-based OS : + + export AZURE_CLIENT_ID="__CLIENT_ID__" + export AZURE_CLIENT_SECRET="__CLIENT_SECRET__" + export AZURE_TENANT_ID="__TENANT_ID__" + export AZURE_SUBSCRIPTION_ID="__SUBSCRIPTION_ID__" + +Authentication and Creating Resource Management Client +------------------------------------------------------ + +Now that the environment is setup, all you need to do is to create an +authenticated client. Our default option is to use +**DefaultAzureCredential** and in this guide we have picked +**Resources** as our target service, but you can set it up similarly for +any other service that you are using. **For example, in order to manage Compute or Network resources, you would create a ``ComputeManagementClient`` or ``NetworkManagementClient``** + +To authenticate to Azure and create a management client, simply do the +following: +```csharp + using Azure.Identity; + using Azure.ResourceManager.Resources; + using Azure.ResourceManager.Resources.Models; + using System; + ... + var subscriptionId = Environment.GetEnvironmentVariable("AZURE_SUBSCRIPTION_ID"); + var resourceClient = new ResourcesManagementClient(subscriptionId, new DefaultAzureCredential()); + var resourceGroupsClient = resourceClient.ResourceGroups; +``` +From this code snippet, we showed that in order to interact with Resources, we need to create a top-level client first (**ResourcesManagementClient**), then get the corresponding sub-resource client we are interested in, in this case we called **.ResourceGroups** to get a ResourceGroupsOperations + +For more information and different authentication approaches using Azure +Identity can be found in [this document](https://docs.microsoft.com/dotnet/api/overview/azure/identity-readme?view=azure-dotnet) + +Interacting with Azure Resources +-------------------------------- + +Now that we are authenticated, we can use our management client to make API calls. Let's demonstrate management client's usage by showing concrete examples + +Example: Managing Resource Groups +--------------------------------- +We can use the Resource client (``Azure.ResourceManager.Resources.ResourcesManagementClient``) we have created to perform operations on Resource Group. In this example, we will show to manage Resource Groups. + +***Create a resource group*** + +```csharp + var location = "westus2"; + var resourceGroupName = "myResourceGroupName"; + var resourceGroup = new ResourceGroup(location); + resourceGroup = await resourceGroupsClient.CreateOrUpdateAsync(resourceGroupName, resourceGroup); +``` + +***Update a resource group*** + +```csharp + ... + var newResourceGroup = new ResourceGroup(location); + var resourceGroupName = "myResourceGroupName"; + var tags = new Dictionary(); + tags.Add("environment","test"); + tags.Add("department","tech"); + newResourceGroup.Tags = tags; + // Use existing resource group name and new resource group object + newResourceGroup = await resourceGroupsClient.CreateOrUpdateAsync(resourceGroupName, newResourceGroup); +``` + + +***List all resource groups*** + +```csharp + AsyncPageable response = resourceGroupsClient.ListAsync(); + await foreach (ResourceGroup rg in response) + { + Console.WriteLine(rg.Name); + } +``` + +***Delete a resource group*** + +```csharp + await resourceGroupsClient.StartDeleteAsync(groupName); +``` + +Example: Creating a Virtual Machine +----------------------------------- +Let's show a concrete example of how you would create a virtual machine using .NET SDK +```csharp +using System.Collections.Generic; +using System.Linq; +using System.Threading.Tasks; + +using Azure.Identity; +using Azure.ResourceManager.Compute; +using Azure.ResourceManager.Compute.Models; +using Azure.ResourceManager.Network; +using Azure.ResourceManager.Network.Models; +using Azure.ResourceManager.Resources; +using Azure.ResourceManager.Resources.Models; + +namespace AzureCreateVMSample +{ + /// + /// Create a Virtual Machine + /// + public class CreateVMSample + { + public static async Task CreateVmAsync( + string subscriptionId, + string resourceGroupName, + string location, + string vmName) + { + var computeClient = new ComputeManagementClient(subscriptionId, new DefaultAzureCredential()); + var networkClient = new NetworkManagementClient(subscriptionId, new DefaultAzureCredential()); + var resourcesClient = new ResourcesManagementClient(subscriptionId, new DefaultAzureCredential()); + + var virtualNetworksClient = networkClient.VirtualNetworks; + var networkInterfaceClient = networkClient.NetworkInterfaces; + var publicIpAddressClient = networkClient.PublicIPAddressses; + var availabilitySetsClient = computeClient.AvailabilitySets; + var virtualMachinesClient = computeClient.VirtualMachines; + var resourceGroupClient = resourcesClient.ResourceGroups; + + // Create Resource Group + var resourceGroup = new ResourceGroup(location); + resourceGroup = await resourceGroupClient.CreateOrUpdateAsync(resourceGroupName, resourceGroup); + + // Create AvailabilitySet + var availabilitySet = new AvailabilitySet(location) + { + PlatformUpdateDomainCount = 5, + PlatformFaultDomainCount = 2, + Sku = new Sku() { Name = "Aligned" } // TODO. Verify new codegen on AvailabilitySetSkuTypes.Aligned + }; + + availabilitySet = await availabilitySetsClient.CreateOrUpdateAsync(resourceGroupName, vmName + "_aSet", availabilitySet); + + // Create IP Address + var ipAddress = new PublicIPAddress() + { + PublicIPAddressVersion = IPVersion.IPv4, + PublicIPAllocationMethod = IPAllocationMethod.Dynamic, + Location = location, + }; + + ipAddress = await publicIpAddressClient.StartCreateOrUpdate(resourceGroupName, vmName + "_ip", ipAddress) + .WaitForCompletionAsync(); + + // Create VNet + var vnet = new VirtualNetwork() + { + Location = location, + AddressSpace = new AddressSpace() { AddressPrefixes = new List() { "10.0.0.0/16" } }, + Subnets = new List() + { + new Subnet() + { + Name = "mySubnet", + AddressPrefix = "10.0.0.0/24", + } + }, + }; + + vnet = await virtualNetworksClient + .StartCreateOrUpdate(resourceGroupName, vmName + "_vent", vnet) + .WaitForCompletionAsync(); + + // Create Network interface + var nic = new NetworkInterface() + { + Location = location, + IpConfigurations = new List() + { + new NetworkInterfaceIPConfiguration() + { + Name = "Primary", + Primary = true, + Subnet = new Subnet() { Id = vnet.Subnets.First().Id }, + PrivateIPAllocationMethod = IPAllocationMethod.Dynamic, + PublicIPAddress = new PublicIPAddress() { Id = ipAddress.Id } + } + } + }; + + nic = await networkInterfaceClient + .StartCreateOrUpdate(resourceGroupName, vmName + "_nic", nic) + .WaitForCompletionAsync(); + + var vm = new VirtualMachine(location) + { + NetworkProfile = new Compute.Models.NetworkProfile { NetworkInterfaces = new[] { new NetworkInterfaceReference() { Id = nic.Id } } }, + OsProfile = new OSProfile + { + ComputerName = "testVM", + AdminUsername = "username", + AdminPassword = "(YourPassword)", + LinuxConfiguration = new LinuxConfiguration { DisablePasswordAuthentication = false, ProvisionVMAgent = true } + }, + StorageProfile = new StorageProfile() + { + ImageReference = new ImageReference() + { + Offer = "UbuntuServer", + Publisher = "Canonical", + Sku = "18.04-LTS", + Version = "latest" + }, + DataDisks = new List() + }, + HardwareProfile = new HardwareProfile() { VmSize = VirtualMachineSizeTypes.StandardB1Ms }, + }; + vm.AvailabilitySet.Id = availabilitySet.Id; + + var operaiontion = await virtualMachinesClient.StartCreateOrUpdateAsync(resourceGroupName, vmName, vm); + var vm = (await operaiontion.WaitForCompletionAsync()).Value; + } + } +} + +``` + +Driver program + +```csharp +using System; +using System.Threading.Tasks; + +namespace AzureCreateVMSample +{ + class Program + { + static async Task Main(string[] args) + { + var subscriptionId = Environment.GetEnvironmentVariable("AZURE_SUBSCRIPTION_ID"); + var location = "westus2"; + + await CreateVMSample.CreateVmAsync(subscriptionId, "myResourceGroupName", location, "myVirtualMachine"); + } + } +} +``` + +Need help? +---------- + +- File an issue via [Github + Issues](https://github.com/Azure/azure-sdk-for-net/issues) and + make sure you add the "Preview" label to the issue +- Check [previous + questions](https://stackoverflow.com/questions/tagged/azure+.net) + or ask new ones on StackOverflow using azure and .NET tags. + +Contributing +------------ + +For details on contributing to this repository, see the contributing +guide. + +This project welcomes contributions and suggestions. Most contributions +require you to agree to a Contributor License Agreement (CLA) declaring +that you have the right to, and actually do, grant us the rights to use +your contribution. For details, visit . + +When you submit a pull request, a CLA-bot will automatically determine +whether you need to provide a CLA and decorate the PR appropriately +(e.g., label, comment). Simply follow the instructions provided by the +bot. You will only need to do this once across all repositories using +our CLA. + +This project has adopted the Microsoft Open Source Code of Conduct. For +more information see the Code of Conduct FAQ or contact + with any additional questions or comments. diff --git a/sdk/appconfiguration/Azure.ResourceManager.AppConfiguration/README.md b/sdk/appconfiguration/Azure.ResourceManager.AppConfiguration/README.md index 5cd4c6261230..859018866a68 100644 --- a/sdk/appconfiguration/Azure.ResourceManager.AppConfiguration/README.md +++ b/sdk/appconfiguration/Azure.ResourceManager.AppConfiguration/README.md @@ -1,67 +1,74 @@ -# README.md template +# Azure App Configuration Management client library for .NET -Use the guidelines in each section of this template to ensure consistency and readability of your README. The README resides in your package's GitHub repository at the root of its directory within the repo. It's also used as the package distribution page (NuGet, PyPi, npm, etc.) and as a Quickstart on docs.microsoft.com. See [README-EXAMPLE.md](README-EXAMPLE.md) for an example following this template. +This package follows the [new Azure SDK guidelines](https://azure.github.io/azure-sdk/general_introduction.html) which provide a number of core capabilities that are shared amongst all Azure SDKs, including the intuitive Azure Identity library, an HTTP Pipeline with custom policies, error-handling, distributed tracing, and much more. -* All headings, including the H1, should use **sentence-style capitalization**. Refer to the [Microsoft Style Guide][style-guide-msft] and [Microsoft Cloud Style Guide][style-guide-cloud] for more information. -* Example: `# Azure Batch client library for Python` - -# Azure Management AppConfiguration client library for .NET - -**Introduction**: The introduction appears directly under the title (H1) of your README. - -* **DO NOT** use an "Introduction" or "Overview" heading (H2) for this section. -* First sentence: **Describe the service** briefly. You can usually use the first line of the service's docs landing page for this (Example: [Cosmos DB docs landing page](https://docs.microsoft.com/azure/cosmos-db/)). -* Next, add a **bulleted list** of the **most common tasks** supported by the package or library, prefaced with "Use the client library for [Product Name] to:". Then, provide code snippets for these tasks in the [Examples](#examples) section later in the document. Keep the task list short but include those tasks most developers need to perform with your package. -* Include this single line of links targeting your product's content at the bottom of the introduction, making any adjustments as necessary (for example, NuGet instead of PyPi): - - - [Source code](https://github.com/Azure/azure-sdk-for-python/tree/master/azure-batch) | [Package (PyPi)](https://pypi.org/project/azure-batch/) | [API reference documentation](https://docs.microsoft.com/python/api/overview/azure/batch?view=azure-python) | [Product documentation](https://docs.microsoft.com/azure/batch/) - -> TIP: Your README should be as **brief** as possible but **no more brief** than necessary to get a developer new to Azure, the service, or the package up and running quickly. Keep it brief, but include everything a developer needs to make their first API call successfully. - -## Getting started - -This section should include everything a developer needs to do to install and create their first client connection *very quickly*. +## Getting started ### Install the package -First, provide instruction for obtaining and installing the package or library. This section might include only a single line of code, like `pip install package-name`, but should enable a developer to successfully install the package from NuGet, pip, npm, Maven, or even cloning a GitHub repository. +Install the Azure App Configuration management library for .NET with [NuGet](https://www.nuget.org/): + +```PowerShell +Install-Package Azure.ResourceManager.AppConfiguration -Version 1.0.0-preview.1 +``` ### Prerequisites * You must have an [Azure subscription](https://azure.microsoft.com/free/) -### Authenticate the client +### Authenticate the Client -If your library requires authentication for use, such as for Azure services, include instructions and example code needed for initializing and authenticating. - -For example, include details on obtaining an account key and endpoint URI, setting environment variables for each, and initializing the client object. +To create an authenticated client and start interacting with Azure resources, please see the [quickstart guide here](https://github.com/Azure/azure-sdk-for-net/blob/master/doc/mgmt_preview_quickstart.md) ## Key concepts -The *Key concepts* section should describe the functionality of the main classes. Point out the most important and useful classes in the package (with links to their reference pages) and explain how those classes work together. Feel free to use bulleted lists, tables, code blocks, or even diagrams for clarity. +Key concepts of the Azure .NET SDK can be found [here](https://azure.github.io/azure-sdk/dotnet_introduction.html) + +## Documentation + +Documentation is available to help you learn how to use this package + +- [Quickstart](https://github.com/Azure/azure-sdk-for-net/blob/master/doc/mgmt_preview_quickstart.md) +- [API References](https://docs.microsoft.com/dotnet/api/?view=azure-dotnet) +- [Authentication](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/identity/Azure.Identity/README.md) ## Examples -Include code snippets and short descriptions for each task you listed in the [Introduction](#introduction) (the bulleted list). Briefly explain each operation, but include enough clarity to explain complex or otherwise tricky operations. +Code samples for using the management library for .NET can be found in the following locations +- [.NET Management Library Code Samples](https://docs.microsoft.com/samples/browse/?branch=master&languages=csharp&term=managing%20using%20Azure%20.NET%20SDK) ## Troubleshooting -Describe common errors and exceptions, how to "unpack" them if necessary, and include guidance for graceful handling and recovery. +- File an issue via [Github + Issues](https://github.com/Azure/azure-sdk-for-net/issues) +- Check [previous + questions](https://stackoverflow.com/questions/tagged/azure+.net) + or ask new ones on Stack Overflow using azure and .net tags. -Provide information to help developers avoid throttling or other service-enforced errors they might encounter. For example, provide guidance and examples for using retry or connection policies in the API. - -If the package or a related package supports it, include tips for logging or enabling instrumentation to help them debug their code. ## Next steps -* Provide a link to additional code examples, ideally to those sitting alongside the README in the package's `/samples` directory. -* If appropriate, point users to other packages that might be useful. -* If you think there's a good chance that developers might stumble across your package in error (because they're searching for specific functionality and mistakenly think the package provides that functionality), point them to the packages they might be looking for. +For more information on Azure SDK, please refer to [this website](https://azure.github.io/azure-sdk/) ## Contributing -This is a template, but your SDK readme should include details on how to contribute code to the repo/package. +For details on contributing to this repository, see the contributing +guide. + +This project welcomes contributions and suggestions. Most contributions +require you to agree to a Contributor License Agreement (CLA) declaring +that you have the right to, and actually do, grant us the rights to use +your contribution. For details, visit . + +When you submit a pull request, a CLA-bot will automatically determine +whether you need to provide a CLA and decorate the PR appropriately +(e.g., label, comment). Simply follow the instructions provided by the +bot. You will only need to do this once across all repositories using +our CLA. + +This project has adopted the Microsoft Open Source Code of Conduct. For +more information see the Code of Conduct FAQ or contact + with any additional questions or comments. [style-guide-msft]: https://docs.microsoft.com/style-guide/capitalization diff --git a/sdk/compute/Azure.ResourceManager.Compute/README.md b/sdk/compute/Azure.ResourceManager.Compute/README.md index 87028f10e725..e684de84f409 100644 --- a/sdk/compute/Azure.ResourceManager.Compute/README.md +++ b/sdk/compute/Azure.ResourceManager.Compute/README.md @@ -1,69 +1,77 @@ -# README.md template +# Azure Compute Management client library for .NET -Use the guidelines in each section of this template to ensure consistency and readability of your README. The README resides in your package's GitHub repository at the root of its directory within the repo. It's also used as the package distribution page (NuGet, PyPi, npm, etc.) and as a Quickstart on docs.microsoft.com. See [README-EXAMPLE.md](README-EXAMPLE.md) for an example following this template. +This package follows the [new Azure SDK guidelines](https://azure.github.io/azure-sdk/general_introduction.html) which provide a number of core capabilities that are shared amongst all Azure SDKs, including the intuitive Azure Identity library, an HTTP Pipeline with custom policies, error-handling, distributed tracing, and much more. -* All headings, including the H1, should use **sentence-style capitalization**. Refer to the [Microsoft Style Guide][style-guide-msft] and [Microsoft Cloud Style Guide][style-guide-cloud] for more information. -* Example: `# Azure Batch client library for Python` - -# Azure Management Compute client library for .NET - -**Introduction**: The introduction appears directly under the title (H1) of your README. - -* **DO NOT** use an "Introduction" or "Overview" heading (H2) for this section. -* First sentence: **Describe the service** briefly. You can usually use the first line of the service's docs landing page for this (Example: [Cosmos DB docs landing page](https://docs.microsoft.com/azure/cosmos-db/)). -* Next, add a **bulleted list** of the **most common tasks** supported by the package or library, prefaced with "Use the client library for [Product Name] to:". Then, provide code snippets for these tasks in the [Examples](#examples) section later in the document. Keep the task list short but include those tasks most developers need to perform with your package. -* Include this single line of links targeting your product's content at the bottom of the introduction, making any adjustments as necessary (for example, NuGet instead of PyPi): - - [Source code](https://github.com/Azure/azure-sdk-for-python/tree/master/azure-batch) | [Package (PyPi)](https://pypi.org/project/azure-batch/) | [API reference documentation](https://docs.microsoft.com/python/api/overview/azure/batch?view=azure-python) | [Product documentation](https://docs.microsoft.com/azure/batch/) - -> TIP: Your README should be as **brief** as possible but **no more brief** than necessary to get a developer new to Azure, the service, or the package up and running quickly. Keep it brief, but include everything a developer needs to make their first API call successfully. - -## Getting started - -This section should include everything a developer needs to do to install and create their first client connection *very quickly*. +## Getting started ### Install the package -First, provide instruction for obtaining and installing the package or library. This section might include only a single line of code, like `pip install package-name`, but should enable a developer to successfully install the package from NuGet, pip, npm, Maven, or even cloning a GitHub repository. +Install the Azure Compute management library for .NET with [NuGet](https://www.nuget.org/): + +```PowerShell +Install-Package Azure.ResourceManager.Compute -Version 1.0.0-preview.1 +``` ### Prerequisites * You must have an [Azure subscription](https://azure.microsoft.com/free/) -### Authenticate the client +### Authenticate the Client -If your library requires authentication for use, such as for Azure services, include instructions and example code needed for initializing and authenticating. - -For example, include details on obtaining an account key and endpoint URI, setting environment variables for each, and initializing the client object. +To create an authenticated client and start interacting with Azure resources, please see the [quickstart guide here](https://github.com/Azure/azure-sdk-for-net/blob/master/doc/mgmt_preview_quickstart.md) ## Key concepts -The *Key concepts* section should describe the functionality of the main classes. Point out the most important and useful classes in the package (with links to their reference pages) and explain how those classes work together. Feel free to use bulleted lists, tables, code blocks, or even diagrams for clarity. +Key concepts of the Azure .NET SDK can be found [here](https://azure.github.io/azure-sdk/dotnet_introduction.html) + +## Documentation + +Documentation is available to help you learn how to use this package + +- [Quickstart](https://github.com/Azure/azure-sdk-for-net/blob/master/doc/mgmt_preview_quickstart.md) +- [API References](https://docs.microsoft.com/dotnet/api/?view=azure-dotnet) +- [Authentication](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/identity/Azure.Identity/README.md) ## Examples -Include code snippets and short descriptions for each task you listed in the [Introduction](#introduction) (the bulleted list). Briefly explain each operation, but include enough clarity to explain complex or otherwise tricky operations. +Code samples for using the management library for .NET can be found in the following locations +- [.NET Management Library Code Samples](https://docs.microsoft.com/samples/browse/?branch=master&languages=csharp&term=managing%20using%20Azure%20.NET%20SDK) ## Troubleshooting -Describe common errors and exceptions, how to "unpack" them if necessary, and include guidance for graceful handling and recovery. +- File an issue via [Github + Issues](https://github.com/Azure/azure-sdk-for-net/issues) +- Check [previous + questions](https://stackoverflow.com/questions/tagged/azure+.net) + or ask new ones on Stack Overflow using azure and .net tags. -Provide information to help developers avoid throttling or other service-enforced errors they might encounter. For example, provide guidance and examples for using retry or connection policies in the API. - -If the package or a related package supports it, include tips for logging or enabling instrumentation to help them debug their code. ## Next steps -* Provide a link to additional code examples, ideally to those sitting alongside the README in the package's `/samples` directory. -* If appropriate, point users to other packages that might be useful. -* If you think there's a good chance that developers might stumble across your package in error (because they're searching for specific functionality and mistakenly think the package provides that functionality), point them to the packages they might be looking for. +For more information on Azure SDK, please refer to [this website](https://azure.github.io/azure-sdk/) ## Contributing -This is a template, but your SDK readme should include details on how to contribute code to the repo/package. +For details on contributing to this repository, see the contributing +guide. + +This project welcomes contributions and suggestions. Most contributions +require you to agree to a Contributor License Agreement (CLA) declaring +that you have the right to, and actually do, grant us the rights to use +your contribution. For details, visit . + +When you submit a pull request, a CLA-bot will automatically determine +whether you need to provide a CLA and decorate the PR appropriately +(e.g., label, comment). Simply follow the instructions provided by the +bot. You will only need to do this once across all repositories using +our CLA. + +This project has adopted the Microsoft Open Source Code of Conduct. For +more information see the Code of Conduct FAQ or contact + with any additional questions or comments. [style-guide-msft]: https://docs.microsoft.com/style-guide/capitalization [style-guide-cloud]: https://worldready.cloudapp.net/Styleguide/Read?id=2696&topicid=25357 -![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-net%2Fsdk%2Fcompute%2FAzure.ResourceManager.Compute%2FREADME.png) +![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-net%2Fsdk%2Ftemplate%2FAzure.Template%2FREADME.png) diff --git a/sdk/eventhub/Azure.ResourceManager.EventHubs/README.md b/sdk/eventhub/Azure.ResourceManager.EventHubs/README.md index 9dfec6e4102c..4efd94c3ea54 100644 --- a/sdk/eventhub/Azure.ResourceManager.EventHubs/README.md +++ b/sdk/eventhub/Azure.ResourceManager.EventHubs/README.md @@ -1,66 +1,74 @@ -# README.md template +# Azure Event Hubs Management client library for .NET -Use the guidelines in each section of this template to ensure consistency and readability of your README. The README resides in your package's GitHub repository at the root of its directory within the repo. It's also used as the package distribution page (NuGet, PyPi, npm, etc.) and as a Quickstart on docs.microsoft.com. See [README-EXAMPLE.md](README-EXAMPLE.md) for an example following this template. +This package follows the [new Azure SDK guidelines](https://azure.github.io/azure-sdk/general_introduction.html) which provide a number of core capabilities that are shared amongst all Azure SDKs, including the intuitive Azure Identity library, an HTTP Pipeline with custom policies, error-handling, distributed tracing, and much more. -* All headings, including the H1, should use **sentence-style capitalization**. Refer to the [Microsoft Style Guide][style-guide-msft] and [Microsoft Cloud Style Guide][style-guide-cloud] for more information. -* Example: `# Azure Batch client library for Python` - -# Azure Management EventHub client library for .NET - -**Introduction**: The introduction appears directly under the title (H1) of your README. - -* **DO NOT** use an "Introduction" or "Overview" heading (H2) for this section. -* First sentence: **Describe the service** briefly. You can usually use the first line of the service's docs landing page for this (Example: [Cosmos DB docs landing page](https://docs.microsoft.com/azure/cosmos-db/)). -* Next, add a **bulleted list** of the **most common tasks** supported by the package or library, prefaced with "Use the client library for [Product Name] to:". Then, provide code snippets for these tasks in the [Examples](#examples) section later in the document. Keep the task list short but include those tasks most developers need to perform with your package. -* Include this single line of links targeting your product's content at the bottom of the introduction, making any adjustments as necessary (for example, NuGet instead of PyPi): - - [Source code](https://github.com/Azure/azure-sdk-for-python/tree/master/azure-batch) | [Package (PyPi)](https://pypi.org/project/azure-batch/) | [API reference documentation](https://docs.microsoft.com/python/api/overview/azure/batch?view=azure-python) | [Product documentation](https://docs.microsoft.com/azure/batch/) - -> TIP: Your README should be as **brief** as possible but **no more brief** than necessary to get a developer new to Azure, the service, or the package up and running quickly. Keep it brief, but include everything a developer needs to make their first API call successfully. - -## Getting started - -This section should include everything a developer needs to do to install and create their first client connection *very quickly*. +## Getting started ### Install the package -First, provide instruction for obtaining and installing the package or library. This section might include only a single line of code, like `pip install package-name`, but should enable a developer to successfully install the package from NuGet, pip, npm, Maven, or even cloning a GitHub repository. +Install the Azure Event Hubs management library for .NET with [NuGet](https://www.nuget.org/): + +```PowerShell +Install-Package Azure.ResourceManager.EventHubs -Version 1.0.0-preview.1 +``` ### Prerequisites * You must have an [Azure subscription](https://azure.microsoft.com/free/) -### Authenticate the client +### Authenticate the Client -If your library requires authentication for use, such as for Azure services, include instructions and example code needed for initializing and authenticating. - -For example, include details on obtaining an account key and endpoint URI, setting environment variables for each, and initializing the client object. +To create an authenticated client and start interacting with Azure resources, please see the [quickstart guide here](https://github.com/Azure/azure-sdk-for-net/blob/master/doc/mgmt_preview_quickstart.md) ## Key concepts -The *Key concepts* section should describe the functionality of the main classes. Point out the most important and useful classes in the package (with links to their reference pages) and explain how those classes work together. Feel free to use bulleted lists, tables, code blocks, or even diagrams for clarity. +Key concepts of the Azure .NET SDK can be found [here](https://azure.github.io/azure-sdk/dotnet_introduction.html) + +## Documentation + +Documentation is available to help you learn how to use this package + +- [Quickstart](https://github.com/Azure/azure-sdk-for-net/blob/master/doc/mgmt_preview_quickstart.md) +- [API References](https://docs.microsoft.com/dotnet/api/?view=azure-dotnet) +- [Authentication](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/identity/Azure.Identity/README.md) ## Examples -Include code snippets and short descriptions for each task you listed in the [Introduction](#introduction) (the bulleted list). Briefly explain each operation, but include enough clarity to explain complex or otherwise tricky operations. +Code samples for using the management library for .NET can be found in the following locations +- [.NET Management Library Code Samples](https://docs.microsoft.com/samples/browse/?branch=master&languages=csharp&term=managing%20using%20Azure%20.NET%20SDK) ## Troubleshooting -Describe common errors and exceptions, how to "unpack" them if necessary, and include guidance for graceful handling and recovery. +- File an issue via [Github + Issues](https://github.com/Azure/azure-sdk-for-net/issues) +- Check [previous + questions](https://stackoverflow.com/questions/tagged/azure+.net) + or ask new ones on Stack Overflow using azure and .net tags. -Provide information to help developers avoid throttling or other service-enforced errors they might encounter. For example, provide guidance and examples for using retry or connection policies in the API. - -If the package or a related package supports it, include tips for logging or enabling instrumentation to help them debug their code. ## Next steps -* Provide a link to additional code examples, ideally to those sitting alongside the README in the package's `/samples` directory. -* If appropriate, point users to other packages that might be useful. -* If you think there's a good chance that developers might stumble across your package in error (because they're searching for specific functionality and mistakenly think the package provides that functionality), point them to the packages they might be looking for. +For more information on Azure SDK, please refer to [this website](https://azure.github.io/azure-sdk/) ## Contributing -This is a template, but your SDK readme should include details on how to contribute code to the repo/package. +For details on contributing to this repository, see the contributing +guide. + +This project welcomes contributions and suggestions. Most contributions +require you to agree to a Contributor License Agreement (CLA) declaring +that you have the right to, and actually do, grant us the rights to use +your contribution. For details, visit . + +When you submit a pull request, a CLA-bot will automatically determine +whether you need to provide a CLA and decorate the PR appropriately +(e.g., label, comment). Simply follow the instructions provided by the +bot. You will only need to do this once across all repositories using +our CLA. + +This project has adopted the Microsoft Open Source Code of Conduct. For +more information see the Code of Conduct FAQ or contact + with any additional questions or comments. [style-guide-msft]: https://docs.microsoft.com/style-guide/capitalization diff --git a/sdk/keyvault/Azure.ResourceManager.KeyVault/README.md b/sdk/keyvault/Azure.ResourceManager.KeyVault/README.md index 5c2635a1adb5..5e1ca5c23de3 100644 --- a/sdk/keyvault/Azure.ResourceManager.KeyVault/README.md +++ b/sdk/keyvault/Azure.ResourceManager.KeyVault/README.md @@ -1,66 +1,74 @@ -# README.md template +# Azure Key Vault Management client library for .NET -Use the guidelines in each section of this template to ensure consistency and readability of your README. The README resides in your package's GitHub repository at the root of its directory within the repo. It's also used as the package distribution page (NuGet, PyPi, npm, etc.) and as a Quickstart on docs.microsoft.com. See [README-EXAMPLE.md](README-EXAMPLE.md) for an example following this template. +This package follows the [new Azure SDK guidelines](https://azure.github.io/azure-sdk/general_introduction.html) which provide a number of core capabilities that are shared amongst all Azure SDKs, including the intuitive Azure Identity library, an HTTP Pipeline with custom policies, error-handling, distributed tracing, and much more. -* All headings, including the H1, should use **sentence-style capitalization**. Refer to the [Microsoft Style Guide][style-guide-msft] and [Microsoft Cloud Style Guide][style-guide-cloud] for more information. -* Example: `# Azure Batch client library for Python` - -# Azure Management KeyVault client library for .NET - -**Introduction**: The introduction appears directly under the title (H1) of your README. - -* **DO NOT** use an "Introduction" or "Overview" heading (H2) for this section. -* First sentence: **Describe the service** briefly. You can usually use the first line of the service's docs landing page for this (Example: [Cosmos DB docs landing page](https://docs.microsoft.com/azure/cosmos-db/)). -* Next, add a **bulleted list** of the **most common tasks** supported by the package or library, prefaced with "Use the client library for [Product Name] to:". Then, provide code snippets for these tasks in the [Examples](#examples) section later in the document. Keep the task list short but include those tasks most developers need to perform with your package. -* Include this single line of links targeting your product's content at the bottom of the introduction, making any adjustments as necessary (for example, NuGet instead of PyPi): - - [Source code](https://github.com/Azure/azure-sdk-for-python/tree/master/azure-batch) | [Package (PyPi)](https://pypi.org/project/azure-batch/) | [API reference documentation](https://docs.microsoft.com/python/api/overview/azure/batch?view=azure-python) | [Product documentation](https://docs.microsoft.com/azure/batch/) - -> TIP: Your README should be as **brief** as possible but **no more brief** than necessary to get a developer new to Azure, the service, or the package up and running quickly. Keep it brief, but include everything a developer needs to make their first API call successfully. - -## Getting started - -This section should include everything a developer needs to do to install and create their first client connection *very quickly*. +## Getting started ### Install the package -First, provide instruction for obtaining and installing the package or library. This section might include only a single line of code, like `pip install package-name`, but should enable a developer to successfully install the package from NuGet, pip, npm, Maven, or even cloning a GitHub repository. +Install the Azure Key Vault management library for .NET with [NuGet](https://www.nuget.org/): + +```PowerShell +Install-Package Azure.ResourceManager.KeyVault -Version 1.0.0-preview.1 +``` ### Prerequisites * You must have an [Azure subscription](https://azure.microsoft.com/free/) -### Authenticate the client +### Authenticate the Client -If your library requires authentication for use, such as for Azure services, include instructions and example code needed for initializing and authenticating. - -For example, include details on obtaining an account key and endpoint URI, setting environment variables for each, and initializing the client object. +To create an authenticated client and start interacting with Azure resources, please see the [quickstart guide here](https://github.com/Azure/azure-sdk-for-net/blob/master/doc/mgmt_preview_quickstart.md) ## Key concepts -The *Key concepts* section should describe the functionality of the main classes. Point out the most important and useful classes in the package (with links to their reference pages) and explain how those classes work together. Feel free to use bulleted lists, tables, code blocks, or even diagrams for clarity. +Key concepts of the Azure .NET SDK can be found [here](https://azure.github.io/azure-sdk/dotnet_introduction.html) + +## Documentation + +Documentation is available to help you learn how to use this package + +- [Quickstart](https://github.com/Azure/azure-sdk-for-net/blob/master/doc/mgmt_preview_quickstart.md) +- [API References](https://docs.microsoft.com/dotnet/api/?view=azure-dotnet) +- [Authentication](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/identity/Azure.Identity/README.md) ## Examples -Include code snippets and short descriptions for each task you listed in the [Introduction](#introduction) (the bulleted list). Briefly explain each operation, but include enough clarity to explain complex or otherwise tricky operations. +Code samples for using the management library for .NET can be found in the following locations +- [.NET Management Library Code Samples](https://docs.microsoft.com/samples/browse/?branch=master&languages=csharp&term=managing%20using%20Azure%20.NET%20SDK) ## Troubleshooting -Describe common errors and exceptions, how to "unpack" them if necessary, and include guidance for graceful handling and recovery. +- File an issue via [Github + Issues](https://github.com/Azure/azure-sdk-for-net/issues) +- Check [previous + questions](https://stackoverflow.com/questions/tagged/azure+.net) + or ask new ones on Stack Overflow using azure and .net tags. -Provide information to help developers avoid throttling or other service-enforced errors they might encounter. For example, provide guidance and examples for using retry or connection policies in the API. - -If the package or a related package supports it, include tips for logging or enabling instrumentation to help them debug their code. ## Next steps -* Provide a link to additional code examples, ideally to those sitting alongside the README in the package's `/samples` directory. -* If appropriate, point users to other packages that might be useful. -* If you think there's a good chance that developers might stumble across your package in error (because they're searching for specific functionality and mistakenly think the package provides that functionality), point them to the packages they might be looking for. +For more information on Azure SDK, please refer to [this website](https://azure.github.io/azure-sdk/) ## Contributing -This is a template, but your SDK readme should include details on how to contribute code to the repo/package. +For details on contributing to this repository, see the contributing +guide. + +This project welcomes contributions and suggestions. Most contributions +require you to agree to a Contributor License Agreement (CLA) declaring +that you have the right to, and actually do, grant us the rights to use +your contribution. For details, visit . + +When you submit a pull request, a CLA-bot will automatically determine +whether you need to provide a CLA and decorate the PR appropriately +(e.g., label, comment). Simply follow the instructions provided by the +bot. You will only need to do this once across all repositories using +our CLA. + +This project has adopted the Microsoft Open Source Code of Conduct. For +more information see the Code of Conduct FAQ or contact + with any additional questions or comments. [style-guide-msft]: https://docs.microsoft.com/style-guide/capitalization diff --git a/sdk/network/Azure.ResourceManager.Network/README.md b/sdk/network/Azure.ResourceManager.Network/README.md index 08f8195841f1..857fe9f0c159 100644 --- a/sdk/network/Azure.ResourceManager.Network/README.md +++ b/sdk/network/Azure.ResourceManager.Network/README.md @@ -1,77 +1,77 @@ -# README.md template +# Azure Network Management client library for .NET -Use the guidelines in each section of this template to ensure consistency and readability of your README. The README resides in your package's GitHub repository at the root of its directory within the repo. It's also used as the package distribution page (NuGet, PyPi, npm, etc.) and as a Quickstart on docs.microsoft.com. See [README-EXAMPLE.md](README-EXAMPLE.md) for an example following this template. +This package follows the [new Azure SDK guidelines](https://azure.github.io/azure-sdk/general_introduction.html) which provide a number of core capabilities that are shared amongst all Azure SDKs, including the intuitive Azure Identity library, an HTTP Pipeline with custom policies, error-handling, distributed tracing, and much more. -* All headings, including the H1, should use **sentence-style capitalization**. Refer to the [Microsoft Style Guide][style-guide-msft] and [Microsoft Cloud Style Guide][style-guide-cloud] for more information. -* Example: `# Azure Batch client library for Python` - -# Azure Management Network client library for .NET - -**Introduction**: The introduction appears directly under the title (H1) of your README. - -* **DO NOT** use an "Introduction" or "Overview" heading (H2) for this section. -* First sentence: **Describe the service** briefly. You can usually use the first line of the service's docs landing page for this (Example: [Cosmos DB docs landing page](https://docs.microsoft.com/azure/cosmos-db/)). -* Next, add a **bulleted list** of the **most common tasks** supported by the package or library, prefaced with "Use the client library for [Product Name] to:". Then, provide code snippets for these tasks in the [Examples](#examples) section later in the document. Keep the task list short but include those tasks most developers need to perform with your package. -* Include this single line of links targeting your product's content at the bottom of the introduction, making any adjustments as necessary (for example, NuGet instead of PyPi): - - [Source code](https://github.com/Azure/azure-sdk-for-python/tree/master/azure-batch) | [Package (PyPi)](https://pypi.org/project/azure-batch/) | [API reference documentation](https://docs.microsoft.com/python/api/overview/azure/batch?view=azure-python) | [Product documentation](https://docs.microsoft.com/azure/batch/) - -> TIP: Your README should be as **brief** as possible but **no more brief** than necessary to get a developer new to Azure, the service, or the package up and running quickly. Keep it brief, but include everything a developer needs to make their first API call successfully. - -## Getting started - -This section should include everything a developer needs to do to install and create their first client connection *very quickly*. +## Getting started ### Install the package -First, provide instruction for obtaining and installing the package or library. This section might include only a single line of code, like `pip install package-name`, but should enable a developer to successfully install the package from NuGet, pip, npm, Maven, or even cloning a GitHub repository. +Install the Azure Network management library for .NET with [NuGet](https://www.nuget.org/): + +```PowerShell +Install-Package Azure.ResourceManager.Network -Version 1.0.0-preview.1 +``` ### Prerequisites * You must have an [Azure subscription](https://azure.microsoft.com/free/) -### Authenticate the client +### Authenticate the Client -If your library requires authentication for use, such as for Azure services, include instructions and example code needed for initializing and authenticating. - -For example, include details on obtaining an account key and endpoint URI, setting environment variables for each, and initializing the client object. +To create an authenticated client and start interacting with Azure resources, please see the [quickstart guide here](https://github.com/Azure/azure-sdk-for-net/blob/master/doc/mgmt_preview_quickstart.md) ## Key concepts -The *Key concepts* section should describe the functionality of the main classes. Point out the most important and useful classes in the package (with links to their reference pages) and explain how those classes work together. Feel free to use bulleted lists, tables, code blocks, or even diagrams for clarity. +Key concepts of the Azure .NET SDK can be found [here](https://azure.github.io/azure-sdk/dotnet_introduction.html) -## Examples +## Documentation -Include code snippets and short descriptions for each task you listed in the [Introduction](#introduction) (the bulleted list). Briefly explain each operation, but include enough clarity to explain complex or otherwise tricky operations. +Documentation is available to help you learn how to use this package -If possible, use the same example snippets that your in-code documentation uses. For example, use the snippets in your `examples.py` that Sphinx ingests via its [literalinclude](https://www.sphinx-doc.org/en/1.5/markup/code.html?highlight=code%20examples#includes) directive. The `examples.py` file containing the snippets should reside alongside your package's code, and should be tested in an automated fashion. +- [Quickstart](https://github.com/Azure/azure-sdk-for-net/blob/master/doc/mgmt_preview_quickstart.md) +- [API References](https://docs.microsoft.com/dotnet/api/?view=azure-dotnet) +- [Authentication](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/identity/Azure.Identity/README.md) -Each example in the *Examples* section starts with an H3 that describes the example. At the top of this section, just under the *Examples* H2, add a bulleted list linking to each example H3. Each example should deep-link to the types and/or members used in the example. +## Examples -* [Create the thing](#create-the-thing) -* [Get the thing](#get-the-thing) -* [List the things](#list-the-things) +Code samples for using the management library for .NET can be found in the following locations +- [.NET Management Library Code Samples](https://docs.microsoft.com/samples/browse/?branch=master&languages=csharp&term=managing%20using%20Azure%20.NET%20SDK) ## Troubleshooting -Describe common errors and exceptions, how to "unpack" them if necessary, and include guidance for graceful handling and recovery. - -Provide information to help developers avoid throttling or other service-enforced errors they might encounter. For example, provide guidance and examples for using retry or connection policies in the API. +- File an issue via [Github + Issues](https://github.com/Azure/azure-sdk-for-net/issues) +- Check [previous + questions](https://stackoverflow.com/questions/tagged/azure+.net) + or ask new ones on Stack Overflow using azure and .net tags. -If the package or a related package supports it, include tips for logging or enabling instrumentation to help them debug their code. ## Next steps -* Provide a link to additional code examples, ideally to those sitting alongside the README in the package's `/samples` directory. -* If appropriate, point users to other packages that might be useful. -* If you think there's a good chance that developers might stumble across your package in error (because they're searching for specific functionality and mistakenly think the package provides that functionality), point them to the packages they might be looking for. +For more information on Azure SDK, please refer to [this website](https://azure.github.io/azure-sdk/) ## Contributing -This is a template, but your SDK readme should include details on how to contribute code to the repo/package. +For details on contributing to this repository, see the contributing +guide. + +This project welcomes contributions and suggestions. Most contributions +require you to agree to a Contributor License Agreement (CLA) declaring +that you have the right to, and actually do, grant us the rights to use +your contribution. For details, visit . + +When you submit a pull request, a CLA-bot will automatically determine +whether you need to provide a CLA and decorate the PR appropriately +(e.g., label, comment). Simply follow the instructions provided by the +bot. You will only need to do this once across all repositories using +our CLA. + +This project has adopted the Microsoft Open Source Code of Conduct. For +more information see the Code of Conduct FAQ or contact + with any additional questions or comments. [style-guide-msft]: https://docs.microsoft.com/style-guide/capitalization [style-guide-cloud]: https://worldready.cloudapp.net/Styleguide/Read?id=2696&topicid=25357 -![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-net%2Fsdk%2Fnetwork%2FAzure.ResourceManager.Network%2FREADME.png) +![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-net%2Fsdk%2Ftemplate%2FAzure.Template%2FREADME.png) diff --git a/sdk/resources/Azure.ResourceManager.Resources/README.md b/sdk/resources/Azure.ResourceManager.Resources/README.md index 3c76339b7b52..98bbf3e24d39 100644 --- a/sdk/resources/Azure.ResourceManager.Resources/README.md +++ b/sdk/resources/Azure.ResourceManager.Resources/README.md @@ -1,66 +1,74 @@ -# README.md template +# Azure Resources Management client library for .NET -Use the guidelines in each section of this template to ensure consistency and readability of your README. The README resides in your package's GitHub repository at the root of its directory within the repo. It's also used as the package distribution page (NuGet, PyPi, npm, etc.) and as a Quickstart on docs.microsoft.com. See [README-EXAMPLE.md](README-EXAMPLE.md) for an example following this template. +This package follows the [new Azure SDK guidelines](https://azure.github.io/azure-sdk/general_introduction.html) which provide a number of core capabilities that are shared amongst all Azure SDKs, including the intuitive Azure Identity library, an HTTP Pipeline with custom policies, error-handling, distributed tracing, and much more. -* All headings, including the H1, should use **sentence-style capitalization**. Refer to the [Microsoft Style Guide][style-guide-msft] and [Microsoft Cloud Style Guide][style-guide-cloud] for more information. -* Example: `# Azure Batch client library for Python` - -# Azure Management Resource client library for .NET - -**Introduction**: The introduction appears directly under the title (H1) of your README. - -* **DO NOT** use an "Introduction" or "Overview" heading (H2) for this section. -* First sentence: **Describe the service** briefly. You can usually use the first line of the service's docs landing page for this (Example: [Cosmos DB docs landing page](https://docs.microsoft.com/azure/cosmos-db/)). -* Next, add a **bulleted list** of the **most common tasks** supported by the package or library, prefaced with "Use the client library for [Product Name] to:". Then, provide code snippets for these tasks in the [Examples](#examples) section later in the document. Keep the task list short but include those tasks most developers need to perform with your package. -* Include this single line of links targeting your product's content at the bottom of the introduction, making any adjustments as necessary (for example, NuGet instead of PyPi): - - [Source code](https://github.com/Azure/azure-sdk-for-python/tree/master/azure-batch) | [Package (PyPi)](https://pypi.org/project/azure-batch/) | [API reference documentation](https://docs.microsoft.com/python/api/overview/azure/batch?view=azure-python) | [Product documentation](https://docs.microsoft.com/azure/batch/) - -> TIP: Your README should be as **brief** as possible but **no more brief** than necessary to get a developer new to Azure, the service, or the package up and running quickly. Keep it brief, but include everything a developer needs to make their first API call successfully. - -## Getting started - -This section should include everything a developer needs to do to install and create their first client connection *very quickly*. +## Getting started ### Install the package -First, provide instruction for obtaining and installing the package or library. This section might include only a single line of code, like `pip install package-name`, but should enable a developer to successfully install the package from NuGet, pip, npm, Maven, or even cloning a GitHub repository. +Install the Azure Resources management library for .NET with [NuGet](https://www.nuget.org/): + +```PowerShell +Install-Package Azure.ResourceManager.Resources -Version 1.0.0-preview.1 +``` ### Prerequisites * You must have an [Azure subscription](https://azure.microsoft.com/free/) -### Authenticate the client +### Authenticate the Client -If your library requires authentication for use, such as for Azure services, include instructions and example code needed for initializing and authenticating. - -For example, include details on obtaining an account key and endpoint URI, setting environment variables for each, and initializing the client object. +To create an authenticated client and start interacting with Azure resources, please see the [quickstart guide here](https://github.com/Azure/azure-sdk-for-net/blob/master/doc/mgmt_preview_quickstart.md) ## Key concepts -The *Key concepts* section should describe the functionality of the main classes. Point out the most important and useful classes in the package (with links to their reference pages) and explain how those classes work together. Feel free to use bulleted lists, tables, code blocks, or even diagrams for clarity. +Key concepts of the Azure .NET SDK can be found [here](https://azure.github.io/azure-sdk/dotnet_introduction.html) + +## Documentation + +Documentation is available to help you learn how to use this package + +- [Quickstart](https://github.com/Azure/azure-sdk-for-net/blob/master/doc/mgmt_preview_quickstart.md) +- [API References](https://docs.microsoft.com/dotnet/api/?view=azure-dotnet) +- [Authentication](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/identity/Azure.Identity/README.md) ## Examples -Include code snippets and short descriptions for each task you listed in the [Introduction](#introduction) (the bulleted list). Briefly explain each operation, but include enough clarity to explain complex or otherwise tricky operations. +Code samples for using the management library for .NET can be found in the following locations +- [.NET Management Library Code Samples](https://docs.microsoft.com/samples/browse/?branch=master&languages=csharp&term=managing%20using%20Azure%20.NET%20SDK) ## Troubleshooting -Describe common errors and exceptions, how to "unpack" them if necessary, and include guidance for graceful handling and recovery. +- File an issue via [Github + Issues](https://github.com/Azure/azure-sdk-for-net/issues) +- Check [previous + questions](https://stackoverflow.com/questions/tagged/azure+.net) + or ask new ones on Stack Overflow using azure and .net tags. -Provide information to help developers avoid throttling or other service-enforced errors they might encounter. For example, provide guidance and examples for using retry or connection policies in the API. - -If the package or a related package supports it, include tips for logging or enabling instrumentation to help them debug their code. ## Next steps -* Provide a link to additional code examples, ideally to those sitting alongside the README in the package's `/samples` directory. -* If appropriate, point users to other packages that might be useful. -* If you think there's a good chance that developers might stumble across your package in error (because they're searching for specific functionality and mistakenly think the package provides that functionality), point them to the packages they might be looking for. +For more information on Azure SDK, please refer to [this website](https://azure.github.io/azure-sdk/) ## Contributing -This is a template, but your SDK readme should include details on how to contribute code to the repo/package. +For details on contributing to this repository, see the contributing +guide. + +This project welcomes contributions and suggestions. Most contributions +require you to agree to a Contributor License Agreement (CLA) declaring +that you have the right to, and actually do, grant us the rights to use +your contribution. For details, visit . + +When you submit a pull request, a CLA-bot will automatically determine +whether you need to provide a CLA and decorate the PR appropriately +(e.g., label, comment). Simply follow the instructions provided by the +bot. You will only need to do this once across all repositories using +our CLA. + +This project has adopted the Microsoft Open Source Code of Conduct. For +more information see the Code of Conduct FAQ or contact + with any additional questions or comments. [style-guide-msft]: https://docs.microsoft.com/style-guide/capitalization diff --git a/sdk/storage/Azure.ResourceManager.Storage/README.md b/sdk/storage/Azure.ResourceManager.Storage/README.md index debbc22408f2..934807f1c909 100644 --- a/sdk/storage/Azure.ResourceManager.Storage/README.md +++ b/sdk/storage/Azure.ResourceManager.Storage/README.md @@ -1,67 +1,74 @@ -# README.md template +# Azure Compute Management client library for .NET -Use the guidelines in each section of this template to ensure consistency and readability of your README. The README resides in your package's GitHub repository at the root of its directory within the repo. It's also used as the package distribution page (NuGet, PyPi, npm, etc.) and as a Quickstart on docs.microsoft.com. See [README-EXAMPLE.md](README-EXAMPLE.md) for an example following this template. +This package follows the [new Azure SDK guidelines](https://azure.github.io/azure-sdk/general_introduction.html) which provide a number of core capabilities that are shared amongst all Azure SDKs, including the intuitive Azure Identity library, an HTTP Pipeline with custom policies, error-handling, distributed tracing, and much more. -* All headings, including the H1, should use **sentence-style capitalization**. Refer to the [Microsoft Style Guide][style-guide-msft] and [Microsoft Cloud Style Guide][style-guide-cloud] for more information. -* Example: `# Azure Batch client library for Python` - -# Azure Management Storage client library for .NET - -**Introduction**: The introduction appears directly under the title (H1) of your README. - -* **DO NOT** use an "Introduction" or "Overview" heading (H2) for this section. -* First sentence: **Describe the service** briefly. You can usually use the first line of the service's docs landing page for this (Example: [Cosmos DB docs landing page](https://docs.microsoft.com/azure/cosmos-db/)). -* Next, add a **bulleted list** of the **most common tasks** supported by the package or library, prefaced with "Use the client library for [Product Name] to:". Then, provide code snippets for these tasks in the [Examples](#examples) section later in the document. Keep the task list short but include those tasks most developers need to perform with your package. -* Include this single line of links targeting your product's content at the bottom of the introduction, making any adjustments as necessary (for example, NuGet instead of PyPi): - - [Source code](https://github.com/Azure/azure-sdk-for-python/tree/master/azure-batch) | [Package (PyPi)](https://pypi.org/project/azure-batch/) | [API reference documentation](https://docs.microsoft.com/python/api/overview/azure/batch?view=azure-python) | [Product documentation](https://docs.microsoft.com/azure/batch/) - -> TIP: Your README should be as **brief** as possible but **no more brief** than necessary to get a developer new to Azure, the service, or the package up and running quickly. Keep it brief, but include everything a developer needs to make their first API call successfully. - -## Getting started - -This section should include everything a developer needs to do to install and create their first client connection *very quickly*. +## Getting started ### Install the package -First, provide instruction for obtaining and installing the package or library. This section might include only a single line of code, like `pip install package-name`, but should enable a developer to successfully install the package from NuGet, pip, npm, Maven, or even cloning a GitHub repository. +Install the Azure Storage management library for .NET with [NuGet](https://www.nuget.org/): + +```PowerShell +Install-Package Azure.ResourceManager.Storage -Version 1.0.0-preview.1 +``` ### Prerequisites * You must have an [Azure subscription](https://azure.microsoft.com/free/) -### Authenticate the client - -If your library requires authentication for use, such as for Azure services, include instructions and example code needed for initializing and authenticating. +### Authenticate the Client -For example, include details on obtaining an account key and endpoint URI, setting environment variables for each, and initializing the client object. +To create an authenticated client and start interacting with Azure resources, please see the [quickstart guide here](https://github.com/Azure/azure-sdk-for-net/blob/master/doc/mgmt_preview_quickstart.md) ## Key concepts -The *Key concepts* section should describe the functionality of the main classes. Point out the most important and useful classes in the package (with links to their reference pages) and explain how those classes work together. Feel free to use bulleted lists, tables, code blocks, or even diagrams for clarity. +Key concepts of the Azure .NET SDK can be found [here](https://azure.github.io/azure-sdk/dotnet_introduction.html) -## Examples +## Documentation -Include code snippets and short descriptions for each task you listed in the [Introduction](#introduction) (the bulleted list). Briefly explain each operation, but include enough clarity to explain complex or otherwise tricky operations. +Documentation is available to help you learn how to use this package +- [Quickstart](https://github.com/Azure/azure-sdk-for-net/blob/master/doc/mgmt_preview_quickstart.md) +- [API References](https://docs.microsoft.com/dotnet/api/?view=azure-dotnet) +- [Authentication](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/identity/Azure.Identity/README.md) -## Troubleshooting +## Examples + +Code samples for using the management library for .NET can be found in the following locations +- [.NET Management Library Code Samples](https://docs.microsoft.com/samples/browse/?branch=master&languages=csharp&term=managing%20using%20Azure%20.NET%20SDK) -Describe common errors and exceptions, how to "unpack" them if necessary, and include guidance for graceful handling and recovery. +## Troubleshooting -Provide information to help developers avoid throttling or other service-enforced errors they might encounter. For example, provide guidance and examples for using retry or connection policies in the API. +- File an issue via [Github + Issues](https://github.com/Azure/azure-sdk-for-net/issues) +- Check [previous + questions](https://stackoverflow.com/questions/tagged/azure+.net) + or ask new ones on Stack Overflow using azure and .net tags. -If the package or a related package supports it, include tips for logging or enabling instrumentation to help them debug their code. ## Next steps -* Provide a link to additional code examples, ideally to those sitting alongside the README in the package's `/samples` directory. -* If appropriate, point users to other packages that might be useful. -* If you think there's a good chance that developers might stumble across your package in error (because they're searching for specific functionality and mistakenly think the package provides that functionality), point them to the packages they might be looking for. +For more information on Azure SDK, please refer to [this website](https://azure.github.io/azure-sdk/) ## Contributing -This is a template, but your SDK readme should include details on how to contribute code to the repo/package. +For details on contributing to this repository, see the contributing +guide. + +This project welcomes contributions and suggestions. Most contributions +require you to agree to a Contributor License Agreement (CLA) declaring +that you have the right to, and actually do, grant us the rights to use +your contribution. For details, visit . + +When you submit a pull request, a CLA-bot will automatically determine +whether you need to provide a CLA and decorate the PR appropriately +(e.g., label, comment). Simply follow the instructions provided by the +bot. You will only need to do this once across all repositories using +our CLA. + +This project has adopted the Microsoft Open Source Code of Conduct. For +more information see the Code of Conduct FAQ or contact + with any additional questions or comments. [style-guide-msft]: https://docs.microsoft.com/style-guide/capitalization