Merge pull request #235078 from ShawnJackson/communication-services-telephony

[AQ] edit pass: Articles about configuring voice routing and validating a domain

Author: paulth1

articles/communication-services/how-tos/telephony/domain-validation.md

@@ -1,6 +1,6 @@
 ---
 title: Azure Communication Services direct routing domain validation
-description: A how-to page about domain validation for direct routing.
+description: Learn how to validate a domain for direct routing.
 services: azure-communication-services
 author: boris-bazilevskiy
 
@@ -12,54 +12,49 @@ ms.custom: include file
 ms.author: nikuklic
 ---
 
-# Domain validation
+# Validate a domain for direct routing
 
-This page describes the process of domain name ownership validation. Fully Qualified Domain Name (FQDN) consists of two parts: host name and domain name. For example, if your session border controller (SBC) name is `sbc1.contoso.com`, then `sbc1` would be a host name, while `contoso.com` would be a domain name. If there's an SBC with FQDN of `acs.sbc1.testing.contoso.com`, `acs` would be a host name, and `sbc1.testing.contoso.com` would be a domain name. To use direct routing, you need to validate that you own a domain part of your FQDN.
+This article describes the process of validating domain name ownership by using the Azure portal.
 
-Azure Communication Services direct routing configuration consists of the following steps:
+A fully qualified domain name (FQDN) consists of two parts: host name and domain name. For example, if your session border controller (SBC) name is `sbc1.contoso.com`, then `sbc1` is the host name and `contoso.com` is the domain name. If an SBC has an FQDN of `acs.sbc1.testing.contoso.com`, then `acs` is the host name and `sbc1.testing.contoso.com` is the domain name.
 
-- Verify domain ownership for your SBC FQDN
-- Configure SBC FQDN and port number
-- Create voice routing rules
+To use direct routing in Azure Communication Services, you need to validate that you own the domain part of your SBC FQDN. After that, you can configure the SBC FQDN and port number and then create voice routing rules.
 
-## Domain ownership validation
+When you're verifying the domain name portion of the SBC FQDN, keep in mind that the `*.onmicrosoft.com` and `*.azure.com` domain names aren't supported. For example, if you have two domain names, `contoso.com` and `contoso.onmicrosoft.com`, use `sbc.contoso.com` as the SBC name.
 
-Make sure to add and verify domain name portion of the FQDN and keep in mind that the `*.onmicrosoft.com` and `*.azure.com` domain names aren't supported for the SBC FQDN domain name. For example, if you have two domain names, `contoso.com` and `contoso.onmicrosoft.com`, use `sbc.contoso.com` as the SBC name. If using a subdomain, make sure this subdomain is also added and verified. For example, if you want to use `sbc.acs.contoso.com`, then `acs.contoso.com` needs to be registered.
+If you're using a subdomain, make sure that this subdomain is also added and verified. For example, if you want to use `sbc.acs.contoso.com`, you need to register `acs.contoso.com`.
 
-### Domain verification using Azure portal
+## Add a new domain name
 
-#### Add new domain name
-
-1. Open Azure portal and navigate to your [Communication Service resource](../../quickstarts/create-communication-resource.md).
-1. In the left navigation pane, select Direct routing under Voice Calling - PSTN.
-1. Select Connect domain from the Domains tab.
-1. Enter the domain part of SBC’s fully qualified domain name.
+1. Open the Azure portal and go to your [Communication Services resource](../../quickstarts/create-communication-resource.md).
+1. On the left pane, under **Voice Calling - PSTN**, select **Direct routing**.
+1. On the **Domains** tab, select **Connect domain**.
+1. Enter the domain part of the SBC FQDN.
 1. Reenter the domain name.
