5593 azure.resource manager.core readme

sdk/resourcemanager/Azure.ResourceManager.Core/README.md

@@ -14,46 +14,155 @@ Install-Package Azure.ResourceManager.Core -Version 1.0.0-beta.1
 
 ### Prerequisites
 
-* You must have an [Azure subscription](https://azure.microsoft.com/free/)
+You'll need the following values to authenticate to Azure:
 
-### Authenticate the Client
+-   **Subscription ID**
+-   **Client ID**
+-   **Client Secret**
+-   **Tenant ID**
 
-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)
+Detailed instructions on getting and setting these values is found in the [Prerequisites guide](docs/Prerequisites.md). 
+
+### Authentication and Creating Resource Management Client
+
+Once the environment is set up, create an authenticated client. Our default option is to use `DefaultAzureCredential` and create an `AzureResourceManagerClient`. Since all management APIs go through the same endpoint, you no longer need to create a new client for every resource type.
+
+To authenticate to Azure and create an ARM client, do the following:
+
+```csharp
+    using Azure.Identity;
+    using Azure.ResourceManager.Core;
+    using System;
+
+    // code omitted for brevity
+
+    ArmClient armClient = new ArmClient(new DefaultAzureCredential());
+```
+
+From this code snippet, we showed that in order to interact with Resources, we need to create the top-level client first **AzureResourceManagerClient**
+
+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).
 
 ## Key concepts
+### Understanding Azure Resource Hierarchy
+
+To reduce both the number of clients needed to perform common tasks and the amount of redundant parameters that each of those clients take, we have introduced an object hierarchy in the SDK that mimics the object hierarchy in Azure. Each resource client in the SDK has methods to access the resource clients of its children that is already scoped to the proper subscription and resource group.
+
+To accomplish this, we're introducing 4 standard types for all resources in Azure:
+
+#### **[Resource]Data**
+This represents the data that makes up a given resource. Typically, this is the response data from a service call such as GET and provides details about the underlying resource.
+Previously, this was represented by a **Model** class.
+
+#### **[Resource]Operations**
+
+This represents a service client that's scoped to a particular resource. You can directly execute all operations on that client without needing to pass in scope parameters such as subscription ID or resource name.
 
