[Communication] - PhoneNumberClient - Adding samples for phone number administration

sdk/communication/Azure.Communication.Administration/README.md

@@ -7,7 +7,7 @@ Identity client: 2020-07-20-preview2
 
 Azure Communication Administration is managing tokens and phone numbers for Azure Communication Services.
 
-[Source code][source] | [Package (NuGet)][package] | [Product documentation][product_docs]
+[Source code][source] | [Package (NuGet)][package] | [Product documentation][product_docs] | [Samples][source_samples]
 
 ## Getting started
 
@@ -205,19 +205,6 @@ Console.WriteLine($"ReservationId: {reservationResponse.Value.ReservationId}, St
 ```C#
 var reservationPurchaseOperation = await client.StartPurchaseReservationAsync(reservationId).ConfigureAwait(false);
 await reservationPurchaseOperation.WaitForCompletionAsync().ConfigureAwait(false);
-
-// Ensure purchase has completed successfuly
-try
-{
-    var reservationStatus = reservationPurchaseOperation.Value;
-    // ...
-}
-catch (Exception ex)
-{
-    Console.WriteLine("Purchase failed");
-    Console.WriteLine(ex.Message);
-}
-
 ```
 
 ### Configure phone number
@@ -249,6 +236,7 @@ This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For m
 [azure_sub]: https://azure.microsoft.com/free/
 [azure_portal]: https://portal.azure.com
 [source]: https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/communication/Azure.Communication.Administration/src
+[source_samples]: https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/communication/Azure.Communication.Administration/samples
 [cla]: https://cla.microsoft.com
 [coc]: https://opensource.microsoft.com/codeofconduct/
 [coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/

sdk/communication/Azure.Communication.Administration/api/Azure.Communication.Administration.netstandard2.0.cs

@@ -76,6 +76,8 @@ public PhoneNumberAdministrationClient(string connectionString, Azure.Communicat
         public virtual System.Threading.Tasks.Task<Azure.Response<Azure.Communication.Administration.Models.PhoneNumberReservation>> GetReservationByIdAsync(string reservationId, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
         public virtual Azure.Communication.Administration.Models.PhoneNumberReservationPurchaseOperation StartPurchaseReservation(string reservationId, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
         public virtual System.Threading.Tasks.Task<Azure.Communication.Administration.Models.PhoneNumberReservationPurchaseOperation> StartPurchaseReservationAsync(string reservationId, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
+        public virtual Azure.Communication.Administration.Models.ReleasePhoneNumberOperation StartReleasePhoneNumber(Azure.Communication.PhoneNumber phoneNumber, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
+        public virtual System.Threading.Tasks.Task<Azure.Communication.Administration.Models.ReleasePhoneNumberOperation> StartReleasePhoneNumberAsync(Azure.Communication.PhoneNumber phoneNumber, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
         public virtual Azure.Communication.Administration.Models.ReleasePhoneNumberOperation StartReleasePhoneNumbers(System.Collections.Generic.IEnumerable<Azure.Communication.PhoneNumber> phoneNumbers, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
         public virtual System.Threading.Tasks.Task<Azure.Communication.Administration.Models.ReleasePhoneNumberOperation> StartReleasePhoneNumbersAsync(System.Collections.Generic.IEnumerable<Azure.Communication.PhoneNumber> phoneNumbers, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
         public virtual Azure.Communication.Administration.Models.PhoneNumberReservationOperation StartReservation(Azure.Communication.Administration.Models.CreateReservationOptions body, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }

sdk/communication/Azure.Communication.Administration/samples/README.md

@@ -9,15 +9,21 @@ name: Azure Communication Administration samples for .NET
 description: Samples for the Azure.Communication.Administration client library
 ---
 
-# Azure Communication Administration SDK Samples
+# Azure Communication Administration SDK samples
 
 Azure Communication Administration is a client library that is used to do operations necessary for using different services offered by Azure Communication Services, such as calling, chat, SMS, PSTN etc.
 To get started you will need to have an Azure Subscription. Once you have this you can go into the Azure portal and create Azure Communication Services resource. The page will give you necessary information to be able to use the sample codes here such as connections string, shared access key, etc.
 
 This client library allows to do following operations:
  - Generate user tokens that allows the holders to access Azure Communication Services.
+ - Purchase, configure and release phone numbers.
 
-<!--
- You can find samples for each of these functions below.
- - [Generate user tokens](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/communication/Azure.Communication.Administration/samples/Sample1_CommunicationIdentityClient.md)
--->
+ #### You can find samples for each of these functions below.
+ - Generate user tokens [synchronously][sample_identity] or [asynchronously][sample_identity_async]
+ - Manage phone numbers [synchronously][sample_admin] or [asynchronously][sample_admin_async]
+
+<!-- LINKS -->
+[sample_identity]: https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/communication/Azure.Communication.Administration/samples/Sample1_CommunicationIdentityClient.md
+[sample_identity_async]: https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/communication/Azure.Communication.Administration/samples/Sample1_CommunicationIdentityClientAsync.md
+[sample_admin]: https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/communication/Azure.Communication.Administration/samples/Sample2_PhoneNumberAdministrationClient.md
+[sample_admin_async]: https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/communication/Azure.Communication.Administration/samples/Sample2_PhoneNumberAdministrationClientAsync.md

sdk/communication/Azure.Communication.Administration/samples/Sample1_CommunicationIdentityClient.md

@@ -6,7 +6,7 @@ To get started you'll need an Azure Communication Services resource. See the REA
 
 ## Create a `CommunicationIdentityClient`
 
-To create a new `CommunicationIdentityClient` you need a connection string to the Azure Communication Services resource that you can get from the Azure Portal once you create a relevant resource. 
+To create a new `CommunicationIdentityClient` you need a connection string to the Azure Communication Services resource that you can get from the Azure Portal once you have created the resource. 
 
 You can set `connectionString` based on an environment variable, a configuration setting, or any way that works for your application.
 
@@ -53,4 +53,4 @@ To see the full example source files, see:
 [ReadMe](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/communication/Azure.Communication.Administration/samples/ReadMe.md)
 [GenerateUserTokenCode](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/communication/Azure.Communication.Administration/tests/samples/Sample1_CommunicationIdentityClient.cs)
 
- -->
+ -->

sdk/communication/Azure.Communication.Administration/samples/Sample1_CommunicationIdentityClientAsync.md

@@ -6,7 +6,7 @@ To get started you'll need an Azure Communication Services resource. See the REA
 
 ## Create a `CommunicationIdentityClient`
 
-To create a new `CommunicationIdentityClient` you need a connection string to the Azure Communication Services resource that you can get from the Azure Portal once you create a relevant resource. 
+To create a new `CommunicationIdentityClient` you need a connection string to the Azure Communication Services resource that you can get from the Azure Portal once you have created the resource. 
 
 You can set `connectionString` based on an environment variable, a configuration setting, or any way that works for your application.
 
@@ -53,4 +53,4 @@ To see the full example source files, see:
 <!--
 [ReadMe](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/communication/Azure.Communication.Administration/samples/ReadMe.md)
 [GenerateUserTokenCode](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/communication/Azure.Communication.Administration/tests/samples/Sample1_CommunicationIdentityClient.cs)
--->
+-->

sdk/communication/Azure.Communication.Administration/samples/Sample2_PhoneNumberAdministrationClient.md

@@ -0,0 +1,200 @@
+# Searching, reserving, purchasing, releasing phone numbers
+
+This sample demonstrates how to search, reserve, purchase and release phone numbers in Azure Communication Services.
+To get started, you'll need a URI to an Azure Communication Services. See the [README](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/communication/Azure.Communication.Administration/README.md) for links and instructions.
+
+## Creating a PhoneNumberAdministrationClient
+
+To create a new `PhoneNumberAdministrationClient` you need a connection string to the Azure Communication Services resource that you can get from the Azure Portal once you have created the resource.
+
+You can set `connectionString` based on an environment variable, a configuration setting, or any way that works for your application.
+
+```C# Snippet:CreatePhoneNumberAdministrationClient
+// Get a connection string to our Azure Communication resource.
+var connectionString = "<connection_string>";
+var client = new PhoneNumberAdministrationClient(connectionString);
+```
+
+## Listing all supported countries
+
+In order to acquire a phone number you will need to know if Azure Communication Services are available in a particular country. You can find out by retrieving a list of supported countries.
+
+```C# Snippet:GetAllSupportedCountries
+var supportedCountries = client.GetAllSupportedCountries(locale);
+foreach (var country in supportedCountries)
+{
+    Console.WriteLine($"Supported country code: {country.CountryCode}, name: {country.LocalizedName}");
+}
+```
+
+## Listing phone plan groups
+
+Phone plan groups come in two types, Geographic and Toll-Free.
+
+```C# Snippet:GetPhonePlanGroups
+var phonePlanGroups = client.GetPhonePlanGroups(countryCode, locale);
+
+foreach (var phonePlanGroup in phonePlanGroups)
+{
+    Console.WriteLine($"Plan group: {phonePlanGroup.LocalizedName}, type: {phonePlanGroup.PhoneNumberType}");
+}
+```
+
+## Listing phone plans
+
+Unlike Toll-Free phone plans, area codes for Geographic phone plans are empty. Area codes are found in the Area Codes API.
+
+```C# Snippet:GetPhonePlans
+var phonePlans = client.GetPhonePlans(countryCode, phonePlanGroupId, locale);
+foreach (var phonePlan in phonePlans)
+{
+    Console.WriteLine($"Plan: {phonePlan.LocalizedName}, {phonePlan.LocationType}");
+}
+```
+
+## Get location options
+
+For Geographic phone plans, you can query the available geographic locations. The locations options are structured like the geographic hierarchy of a country. For example, the US has states and within each state are cities.
+
+```C# Snippet:GetPhonePlanLocationOptions
+var locationOptionsResponse = client.GetPhonePlanLocationOptions(countryCode, geographicPhonePlanGroup.PhonePlanGroupId, phonePlanId);
+
+void PrintLocationOption(LocationOptions locationOptions)
+{
+    Console.WriteLine($"LabelId: {locationOptions.LabelId}, LabelName: {locationOptions.LabelName}");
+
+    foreach (var locationOption in locationOptions.Options)
+    {
+        Console.WriteLine($"Name: {locationOption.Name}, Value: {locationOption.Value}");
+
+        foreach (var subLocationOption in locationOption.LocationOptions)
+            PrintLocationOption(subLocationOption);
+    }
+}
+PrintLocationOption(locationOptionsResponse.Value.LocationOptions);
+```
+
+## Get area codes
+
+Fetching area codes for geographic phone plans will require the location options queries set. You must include the chain of geographic locations traversing down the location options object returned by the GetPhonePlanLocationOptions.
+
+```C# Snippet:GeographicalAreaCodes
+var locationOptionsResponse = client.GetPhonePlanLocationOptions(countryCode, geographicPhonePlanGroupId, geographicPhonePlanId);
+var state = locationOptionsResponse.Value.LocationOptions.Options.First();
+
+var locationOptionsQueries = new List<LocationOptionsQuery>
+{
+    new LocationOptionsQuery
+    {
+        LabelId = "state",
+        OptionsValue = state.Value
+    },
+    new LocationOptionsQuery
+    {
+        LabelId = "city",
+        OptionsValue = state.LocationOptions.First().Options.First().Value
+    }
+};
+
+var areaCodes = client.GetAllAreaCodes(geographicPhonePlan.LocationType.ToString(), countryCode, geographicPhonePlan.PhonePlanId, locationOptionsQueries);
+
+foreach (var areaCode in areaCodes.Value.PrimaryAreaCodes)
+{
+    Console.WriteLine($"Primary area code: {areaCode}");
+}
+```
+
+Area codes for toll-free phone plans can be found in the plan.
+
+```C# Snippet:TollFreePlanAreaCodes
+var phonePlans = client.GetPhonePlans(countryCode, tollFreePhonePlanGroupId, locale);
+var tollFreePhonePlan = phonePlans.First();
+
+foreach (var areaCode in tollFreePhonePlan.AreaCodes)
+{
+    Console.WriteLine($"Area code: {areaCode}");
+}
+```
+
+## Reserve phone numbers
+
+Phone numbers need to be reserved before they can be purchased. Reservation is a long running operation that can be started by `CreateReservationOptions` function that returns an `PhoneNumberReservationOperation` object. `PhoneNumberReservationOperation` can be used to update status of the operation and to check for completeness.
+
+```C# Snippet:ReservePhoneNumbers
+var reservationName = "My reservation";
+var reservationDescription = "reservation description";
+var reservationOptions = new CreateReservationOptions(reservationName, reservationDescription, new[] { phonePlanId }, areaCode);
+reservationOptions.Quantity = 1;
+
+var reservationOperation = client.StartReservation(reservationOptions);
+
+while (!reservationOperation.HasCompleted)
+{
+    Thread.Sleep(2000);
+
+    reservationOperation.UpdateStatus();
+}
+```
+
+## Persist reserve phone numbers operation
+
+You can persist the operation Id of the phone number reservation so that you can come back and check the operation status later.
+
+```C# Snippet:PersistReservePhoneNumbersOperation
+var reservationId = reservationOperation.Id;
+
+// persist reservationOperationId and then continue with new operation
+
+var newPhoneNumberReservationOperation = new PhoneNumberReservationOperation(client, reservationId);
+
+while (!newPhoneNumberReservationOperation.HasCompleted)
+{
+    Thread.Sleep(2000);
+
+    newPhoneNumberReservationOperation.UpdateStatus();
+}
+```
+
+## Purchase phone numbers
+
+Phone numbers can be acquired through purchasing a reservation.
+
+```C# Snippet:StartPurchaseReservation
+var reservationPurchaseOperation = client.StartPurchaseReservation(reservationId);
+
+while (!reservationPurchaseOperation.HasCompleted)
+{
+    Thread.Sleep(2000);
+
+    reservationPurchaseOperation.UpdateStatus();
+}
+```
+
+## Listing acquired phone numbers
+
+You can list all phone numbers that have been acquired for your resource.
+
+```C# Snippet:ListAcquiredPhoneNumbers
+var acquiredPhoneNumbers = client.GetAllPhoneNumbers(locale);
+
+foreach (var phoneNumber in acquiredPhoneNumbers)
+{
+    Console.WriteLine($"Phone number: {phoneNumber.PhoneNumber}, activation state: {phoneNumber.ActivationState}");
+}
+```
+
+## Release phone numbers
+
+If you no longer need a phone number you can release it.
+
+```C# Snippet:ReleasePhoneNumbers
+var acquiredPhoneNumber = "<acquired_phone_number>";
+var phoneNumberReleaseOperation = client.StartReleasePhoneNumber(new PhoneNumber(acquiredPhoneNumber));
+
+while (!phoneNumberReleaseOperation.HasCompleted)
+{
+    Thread.Sleep(2000);
+
+    phoneNumberReleaseOperation.UpdateStatus();
+}
+```