Fix doc issues for Key Vault Administration SDK (#33327)

* Add samples for role definition CRUD

Fixes #25791

* Fix Key Vault Admin docs

Fixes #25825

* Update Key Vault Admin README

Fixes #25790

* Update Key Vault Admin sample README

Fixes #25826

* Update Key Vault backup sample

Fixes #25828

* Update RBAC scope assignments sample

Fixes #25829

* Update backup/restore sample

Fixes #25830

Author: heaths

sdk/core/Azure.Core/src/ClientOptions.cs

@@ -100,7 +100,7 @@ public HttpPipelineTransport Transport
         public HttpPipelinePolicy? RetryPolicy { get; set; }
 
         /// <summary>
-        /// Adds an <see cref="HttpPipeline"/> policy into the client pipeline. The position of policy in the pipeline is controlled by <paramref name="position"/> parameter.
+        /// Adds an <see cref="HttpPipeline"/> policy into the client pipeline. The position of policy in the pipeline is controlled by the <paramref name="position"/> parameter.
         /// If you want the policy to execute once per client request use <see cref="HttpPipelinePosition.PerCall"/> otherwise use <see cref="HttpPipelinePosition.PerRetry"/>
         /// to run the policy for every retry. Note that the same instance of <paramref name="policy"/> would be added to all pipelines of client constructed using this <see cref="ClientOptions"/> object.
         /// </summary>

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

@@ -58,14 +58,14 @@ Only the designated administrators that were assigned during the create command
 
 To activate your HSM you need:
 
-* Minimum 3 RSA key-pairs (maximum 10)
-* Specify minimum number of keys required to decrypt the security domain (quorum)
+* A minimum of 3 RSA key-pairs (maximum 10)
+* Specify the minimum number of keys required to decrypt the security domain (quorum)
 
 To activate the HSM you send at least 3 (maximum 10) RSA public keys to the HSM. The HSM encrypts the security domain with these keys and sends it back.
 Once this security domain is successfully downloaded, your HSM is ready to use.
 You also need to specify quorum, which is the minimum number of private keys required to decrypt the security domain.
 
-The example below shows how to use openssl to generate 3 self signed certificate.
+The example below shows how to use openssl to generate 3 self signed certificates.
 
 ```PowerShell
 openssl req -newkey rsa:2048 -nodes -keyout cert_0.key -x509 -days 365 -out cert_0.cer
@@ -74,7 +74,7 @@ openssl req -newkey rsa:2048 -nodes -keyout cert_2.key -x509 -days 365 -out cert
 ```
 
 Use the `az keyvault security-domain download` command to download the security domain and activate your managed HSM.
-The example below, uses 3 RSA key pairs (only public keys are needed for this command) and sets the quorum to 2.
+The example below uses 3 RSA key pairs (only public keys are needed for this command) and sets the quorum to 2.
 
 ```PowerShell
 az keyvault security-domain download --hsm-name <your-managed-hsm-name> --sd-wrapping-keys ./certs/cert_0.cer ./certs/cert_1.cer ./certs/cert_2.cer --sd-quorum 2 --security-domain-file ContosoMHSM-SD.json
@@ -95,7 +95,7 @@ Please read [best practices][best_practices] for properly securing your managed
 
 #### Create KeyVaultAccessControlClient
 
-Instantiate a `DefaultAzureCredential` to pass to the [KeyVaultAccessControlClient][rbac_client].
+Instantiate a `DefaultAzureCredential` to pass to the `KeyVaultAccessControlClient`.
 The same instance of a token credential can be used with multiple clients if they will be authenticating with the same identity.
 
 ```C# Snippet:HelloCreateKeyVaultAccessControlClient
@@ -104,7 +104,7 @@ KeyVaultAccessControlClient client = new KeyVaultAccessControlClient(new Uri(man
 
 #### Create KeyVaultBackupClient
 
-Instantiate a `DefaultAzureCredential` to pass to the [KeyVaultBackupClient][backup_client].
+Instantiate a `DefaultAzureCredential` to pass to the `KeyVaultBackupClient`.
 The same instance of a token credential can be used with multiple clients if they will be authenticating with the same identity.
 
 ```C# Snippet:HelloCreateKeyVaultBackupClient
@@ -113,7 +113,7 @@ KeyVaultBackupClient client = new KeyVaultBackupClient(new Uri(managedHsmUrl), n
 
 #### Create KeyVaultSettingClient
 
-Instantiate a `DefaultAzureCredential` to pass to the [KeyVaultSettingsClient][settings_client].
+Instantiate a `DefaultAzureCredential` to pass to the `KeyVaultSettingsClient`.
 The same instance of a token credential can be used with multiple clients if they will be authenticating with the same identity.
 
 ```C# Snippet:KeyVaultSettingsClient_Create
@@ -201,7 +201,7 @@ for details on how to diagnose various failure scenarios.
 
 ### General
 
-When you interact with the Azure Key Vault administration library using the .NET SDK, errors returned by the service correspond to the same HTTP status codes returned for [REST API][keyvault_rest] requests.
+When you interact with the Azure Key Vault Administration library using the .NET SDK, errors returned by the service correspond to the same HTTP status codes returned for [REST API][keyvault_rest] requests.
 
 For example, if you try to retrieve a role assignment that doesn't exist in your Azure Key Vault, a `404` error is returned, indicating "Not Found".
 
@@ -233,7 +233,7 @@ 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.
+To create an Azure SDK log listener that outputs messages to console, use the `AzureEventSourceListener.CreateConsoleLogger` method.
 
 ```c#
 // Setup a listener to monitor logged events.
@@ -268,9 +268,6 @@ additional questions or comments.
 [best_practices]: https://learn.microsoft.com/azure/key-vault/managed-hsm/best-practices
 [built_in_roles]: https://learn.microsoft.com/azure/key-vault/managed-hsm/built-in-roles
 [code_of_conduct]: https://opensource.microsoft.com/codeofconduct/
-[rbac_client]: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/keyvault/Azure.Security.KeyVault.Administration/src/KeyVaultAccessControlClient.cs
-[backup_client]: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/keyvault/Azure.Security.KeyVault.Administration/src/KeyVaultBackupClient.cs
-[settings_client]: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/keyvault/Azure.Security.KeyVault.Administration/src/KeyVaultSettingsClient.cs
 [managedhsm_docs]: https://learn.microsoft.com/azure/key-vault/managed-hsm/
 [keyvault_rest]: https://learn.microsoft.com/rest/api/keyvault/
 [admin_client_nuget_package]: https://www.nuget.org/packages?q=Azure.Security.KeyVault.Administration

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

@@ -11,8 +11,8 @@ description: Samples for the Azure.Security.KeyVault.Administration client libra
 
 # Azure.Security.KeyVault.Administration Samples
 
-- Creating, getting, and deleting role assignments [synchronously](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample1_RbacHelloWorldSync.md) or [asynchronously](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample1_RbacHelloWorldAsync.md)
+- Creating, getting, and deleting role assignments and definitions [synchronously](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample1_RbacHelloWorldSync.md) or [asynchronously](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample1_RbacHelloWorldAsync.md)
 - [Assigning roles for specific scopes](https://github.com/Azure/azure-sdk-for-net/blob/main/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/main/sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample1_BackupHelloWorldSync.md) and [asynchronously](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample1_BackupHelloWorldAsync.md)
+- Performing a full key key backup and restore [synchronously](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample1_BackupHelloWorldSync.md) and [asynchronously](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample1_BackupHelloWorldAsync.md)
 - [Performing selective key restore](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample2_SelectiveRestore.md)
 - [Checking the status of a previously started backup or restore](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample3_BackRestoreResume.md)

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

@@ -1,6 +1,6 @@
 # Performing a full key backup and restore (Async)
 
-This sample demonstrates how to a perform full key backup and restore in Azure Managed HSM.
+This sample demonstrates how to perform a full key backup and restore in Azure Managed HSM.
 To get started, you'll need a URI to an Azure Managed HSM. See the [README](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/keyvault/Azure.Security.KeyVault.Administration/README.md) for links and instructions.
 
 ## Creating a KeyVaultBackupClient

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

@@ -74,6 +74,46 @@ To remove a role assignment from a service principal, the role assignment must b
 await client.DeleteRoleAssignmentAsync(KeyVaultRoleScope.Global, createdAssignment.Name);
 ```
 
+## Creating a Role Definition
+
+You can also create custom role definitions with custom permissions:
+
+```C# Snippet:CreateRoleDefinitionAsync
+CreateOrUpdateRoleDefinitionOptions options = new CreateOrUpdateRoleDefinitionOptions(KeyVaultRoleScope.Global)
+{
+    RoleName = "Managed HSM Data Decryptor",
+    Description = "Can only decrypt data using the private key stored in Managed HSM",
+    Permissions =
+    {
+        new KeyVaultPermission()
+        {
+            DataActions =
+            {
+                KeyVaultDataAction.DecryptHsmKey
+            }
+        }
+    }
+};
+KeyVaultRoleDefinition createdDefinition = await client.CreateOrUpdateRoleDefinitionAsync(options);
+```
+
+## Getting a Role Definition
+
+To get a role definition, you'll need to know the globally unique ID (GUID) instead of the name like with role assignments:
+
+```C# Snippet:GetRoleDefinitionAsync
+Guid roleDefinitionId = new Guid(createdDefinition.Name);
+KeyVaultRoleDefinition fetchedDefinition = await client.GetRoleDefinitionAsync(KeyVaultRoleScope.Global, roleDefinitionId);
+```
+
+## Deleting a Role Definition
+
+To delete a role definition, you'll need to know the globally unique ID (GUID) instead of the name like with role assignments:
+
+```C# Snippet:DeleteRoleDefinitionAsync
+await client.DeleteRoleDefinitionAsync(KeyVaultRoleScope.Global, roleDefinitionId);
+```
+
 <!-- LINKS -->
 [azure_cli]: https://learn.microsoft.com/cli/azure
 [DefaultAzureCredential]: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/identity/Azure.Identity/README.md#defaultazurecredential

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

@@ -66,6 +66,46 @@ To remove a role assignment from a service principal, the role assignment must b
 client.DeleteRoleAssignment(KeyVaultRoleScope.Global, createdAssignment.Name);
 ```
 
+## Creating a Role Definition
+
+You can also create custom role definitions with custom permissions:
+
+```C# Snippet:CreateRoleDefinition
+CreateOrUpdateRoleDefinitionOptions options = new CreateOrUpdateRoleDefinitionOptions(KeyVaultRoleScope.Global)
+{
+    RoleName = "Managed HSM Data Decryptor",
+    Description = "Can only decrypt data using the private key stored in Managed HSM",
+    Permissions =
+    {
+        new KeyVaultPermission()
+        {
+            DataActions =
+            {
+                KeyVaultDataAction.DecryptHsmKey
+            }
+        }
+    }
+};
+KeyVaultRoleDefinition createdDefinition = client.CreateOrUpdateRoleDefinition(options);
+```
+
+## Getting a Role Definition
+
+To get a role definition, you'll need to know the globally unique ID (GUID) instead of the name like with role assignments:
+
+```C# Snippet:GetRoleDefinition
+Guid roleDefinitionId = new Guid(createdDefinition.Name);
+KeyVaultRoleDefinition fetchedDefinition = client.GetRoleDefinition(KeyVaultRoleScope.Global, roleDefinitionId);
+```
+
+## Deleting a Role Definition
+
+To delete a role definition, you'll need to know the globally unique ID (GUID) instead of the name like with role assignments:
+
+```C# Snippet:DeleteRoleDefinition
+client.DeleteRoleDefinition(KeyVaultRoleScope.Global, roleDefinitionId);
+```
+
 <!-- LINKS -->
 [azure_cli]: https://learn.microsoft.com/cli/azure
 [DefaultAzureCredential]: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/identity/Azure.Identity/README.md#defaultazurecredential

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

@@ -14,7 +14,7 @@ You can also get the object Id for your currently signed in account by running t
 az ad signed-in-user show --query objectId
 ```
 
-A role definition Id can be obtained from the `Id` property of one of the role definitions returned from `GetRoleAssignments`.
+A role definition Id can be obtained from the `Id` property of one of the role definitions returned from `GetRoleDefinitions`.
 
 ```C# Snippet:CreateRoleAssignmentKeysScope
 string definitionIdToAssign = "<roleDefinitionId>";

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

@@ -5,9 +5,9 @@ To get started, you'll need a URI to an Azure Managed HSM. See the [README](http
 
 ## Checking status of a full key backup operation
 
-Using the `KeyVaultBackupClient` and a `BackupOperation`, you can check the status and retrieve the result of a previously started `BackupOperation`.
+Using the `KeyVaultBackupClient` and a `KeyVaultBackupOperation`, you can check the status and retrieve the result of a previously started `KeyVaultBackupOperation`.
 For example the `Id` from a started operation on one client can be saved to persistent storage instead of waiting for completion immediately.
-At some later time, another client can retrieve the persisted operation Id and construct a `BackupOperation` using a `KeyVaultBackupClient` and the Id
+At some later time, another client can retrieve the persisted operation Id and construct a `KeyVaultBackupOperation` using a `KeyVaultBackupClient` and the Id
 and check for status or wait for completion.
 
 ```C# Snippet:ResumeBackupAsync
@@ -26,9 +26,9 @@ Uri folderUri = backupResult.Value.FolderUri;
 
 ## Checking status of a full key restore operation
 
-Using the `KeyVaultBackupClient` and a `RestoreOperation`, you can check the status and retrieve the result of a previously started `RestoreOperation`.
+Using the `KeyVaultBackupClient` and a `KeyVaultRestoreOperation`, you can check the status and retrieve the result of a previously started `KeyVaultRestoreOperation`.
 For example the `Id` from a started operation on one client can be saved to persistent storage instead of waiting for completion immediately.
-At some later time, another client can retrieve the persisted operation Id and construct a `RestoreOperation` using a `KeyVaultBackupClient` and the Id
+At some later time, another client can retrieve the persisted operation Id and construct a `KeyVaultRestoreOperation` using a `KeyVaultBackupClient` and the Id
 and check for status or wait for completion.
 
 ```C# Snippet:ResumeRestoreAsync

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

@@ -23,7 +23,7 @@ public CreateOrUpdateRoleDefinitionOptions(KeyVaultRoleScope roleScope)
         }
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="CreateOrUpdateRoleDefinitionOptions"/> class using a generated role definition name.
+        /// Initializes a new instance of the <see cref="CreateOrUpdateRoleDefinitionOptions"/> class using the specified 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>