Unify Key Vault Administration APIs (#20968)

* Rename operation classes and .models namespace
* Change order of role definition methods
* Use commit 1e2c9f3e for Administration package
* Create CreateOrUpdateRoleDefinitionOptions
* Rename KeyVaultRoleAssignmentPropertiesWithScope
* Enable backup and restore sample
* Updated custom role definition tests
* Rename to KeyVaultSelectiveKeyRestoreOperation and Result

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

@@ -9,6 +9,18 @@
 
 - Updated dependency versions
 
+### Breaking Changes
+
+- Changed parameter order in `KeyVaultAccessControlClient.DeleteRoleDefinition` and `KeyVaultAccessControlClient.DeleteRoleDefinitionAsync`.
+- Changed parameter order in `KeyVaultAccessControlClient.GetRoleDefinition` and `KeyVaultAccessControlClient.GetRoleDefinitionAsync`.
+- Changed parameters for `KeyVaultAccessControlClient.CreateOrUpdateRoleDefinition` and `KeyVaultAccessControlClient.CreateOrUpdateRoleDefinitionAsync` to accept new `CreateOrUpdateRoleDefinitionOptions` class.
+- Moved all classes from the `Azure.Security.KeyVault.Administration.Models` namespace to `Azure.Security.KeyVault.Administration`.
+- Renamed `BackupOperation` to `KeyVaultBackupOperation`.
+- Renamed `KeyVaultRoleAssignmentPropertiesWithScope` to `KeyVaultRoleAssignmentProperties`.
+- Renamed `RestoreOperation` to `KeyVaultRestoreOperation`.
+- Renamed `SelectiveKeyRestoreOperation` to `KeyVaultSelectiveRestoreOperation`.
+- Renamed `SelectiveKeyRestoreResult` to `KeyVaultSelectiveRestoreResult`.
+
 ## 4.0.0-beta.4 (2021-02-10)
 
 ### Added

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

@@ -33,10 +33,10 @@ UriBuilder builder = new UriBuilder(blobStorageUrl)
 };
 
 // Start the backup.
-BackupOperation backupOperation = await Client.StartBackupAsync(builder.Uri, sasToken);
+KeyVaultBackupOperation backupOperation = await Client.StartBackupAsync(builder.Uri, sasToken);
 
 // Wait for completion of the BackupOperation.
-Response<BackupResult> backupResult = await backupOperation.WaitForCompletionAsync();
+Response<KeyVaultBackupResult> backupResult = await backupOperation.WaitForCompletionAsync();
 
 // Get the Uri for the location of your backup blob.
 Uri folderUri = backupResult.Value.FolderUri;
@@ -50,10 +50,10 @@ Alternatively, it is possible to [generate a SAS token in Storage Explorer](http
 
 ```C# Snippet:HelloFullRestoreAsync
 // Start the restore using the backupBlobUri returned from a previous BackupOperation.
-RestoreOperation restoreOperation = await Client.StartRestoreAsync(folderUri, sasToken);
+KeyVaultRestoreOperation restoreOperation = await Client.StartRestoreAsync(folderUri, sasToken);
 
 // Wait for completion of the RestoreOperation.
-Response<RestoreResult> restoreResult = await restoreOperation.WaitForCompletionAsync();
+Response<KeyVaultRestoreResult> restoreResult = await restoreOperation.WaitForCompletionAsync();
 ```
 
 <!-- LINKS -->

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

@@ -33,7 +33,7 @@ UriBuilder builder = new UriBuilder(blobStorageUrl)
 };
 
 // Start the backup.
-BackupOperation backupOperation = Client.StartBackup(builder.Uri, sasToken);
+KeyVaultBackupOperation backupOperation = Client.StartBackup(builder.Uri, sasToken);
 
 // Wait for completion of the BackupOperation.
 while (!backupOperation.HasCompleted)