-Key concepts of the Azure .NET SDK can be found [here](https://azure.github.io/azure-sdk/dotnet_introduction.html)
+#### **[Resource]Container**
 
-## Documentation
+This represents the operations you can perform on a collection of resources belonging to a specific parent resource.
+This mainly consists of List or Create operations. For most things, the parent will be a **ResourceGroup**. However, each parent / child relationship is represented this way. For example, a **Subnet** is a child of a **VirtualNetwork** and a **ResourceGroup** is a child of a **Subscription**.
 
-Documentation is available to help you learn how to use this package
+#### **[Resource]**
+
+This represents a full resource object which contains a **Data** property exposing the details as a **[Resource]Data** type.
+It also has access to all of the operations and like the **[Resource]Operations** object is already scoped
+to a specific resource in Azure.
+
+### Migrating from current to preview versions
+There are core differences between the current and new preview SDK. The main ones are:
+
+- The introduction of Resource Operations.
+- A structured Resource Identifier.
+
+You can learn more about the main differences [in this document](docs\MigratingFromCurrentToPreview.md) and reading the examples below.
 
-- [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
+### Add a tag to a virtual machine
+ Imagine that our company requires all virtual machines to be tagged with the owner and we are tasked with writing a program to add the tag to any missing virtual machines in a given resource group.
+
+ ```csharp
+// First we construct our armClient
+ArmClient armClient = new ArmClient(new DefaultAzureCredential());
+
+// Next we get a resource group object
+// ResourceGroup is a [Resource] object from above
+ResourceGroup resourceGroup = await armClient.DefaultSubscription.GetResourceGroups().GetAsync("myRgName");
+
+// Next we get the container for the virtual machines
+// vmContainer is a [Resource]Container object from above
+VirtualMachineContainer vmContainer = resourceGroup.GetVirtualMachines();
+
+// Next we loop over all vms in the container
+// Each vm is a [Resource] object from above
+await foreach(VirtualMachine vm in vmContainer.ListAsync())
+{
+    // We access the [Resource]Data properties from vm.Data
+    if(!vm.Data.Tags.ContainsKey("owner"))
+    {
+        // We can also access all [Resource]Operations from vm since it is already scoped for us
+        await vm.StartAddTag("owner", GetOwner()).WaitForCompletionAsync();
+    }
+}
+ ```
+
+### Create a resource group
+```csharp
+// First we initialize the ArmClient and get the default subscription
+ArmClient armClient = new ArmClient(new DefaultAzureCredential());
+Subscription subscription = armClient.DefaultSubscription;
+// Now we get a ResourceGroup container for that subscription
+ResourceGroupContainer rgContainer = subscription.GetResourceGroups();
+
+// With the container we can create a new resource group with an specifc name and location
+LocationData location = LocationData.WestUS2;
+string rgName = "myRgName";
+ResourceGroup resourceGroup = await rgContainer.Construct(location).CreateAsync(rgName);
+```
 
-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)
+### List all resource groups
+```csharp
+// First we initialize the ArmClient and get the default subscription
+ArmClient armClient = new ArmClient(new DefaultAzureCredential());
+Subscription subscription = armClient.DefaultSubscription;
+
+// Now we get a ResourceGroup container for that subscription
+ResourceGroupContainer rgContainer = subscription.GetResourceGroups();
+
+// With ListAsync() we can get a list of the resources in the container
+AsyncPageable<ResourceGroup> response = rgContainer.ListAsync();
+await foreach (ResourceGroup rg in response)
+{
+    Console.WriteLine(rg.Data.Name);
+}
+```
+
+For more detailed examples, take a look at [samples](samples/) we have available.
 
 ## Troubleshooting
 
--   File an issue via [Github
-    Issues](https://github.com/Azure/azure-sdk-for-net/issues)
--   Check [previous
+-   If you find a bug or have a suggestion, 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.
+-   If you need help, check [previous
     questions](https://stackoverflow.com/questions/tagged/azure+.net)
-    or ask new ones on Stack Overflow using azure and .net tags.
-
+    or ask new ones on StackOverflow using azure and .NET tags.
+-   If having trouble with authenthication, go to [DefaultAzureCredential documentation](https://docs.microsoft.com/en-us/dotnet/api/azure.identity.defaultazurecredential?view=azure-dotnet).
+## Next Steps
+### More sample code
 
-## Next steps
+- [Managing Resource Groups](samples/ManagingResourceGroups.md)
+- [Creating a Virtual Network](samples/CreatingAVirtualNetwork.md)
+- [.NET Management Library Code Samples](https://docs.microsoft.com/samples/browse/?branch=master&languages=csharp&term=managing%20using%20Azure%20.NET%20SDK)
 
-For more information on Azure SDK, please refer to [this website](https://azure.github.io/azure-sdk/)
+### Additional Documentation
+For more information on Azure SDK, please refer to [this website](https://azure.github.io/azure-sdk/).
 
 ## Contributing
 
-For details on contributing to this repository, see the contributing
-guide.
+For details on contributing to this repository, see the [contributing
+guide](docs/CONTRIBUTING.md).
 
 This project welcomes contributions and suggestions. Most contributions
 require you to agree to a Contributor License Agreement (CLA) declaring
@@ -69,9 +178,3 @@ our CLA.
 This project has adopted the Microsoft Open Source Code of Conduct. For
 more information see the Code of Conduct FAQ or contact
 <opencode@microsoft.com> with any additional questions or comments.
-
-<!-- LINKS -->
-[style-guide-msft]: https://docs.microsoft.com/style-guide/capitalization
-[style-guide-cloud]: https://aka.ms/azsdk/cloud-style-guide
-
-![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-net%2Fsdk%2Ftemplate%2FAzure.Template%2FREADME.png)

sdk/resourcemanager/Azure.ResourceManager.Core/docs/CONTRIBUTING.md

@@ -0,0 +1,78 @@
+# Contributing
+
+Thank you for your interest in contributing to the Azure App Configuration client library. As an open source effort, we're excited to welcome feedback and contributions from the community. A great first step in sharing your thoughts and understanding where help is needed would be to take a look at the [open issues][open_issues].
+
+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 [cla.microsoft.com][cla].
+
+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 repos using our CLA.
+
+## Code of conduct
+
+This project has adopted the [Microsoft Open Source Code of Conduct][code_of_conduct]. For more information see the [Code of Conduct FAQ][code_of_conduct_faq] or contact [opencode@microsoft.com][email_opencode] with any additional questions or comments.
+
+## Getting started
+
+Before working on a contribution, it would be beneficial to familiarize yourself with the process and guidelines used for the Azure SDKs so that your submission is consistent with the project standards and is ready to be accepted with fewer changes requested. In particular, it is recommended to review:
+
+ - [Azure SDK README][sdk_readme], to learn more about the overall project and processes used.
+ - [Azure SDK Design Guidelines][sdk_design_guidelines], to understand the general guidelines for the Azure SDK across all languages and platforms.
+ - [Azure SDK Contributing Guide][sdk_contributing], for information about how to onboard and contribute to the overall Azure SDK ecosystem.
+
+## Azure SDK Design Guidelines for .NET
+
+These libraries follow the [Azure SDK Design Guidelines for .NET][sdk_design_guidelines_dotnet] and share a number of core features such as HTTP retries, logging, transport protocols, authentication protocols, etc., so that once you learn how to use these features in one client library, you will know how to use them in other client libraries. You can learn about these shared features in the [Azure.Core README][sdk_dotnet_code_readme].
+
+## Public API changes  
+
+To update [`Azure.Data.AppConfiguration.netstandard2.0.cs`][azconfig_api] after making changes to the public API, execute [`./eng/scripts/Export-API.ps1`][azconfig_export_api]. 
+
+## Testing
+
+### Frameworks
+
+We use [NUnit 3][nunit] as our testing framework.
+
+[Azure.Core.TestFramework's testing framework][core_tests] provides a set of reusable primitives that simplify writing tests for new Azure SDK libraries.
+
+### Sync/Async testing
+
+We expose all of our APIs with both sync and async variants. To avoid writing each of our tests twice, we automatically rewrite our async API calls into their sync equivalents. Simply write your tests using only async APIs and call `InstrumentClient` on any of our client objects. The test framework will wrap the client with a proxy that forwards everything to the sync overloads. Please note that a number of our helpers will automatically instrument clients they provide you. Visual Studio's test runner will show `*TestClass(True)` for the async variants and `*TestClass(False)` for the sync variants.
+
+### Recorded tests
+
+Our testing framework supports recording service requests made during a unit test so they can be replayed later. You can set the `AZURE_TEST_MODE` environment variable to `Playback` to run previously recorded tests, `Record` to record or re-record tests, and `Live` to run tests against the live service.
+
+Properly supporting recorded tests does require a few extra considerations. All random values should be obtained via `this.Recording.Random` since we use the same seed on test playback to ensure our client code generates the same "random" values each time. You can't share any state between tests or rely on ordering because you don't know the order they'll be recorded or replayed. Any sensitive values are redacted via the [`ConfigurationRecordedTestSanitizer`][tests_sanitized].
+
+### Running tests
+
+The easiest way to run the tests is via Visual Studio's unit test runner.
+
+You can also run tests via the command line using `dotnet test`, but that will run tests for all supported platforms simultaneously and intermingle their output. You can run the tests for just one platform with `dotnet test -f netcoreapp2.1` or `dotnet test -f net461`.
+
+The recorded tests are run automatically on every pull request. Live tests are run nightly. Contributors with write access can ask Azure DevOps to run the live tests against a pull request by commenting `/azp run net - appconfiguration - tests` in the PR.
+
+### Samples
+
+Our samples are structured as unit tests so we can easily verify they're up to date and working correctly. These tests aren't recorded and make minimal use of test infrastructure to keep them easy to read.
+
+## Development history
+
+For additional insight and context, the development, release, and issue history for the Azure Event Hubs client library is available in read-only form, in its previous location, the [Azure App Configuration .NET repository](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/appconfiguration).
+
+<!-- LINKS -->
+[azconfig_root]: ../../sdk/appconfiguration
+[azconfig_api]: https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/appconfiguration/Azure.Data.AppConfiguration/api/Azure.Data.AppConfiguration.netstandard2.0.cs
+[azconfig_export_api]: https://github.com/Azure/azure-sdk-for-net/blob/master/eng/scripts/Export-API.ps1
+[cla]: https://cla.microsoft.com
+[code_of_conduct]: https://opensource.microsoft.com/codeofconduct/
+[code_of_conduct_faq]: https://opensource.microsoft.com/codeofconduct/faq/
+[core_tests]: https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/core/Azure.Core.TestFramework
+[nunit]: https://github.com/nunit/docs/wiki
+[open_issues]: https://github.com/Azure/azure-sdk-for-net/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3AClient+label%3AAzConfig
+[sdk_readme]: https://github.com/Azure/azure-sdk
+[sdk_contributing]: https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/appconfiguration/CONTRIBUTING.md
+[sdk_design_guidelines]: https://azure.github.io/azure-sdk/general_introduction.html
+[sdk_design_guidelines_dotnet]: https://azure.github.io/azure-sdk/dotnet_introduction.html
+[sdk_dotnet_code_readme]: https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/core/Azure.Core/README.md
+[email_opencode]: mailto:opencode@microsoft.com