-1. Select Confirm and then select Add.
+1. Select **Confirm**, and then select **Add**.
 
 [![Screenshot of adding a custom domain.](./media/direct-routing-add-domain.png)](./media/direct-routing-add-domain.png#lightbox)
 
-#### Verify domain ownership
+## Verify domain ownership
 
-1. Select Verify next to new domain that is now visible in Domain’s list.
-1. Azure portal generates a value for a TXT record, you need to add that record to
+1. On the **Domains** tab, select **Verify** next to the new domain that you created.
+1. The Azure portal generates a value for a TXT record. Add that record to your domain's registrar or DNS hosting provider with the provided value.
 
-[![Screenshot of verifying a custom domain.](./media/direct-routing-verify-domain-2.png)](./media/direct-routing-verify-domain-2.png#lightbox)
+   [![Screenshot of verifying a custom domain.](./media/direct-routing-verify-domain-2.png)](./media/direct-routing-verify-domain-2.png#lightbox)
 
->[!Note] 
->It might take up to 30 minutes for new DNS record to propagate on the Internet
+   It might take up to 30 minutes for a new DNS record to propagate on the internet.
 
-3. Select Next. If everything is set up correctly, you should see Domain status changed to *Verified* next to the added domain.
+1. Select **Next**. If you set up everything correctly, **Domain status** should change to **Verified** next to the added domain.
 
-[![Screenshot of a verified domain.](./media/direct-routing-domain-verified.png)](./media/direct-routing-domain-verified.png#lightbox)
+   [![Screenshot of a verified domain.](./media/direct-routing-domain-verified.png)](./media/direct-routing-domain-verified.png#lightbox)
 
-#### Remove domain from Azure Communication Services
+## Remove a domain from Azure Communication Services
 
-If you want to remove a domain from your Azure Communication Services direct routing configuration, select the checkbox fir a corresponding domain name, and select *Remove*.
+If you want to remove a domain from your Azure Communication Services direct routing configuration, select the checkbox for a corresponding domain name, and then select **Remove**.
 
 [![Screenshot of removing a custom domain.](./media/direct-routing-remove-domain.png)](./media/direct-routing-remove-domain.png#lightbox)
 
-## Next steps:
+## Next steps
 
 ### Conceptual documentation
 
@@ -70,4 +65,4 @@ If you want to remove a domain from your Azure Communication Services direct rou
 ### Quickstarts
 
 - [Outbound call to a phone number](../../quickstarts/telephony/pstn-call.md)
-- [Redirect inbound telephony calls with Call Automation](../../quickstarts/call-automation/redirect-inbound-telephony-calls.md)
+- [Redirect inbound telephony calls with Call Automation](../../quickstarts/call-automation/redirect-inbound-telephony-calls.md)

articles/communication-services/quickstarts/telephony/includes/voice-routing-sdk-csharp.md

@@ -1,6 +1,6 @@
 ---
 title: include file
-description: A quickstart on how to use Number Management C# SDK to configure direct routing.
+description: Learn how to use the Number Management C# SDK to configure direct routing.
 services: azure-communication-services
 author: boris-bazilevskiy
 
@@ -16,24 +16,27 @@ ms.author: nikuklic
 
 - An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
 - An active Communication Services resource and connection string. [Create a Communication Services resource](../../create-communication-resource.md).
-- The latest version [.NET Core client library](https://dotnet.microsoft.com/download/dotnet-core) for your operating system.
-- Fully Qualified Domain Name (FQDN) and port number of a Session Border Controller (SBC) in operational telephony system.
-- [Verified domain name](../../../how-tos/telephony/domain-validation.md) of the SBC FQDN.
+- The latest version of the [.NET Core client library](https://dotnet.microsoft.com/download/dotnet-core) for your operating system.
+- The fully qualified domain name (FQDN) and port number of a session border controller (SBC) in an operational telephony system.
+- The [verified domain name](../../../how-tos/telephony/domain-validation.md) of the SBC FQDN.
 
 ## Final code
 
-Find the finalized code for this quickstart on [GitHub](https://github.com/Azure-Samples/communication-services-dotnet-quickstarts/tree/main/DirectRouting)
+Find the finalized code for this quickstart on [GitHub](https://github.com/Azure-Samples/communication-services-dotnet-quickstarts/tree/main/DirectRouting).
 
-## Create a new C# application
+You can also find more usage examples for `SipRoutingClient` on [GitHub](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/communication/Azure.Communication.PhoneNumbers/README.md#siproutingclient).
 
-In a console window (such as cmd, PowerShell, or Bash), use the `dotnet new` command to create a new console app.
+## Create a C# application
+
+In a console window (such as Command Prompt, PowerShell, or Bash), use the `dotnet new` command to create a new console app:
 
 ```console
     dotnet new console -o DirectRoutingQuickstart
 ```
 
-This command creates a simple "Hello World" C# project with a single source file: **Program.cs**.
-Change your directory to the newly created app folder and use the dotnet build command to compile your application.
+This command creates a simple "Hello World" C# project with a single source file: *Program.cs*.
+
+Change your directory to the newly created app folder, and use the `dotnet build` command to compile your application:
 
 ``` console
     cd DirectRoutingQuickstart
@@ -42,39 +45,35 @@ Change your directory to the newly created app folder and use the dotnet build c
 
 ## Install the package
 
-While still in the application directory, install the Azure Communication PhoneNumbers client library for .NET package by using the dotnet add package command.
+While you're still in the application directory, install the Azure Communication PhoneNumbers client library for .NET by using the `dotnet add package` command:
 
 ``` console
     dotnet add package Azure.Communication.PhoneNumbers --version 1.1.0
 ```
 
-Add a using directive to the top of **Program.cs** to include the namespaces.
+Add a `using` directive to the top of *Program.cs* to include the namespaces:
 
 ``` csharp
 using Azure.Communication.PhoneNumbers.SipRouting;
 ```
 
 ## Authenticate the client
 
-Phone Number clients can be authenticated using [connection string from an Azure Communication Services resource](../../create-communication-resource.md#access-your-connection-strings-and-service-endpoints). 
+Authenticate phone number clients by using a [connection string from an Azure Communication Services resource](../../create-communication-resource.md#access-your-connection-strings-and-service-endpoints):
 
 ``` csharp
-// Get a connection string to our Azure Communication Services resource.
+// Get a connection string to the Azure Communication Services resource.
 var connectionString = "<connection_string>";
 var client = new SipRoutingClient(connectionString);
 ```
 
-## Setup direct routing configuration
+## Set up a direct routing configuration
 
-Direct routing configuration consists of:
+In the [prerequisites](#prerequisites), you verified domain ownership. The next steps are to create trunks (add SBCs) and create voice routes.
 
-1. Domain ownership verification - see [prerequisites](#prerequisites)
-1. Creating trunks (adding SBCs)
-1. Creating voice routes
+### Create or update trunks
 
-### Create or update Trunks
-
-Azure Communication Services direct routing allows communication with registered SBCs only. To register an SBC you need its FQDN and port.
+Azure Communication Services direct routing allows communication with registered SBCs only. To register an SBC, you need its FQDN and port:
 
 ``` csharp
 // Register your SBCs by providing their fully qualified domain names and port numbers.
@@ -90,10 +89,11 @@ await client.SetTrunksAsync(new List<SipTrunk> { usTrunk, euTrunk });
 
 ### Create or update routes
 
-> [!NOTE]
-> Order of routes does matter, as it determines priority of routes. The first route that matches the regex will be picked for a call.
+Provide routing rules for outbound calls. Each rule consists of two parts: a regex pattern that should match a dialed phone number, and the FQDN of a registered trunk where the call is routed.
+
+The order of routes determines the priority of routes. The first route that matches the regex will be picked for a call.
 
-For outbound calling routing rules should be provided. Each rule consists of two parts: regex pattern that should match dialed phone number and FQDN of a registered trunk where call is routed. In this example, we create one route for numbers that start with `+1` and a second route for numbers that start with just `+`
+In this example, you create one route for numbers that start with `+1` and a second route for numbers that start with just `+`:
 
 ``` csharp
 var usRoute = new SipTrunkRoute("UsRoute", "^\\+1(\\d{10})$", trunks: new List<string> { usSbcFqdn });
@@ -102,37 +102,31 @@ var defaultRoute = new SipTrunkRoute("DefaultRoute", "^\\+\\d+$", trunks: new Li
 await client.SetRoutesAsync(new List<SipTrunkRoute> { usRoute, defaultRoute });
 ```
 
-### Updating existing configuration
+## Update a direct routing configuration
 
-Properties of specific Trunk can be updated by overwriting the record with the same FQDN. For example, you can set new SBC Port value.
+You can update the properties of a specific trunk by overwriting the record with the same FQDN. For example, you can set a new SBC port value:
 
 ``` csharp
 var usTrunk = new SipTrunk("sbc.us.contoso.com", 5063);
 await client.SetTrunkAsync(usTrunk);
 ```
 
-> [!IMPORTANT]
->The same method is used to create and update routing rules. When updating routes, all routes should be sent in single update and routing configuration will be fully overwritten by the new one. 
+You use the same method to create and update routing rules. When you update routes, send all of them in a single update. The new routing configuration fully overwrites the former one.
 
-### Removing a direct routing configuration
+## Remove a direct routing configuration
 
-You can't edit or remove single voice route. Entire voice routing configuration should be overwritten. Here's the example of an empty list that removes all the routes and trunks:
+You can't edit or remove a single voice route. You should overwrite the entire voice routing configuration. Here's an example of an empty list that removes all the routes and trunks:
 
 ``` csharp
 //delete all configured voice routes
 await client.SetRoutesAsync(new List<SipTrunkRoute>());
 
 //delete all trunks
 await client.SetTrunksAsync(new List<SipTrunk>());
-``` 
+```
 
-You can delete a single trunk (SBC), if it isn't used in any voice route. If SBC is listed in any voice route, that route should be deleted first.
+You can use the following example to delete a single trunk (SBC), if no voice routes are using it. If the SBC is listed in any voice route, delete that route first.
 
 ``` csharp
 await client.DeleteTrunkAsync("sbc.us.contoso.com");
 ```
-
-<!-- All direct routing configuration can be deleted by overriding routes and trunks configuration with a new configuration or an empty list. Same methods are used in "Create or Update Trunks" and "Create or Update Routes" sections. -->
-
-> [!NOTE]
-> More usage examples for SipRoutingClient can be found [here](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/communication/Azure.Communication.PhoneNumbers/README.md#siproutingclient).