Create backup and restore samples, various other updates

sdk/core/Azure.Core.TestFramework/src/RecordedTestAttribute.cs

@@ -61,7 +61,7 @@ public override TestResult Execute(TestExecutionContext context)
                         context.CurrentResult.SetResult(context.CurrentResult.ResultState,
                             "Error while trying to re-record: " + Environment.NewLine +
                             context.CurrentResult.Message + Environment.NewLine +
-                            "Original error: " + originalResult.Message, context.CurrentResult.Message);
+                            "Original error: " + originalResult.Message, context.CurrentResult.StackTrace);
                     }
 
                     // revert RecordTestMode to Playback

sdk/keyvault/Azure.Security.KeyVault.Administration/CHANGELOG.md

@@ -5,3 +5,4 @@
 ### Added
 
 - Add `KeyVaultAccessControlClient`.
+- Add `KeyVaultBackupClient`.

sdk/keyvault/Azure.Security.KeyVault.Administration/readme.md

@@ -4,13 +4,15 @@ Azure Key Vault is a cloud service for securely storing and accessing secrets. A
 
 The Azure Key Vault administration library clients support administrative tasks such as full backup / restore and key-level role-based access control (RBAC).
 
+[Source code][admin_client_src] | [Package (NuGet)][admin_client_nuget_package] | [API reference documentation][API_reference] | [Product documentation][keyvault_docs] | [Samples][admin_client_samples]
+
 ## Getting started
 
 ### Install the package
 Install the Azure Key Vault administration client library for .NET with [NuGet][nuget]:
 
 ```PowerShell
-Install-Package Azure.Security.KeyVault.Administration --version 4.2.0-preview.1
+dotnet install Azure.Security.KeyVault.Administration --version 4.0.0-beta.1
 ```
 
 ### Prerequisites
@@ -27,7 +29,7 @@ Client secret credential authentication is being used in this getting started se
 or other credential providers provided with the Azure SDK, you should install the Azure.Identity package:
 
 ```PowerShell
-Install-Package Azure.Identity
+dotnet install Azure.Identity
 ```
 
 #### Create/Get credentials
@@ -81,74 +83,43 @@ Once you've populated the **AZURE_CLIENT_ID**, **AZURE_CLIENT_SECRET** and **AZU
 KeyVaultAccessControlClient client = new KeyVaultAccessControlClient(vaultUri: new Uri(keyVaultUrl), credential: new DefaultAzureCredential());
 
 // Retrieve all the role definitions.
-List<RoleDefinition> roleDefinitions = client.GetRoleDefinitions(RoleAssignmentScope.Global).ToList();
+List<KeyVaultRoleDefinition> roleDefinitions = client.GetRoleDefinitions(KeyVaultRoleScope.Global).ToList();
 
 // Retrieve all the role assignments.