@@ -54,7 +54,7 @@ Alternatively, it is possible to [generate a SAS token in Storage Explorer](http
 
 ```C# Snippet:HelloFullRestoreSync
 // Start the restore using the backupBlobUri returned from a previous BackupOperation.
-RestoreOperation restoreOperation = Client.StartRestore(folderUri, sasToken);
+KeyVaultRestoreOperation restoreOperation = Client.StartRestore(folderUri, sasToken);
 
 // Wait for completion of the RestoreOperation.
 while (!restoreOperation.HasCompleted)

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

@@ -11,8 +11,8 @@ Alternatively, it is possible to [generate a SAS token in Storage Explorer](http
 string keyName = "<key name to restore>";
 
 // Start the restore for a specific key that was previously backed up using the backupBlobUri returned from a previous BackupOperation.
-SelectiveKeyRestoreOperation restoreOperation = await Client.StartSelectiveRestoreAsync(keyName, folderUri, sasToken);
+KeyVaultSelectiveKeyRestoreOperation restoreOperation = await Client.StartSelectiveRestoreAsync(keyName, folderUri, sasToken);
 
 // Wait for completion of the RestoreOperation.
-SelectiveKeyRestoreResult restoreResult = await restoreOperation.WaitForCompletionAsync();
+KeyVaultSelectiveKeyRestoreResult restoreResult = await restoreOperation.WaitForCompletionAsync();
 ```

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

@@ -15,10 +15,10 @@ and check for status or wait for completion.
 KeyVaultBackupClient client = new KeyVaultBackupClient(new Uri(keyVaultUrl), new DefaultAzureCredential());
 
 // Construct a BackupOperation using a KeyVaultBackupClient and the Id from a previously started operation.
-BackupOperation backupOperation = new BackupOperation(client, backupOperationId);
+KeyVaultBackupOperation backupOperation = new KeyVaultBackupOperation(client, backupOperationId);
 
 // Wait for completion of the BackupOperation.
-Response<BackupResult> backupResult = await backupOperation.WaitForCompletionAsync();
+Response<KeyVaultBackupResult> backupResult = await backupOperation.WaitForCompletionAsync();
 
 // Get the Uri for the location of you backup blob.
 Uri folderUri = backupResult.Value.FolderUri;
@@ -36,10 +36,10 @@ and check for status or wait for completion.
 KeyVaultBackupClient Client = new KeyVaultBackupClient(new Uri(keyVaultUrl), new DefaultAzureCredential());
 
 // Construct a RestoreOperation using a KeyVaultBackupClient and the Id from a previously started operation.
-RestoreOperation restoreOperation = new RestoreOperation(client, restoreOperationId);
+KeyVaultRestoreOperation restoreOperation = new KeyVaultRestoreOperation(client, restoreOperationId);
 
 // Wait for completion of the RestoreOperation.
-RestoreResult restoreResult = await restoreOperation.WaitForCompletionAsync();
+KeyVaultRestoreResult restoreResult = await restoreOperation.WaitForCompletionAsync();
 ```
 
 <!-- LINKS -->

sdk/keyvault/Azure.Security.KeyVault.Administration/src/CreateOrUpdateRoleDefinitionOptions.cs

@@ -0,0 +1,95 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+using System;
+using System.Collections.Generic;
+using Azure.Security.KeyVault.Administration.Models;
+
+namespace Azure.Security.KeyVault.Administration
+{
+    /// <summary>
+    /// Options to create or update a role definition passed to <see cref="KeyVaultAccessControlClient.CreateOrUpdateRoleDefinition(CreateOrUpdateRoleDefinitionOptions, System.Threading.CancellationToken)"/>
+    /// or <see cref="KeyVaultAccessControlClient.CreateOrUpdateRoleDefinitionAsync(CreateOrUpdateRoleDefinitionOptions, System.Threading.CancellationToken)"/>.
+    /// </summary>
+    public class CreateOrUpdateRoleDefinitionOptions
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="CreateOrUpdateRoleDefinitionOptions"/> class using a generated role definition name.
+        /// </summary>
+        /// <param name="roleScope">The <see cref="KeyVaultRoleScope"/> to which the definition applies.</param>
+        public CreateOrUpdateRoleDefinitionOptions(KeyVaultRoleScope roleScope)
+            : this(roleScope, Guid.NewGuid())
+        {
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="CreateOrUpdateRoleDefinitionOptions"/> class using a generated role definition name.
+        /// </summary>
+        /// <param name="roleScope">The <see cref="KeyVaultRoleScope"/> to which the definition applies.</param>
+        /// <param name="roleDefinitionName">The unique role definition name. If the named role definition is already defined it will be updated.</param>
+        public CreateOrUpdateRoleDefinitionOptions(KeyVaultRoleScope roleScope, Guid roleDefinitionName)
+        {
+            RoleScope = roleScope;
+            RoleDefinitionName = roleDefinitionName;
+
+            Permissions = new List<KeyVaultPermission>();
+            AssignableScopes = new List<KeyVaultRoleScope>();
+        }
+
+        /// <summary>
+        /// Gets the <see cref="KeyVaultRoleScope"/> to which this definition applies.
+        /// </summary>
+        public KeyVaultRoleScope RoleScope { get; }
+
+        /// <summary>
+        /// Gets the unique role definition name.
+        /// </summary>
+        public Guid RoleDefinitionName { get; }
+
+        /// <summary>
+        /// Gets the display name of this role definition. Defaults to the <see cref="RoleDefinitionName"/>.
+        /// </summary>
+        public string RoleName { get; set; }
+
+        /// <summary>
+        /// Gets a description of this role definition.
+        /// </summary>
+        public string Description { get; set; }
+
+        /// <summary>
+        /// Gets a list of permissions granted by this role definition when assigned to a principal.
+        /// </summary>
+        public IList<KeyVaultPermission> Permissions { get; }
+
+        /// <summary>
+        /// Gets a list of scopes for which this role definition can be assigned.
+        /// </summary>
+        public IList<KeyVaultRoleScope> AssignableScopes { get; }
+
+        /// <summary>
+        /// Converts this instance of <see cref="CreateOrUpdateRoleDefinitionOptions"/> to a <see cref="RoleDefinitionProperties"/> object.
+        /// </summary>
+        /// <returns></returns>
+        internal RoleDefinitionCreateParameters ToParameters(KeyVaultRoleType roleType)
+        {
+            RoleDefinitionProperties properties = new()
+            {
+                RoleType = roleType,
+                RoleName = RoleName,
+                Description = Description,
+            };
+
+            foreach (KeyVaultPermission permission in Permissions)
+            {
+                properties.Permissions.Add(permission);
+            }
+
+            foreach (KeyVaultRoleScope scope in AssignableScopes)
+            {
+                properties.AssignableScopes.Add(scope);
+            }
+
+            return new(properties);
+        }
+    }
+}