-List<RoleAssignment> roleAssignments = client.GetRoleAssignments(RoleAssignmentScope.Global).ToList();
+List<KeyVaultRoleAssignment> roleAssignments = client.GetRoleAssignments(KeyVaultRoleScope.Global).ToList();
 ```
 
 ## Key concepts
 
-### RoleDefinition
-A `RoleDefinition` is a collection of permissions. A role definition defines the operations that can be performed, such as read, write, and delete. It can also define the operations that are excluded from allowed operations.
+### KeyVaultRoleDefinition
+A `KeyVaultRoleDefinition` is a collection of permissions. A role definition defines the operations that can be performed, such as read, write, and delete. It can also define the operations that are excluded from allowed operations.
 
-RoleDefinitions can be listed and specified as part of a `RoleAssignment`.
+RoleDefinitions can be listed and specified as part of a `KeyVaultRoleAssignment`.
 
 ### RoleAssignment. 
-A `RoleAssignment` is the association of a RoleDefinition to a service principal. They can be created, listed, fetched individually, and deleted.
+A `KeyVaultRoleAssignment` is the association of a KeyVaultRoleDefinition to a service principal. They can be created, listed, fetched individually, and deleted.
 
 ### KeyVaultAccessControlClient
-A `KeyVaultAccessControlClient` provides both synchronous and asynchronous operations allowing for management of `RoleDefinition` and `RoleAssignment` objects.
+A `KeyVaultAccessControlClient` provides both synchronous and asynchronous operations allowing for management of `KeyVaultRoleDefinition` and `KeyVaultRoleAssignment` objects.
 
 ## Examples
 The Azure.Security.KeyVault.Administration package supports synchronous and asynchronous APIs.
 
 The following section provides several code snippets using the `client` [created above](#create-keyvaultaccesscontrolclient), covering some of the most common Azure Key Vault access control related tasks:
 
-### List the role definitions
-List the role definitions available for assignment.
-
-```C# Snippet:GetRoleDefinitions
-Pageable<RoleDefinition> allDefinitions = client.GetRoleDefinitions(RoleAssignmentScope.Global);
-
-foreach (RoleDefinition roleDefinition in allDefinitions)
-{
-    Console.WriteLine(roleDefinition.Id);
-    Console.WriteLine(roleDefinition.RoleName);
-    Console.WriteLine(roleDefinition.Description);
-    Console.WriteLine();
-}
-```
-
-### Create, Get, and Delete a role assignment
-Assign a role to a service principal. This will require a role definition id from the list retrieved in the [above snippet](#list-the-role-definitions) and the principal object id retrieved in the [Create/Get credentials](#create/get-credentials)
-
-```C# Snippet:ReadmeCreateRoleAssignment
-// Replace <roleDefinitionId> with a role definition Id from the definitions returned from the List the role definitions section above
-string definitionIdToAssign = "<roleDefinitionId>";
-
-// Replace <objectId> with the service principal object id from the Create/Get credentials section above
-string servicePrincipalObjectId = "<objectId>";
-
-RoleAssignmentProperties properties = new RoleAssignmentProperties(definitionIdToAssign, servicePrincipalObjectId);
-RoleAssignment createdAssignment = client.CreateRoleAssignment(RoleAssignmentScope.Global, properties);
+### Sync examples
+- [Listing All Role Definitions](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample1_RbacHelloWorldSync.md#listing-all-role-definitions-sync)
+- [Listing All Role Assignments](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample1_RbacHelloWorldSync.md#listing-all-role-assignments)
+- [Creating a Role Assignment](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample1_RbacHelloWorldSync.md#creating-a-role-assignment)
+- [Getting a Role Assignment](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample1_RbacHelloWorldSync.md#getting-a-role-assignment)
+- [Deleting a Role Assignment](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample1_RbacHelloWorldSync.md#deleting-a-role-assignment)
 
-Console.WriteLine(createdAssignment.Name);
-Console.WriteLine(createdAssignment.Properties.PrincipalId);
-Console.WriteLine(createdAssignment.Properties.RoleDefinitionId);
-
-RoleAssignment fetchedAssignment = client.GetRoleAssignment(RoleAssignmentScope.Global, createdAssignment.Name);
-
-Console.WriteLine(fetchedAssignment.Name);
-Console.WriteLine(fetchedAssignment.Properties.PrincipalId);
-Console.WriteLine(fetchedAssignment.Properties.RoleDefinitionId);
-
-RoleAssignment deletedAssignment = client.DeleteRoleAssignment(RoleAssignmentScope.Global, createdAssignment.Name);
-
-Console.WriteLine(deletedAssignment.Name);
-Console.WriteLine(deletedAssignment.Properties.PrincipalId);
-Console.WriteLine(deletedAssignment.Properties.RoleDefinitionId);
-```
+### Async examples
+- [Listing All Role Definitions](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample1_RbacHelloWorldAsync.md#listing-all-role-definitions-sync)
+- [Listing All Role Assignments](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample1_RbacHelloWorldAsync.md#listing-all-role-assignments)
+- [Creating a Role Assignment](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample1_RbacHelloWorldAsync.md#creating-a-role-assignment)
+- [Getting a Role Assignment](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample1_RbacHelloWorldAsync.md#getting-a-role-assignment)
+- [Deleting a Role Assignment](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample1_RbacHelloWorldAsync.md#deleting-a-role-assignment)
 
 ## Troubleshooting
 
@@ -159,7 +130,7 @@ For example, if you try to retrieve a role assignment that doesn't exist in your
 ```C# Snippet:RoleAssignmentNotFound
 try
 {
-    RoleAssignment roleAssignment = client.GetRoleAssignment(RoleAssignmentScope.Global, "invalid-name");
+    KeyVaultRoleAssignment roleAssignment = client.GetRoleAssignment(KeyVaultRoleScope.Global, "invalid-name");
 }
 catch (RequestFailedException ex)
 {
@@ -181,9 +152,20 @@ Content-Length: 143
 Content-Type: application/json
 ```
 
+### Setting up console logging
+The simplest way to see the logs is to enable the console logging.
+To create an Azure SDK log listener that outputs messages to console use AzureEventSourceListener.CreateConsoleLogger method.
+
+```
+// Setup a listener to monitor logged events.
+using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();
+```
+
+To learn more about other logging mechanisms see [here](logging).
+
 ## Next steps
 
-Content forthcoming
+Get started with our [samples](admin_client_samples).
 
 ## Contributing
 
@@ -205,9 +187,13 @@ additional questions or comments.
 [rbac_client]: https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/keyvault/Azure.Security.KeyVault.Administration/src/KeyVaultAccessControlClient.cs
 [keyvault_docs]: https://docs.microsoft.com/azure/key-vault/
 [keyvault_rest]: https://docs.microsoft.com/rest/api/keyvault/
+[admin_client_nuget_package]: https://www.nuget.org/packages/Azure.Security.KeyVault.Administration/
+[admin_client_samples]: https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/keyvault/Azure.Security.KeyVault.Administration/samples
+[admin_client_src]: https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/keyvault/Azure.Security.KeyVault.Administration/src
 [JWK]: https://tools.ietf.org/html/rfc7517
 [nuget]: https://www.nuget.org/
 [DefaultAzureCredential]: https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/identity/Azure.Identity/README.md
+[logging]: https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/core/Azure.Core/samples/Diagnostics.md
 [contributing]: https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/keyvault/Microsoft.Azure.KeyVault/CONTRIBUTING.md
 
 

sdk/keyvault/Azure.Security.KeyVault.Administration/samples/README.md

@@ -13,3 +13,5 @@ description: Samples for the Azure.Security.KeyVault.Administration client libra
 
 - Creating, getting, and deleting role assignments [synchronously](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample1_RbacHelloWorldSync.md) or [asynchronously](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample1_RbacHelloWorldAsync.md)
 - [Assigning roles for specific scopes](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample2_RbacScopeAssignment.md) 
+- Performing a full key backup and restore [synchronously](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample1_BackupHelloWorldSync.md) and [asynchronously](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample1_BackupHelloWorldAsync.md)
+- [Performing selective key restore]

sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample1_BackupHelloWorldAsync.md

@@ -0,0 +1,64 @@
+# Performing a full key backup and restore (Async)
+
+This sample demonstrates how to a full key backup and restore in Azure Key Vault.
+To get started, you'll need a URI to an Azure Key Vault. See the [README](../README.md) for links and instructions.
+
+## Creating a KeyVaultBackupClient
+
+To create a new `KeyVaultBackupClient`, you'll need the endpoint to an Azure Key Vault and credentials.
+You can use the [DefaultAzureCredential][DefaultAzureCredential] to try a number of common authentication methods optimized for both running as a service and development.
+
+In the sample below, you can set `keyVaultUrl` based on an environment variable, configuration setting, or any way that works for your application.
+
+```C# Snippet:HelloCreateKeyVaultBackupClient
+KeyVaultBackupClient client = new KeyVaultBackupClient(new Uri(keyVaultUrl), new DefaultAzureCredential());
+```
+
+## Performing a full key backup
+
+Using the `KeyVaultBackupClient`, you can backup your entire collection of keys. The backing store for full key backups is a blob storage container using Shared Access Signature authentication. 
+For more details on creating a SAS token using the `BlobServiceClient`, see the [Azure Storage Blobs client README](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/README.md) and the [authentication samples](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/samples/Sample02_Auth.cs).
+Alternatively, it is possible to [generate a SAS token in Storage Explorer](https://docs.microsoft.com/en-us/azure/vs-azure-tools-storage-manage-with-storage-explorer?tabs=windows#generate-a-shared-access-signature-in-storage-explorer)
+
+To ensure you have some keys for backup, you may want to first create a key using the `KeyClient`.
+To create a new `KeyClient` to create a key, see the [Creating a KeyClient](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/keyvault/Azure.Security.KeyVault.Keys/samples/Sample1_HelloWorld.md#creating-a-keyclientkeyvault) and [Creating a key](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/keyvault/Azure.Security.KeyVault.Keys/samples/Sample1_HelloWorld.md#creating-a-key) samples.
+
+In the sample below, you can set `blobStorageUrl`, `blobContainerName`, and `sasToken` based on a environment variables, configuration settings, or any way that works for your application.
+
+```C# Snippet:HelloFullBackupAsync
+// Create a Uri with the storage container
+UriBuilder builder = new UriBuilder(blobStorageUrl)
+{
+    Path = blobContainerName,
+};
+
+// Start the backup.
+BackupOperation backupOperation = await Client.StartBackupAsync(builder.Uri, sasToken);
+
+// Wait for completion of the BackupOperation.
+var backupResult = await backupOperation.WaitForCompletionAsync();
+
+// Get the Uri for the location of you backup blob.
+Uri backupBlobUri = backupResult.Value;
+```
+
+## Performing a full key restore
+
+Using the `KeyVaultBackupClient`, you can restore your entire collection of keys from backup. The data source for full key restore is a storage blob accessed using Shared Access Signature authentication. 
+For more details on creating a SAS token using the `BlobServiceClient`, see the [Azure Storage Blobs client README](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/README.md) and the [authentication samples](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/samples/Sample02_Auth.cs).
+Alternatively, it is possible to [generate a SAS token in Storage Explorer](https://docs.microsoft.com/en-us/azure/vs-azure-tools-storage-manage-with-storage-explorer?tabs=windows#generate-a-shared-access-signature-in-storage-explorer)
+
+```C# Snippet:HelloFullRestoreAsync
+// Get the folder name from the backupBlobUri returned from a previous BackupOperation
+var uriSegments = backupBlobUri.Segments;
+string folderName = uriSegments[uriSegments.Length - 1];
+
+// Start the restore.
+RestoreOperation restoreOperation = await Client.StartRestoreAsync(builder.Uri, sasToken, folderName);
+
+// Wait for completion of the RestoreOperation.
+var restoreResult = await restoreOperation.WaitForCompletionAsync();
+```
+
+<!-- LINKS -->
+[DefaultAzureCredential]: ../../../identity/Azure.Identity/README.md