axl-dotnet-samples

Overview

These C# samples demonstrate how to use the DotNet SoapCore package to read/update CUCM configurations with the AXL SOAP API.

The concepts and techniques shown can be extended to enable automated management of virtually any configuration or setting in the CUCM admin UI.

Tested using:

getPhone.cs - Executes a <getPhone> request and displays the response (<getPhone>)
addUser.cs - Adds a simple end user, then deletes the user (<addUser>, <removeUser>)
executeSqlQuery.cs - Performs an executeSqlQuery request to retrieve Application User details,
then prints a short report to the console.

From a terminal, use git to clone this repo to your PC, then change into the new directory:
```
git clone https://www.github.com/CiscoDevNet/axl-dotnet-samples
cd axl-dotnet-samples
```
Install the DotNet Core SDK 3.1:
```
sudo apt install dotnet-sdk-3.1
```
Install the dotnet-svcutil utility for generating SOAP client code from WSDL files (requires DotNet Core 2.1)
```
sudo apt instasll dotnet-sdk-2.1
dotnet tool install --global dotnet-svcutil
```
This project includes the AXL WSDL files for CUCM 12.5. If you wish to use another version:
- From the CUCM admin pages, navigate to Applications / Plugins, click Find and download the "Cisco AXL Toolkit":
- Extract the .zip file. From the appropriate version directory under schema/, copy the AXLAPI.wsdl, AXLEnums.xsd, and AXLSoap.xsd files to the schema/ directory under this project
Some limitations of WCF or quirks in the AXL schema/implementation may require tweaks to the AXL WSDL schema files prior to generating client code.

See quirks.sh to see if any of these issues apply for the requests you may be using, and either perform the tweaks manually, or simply execute the script to apply all of them:
```
./quirks.sh
```

Use dotnet-svcutil to generate the AXL client code. From the project root:

~/.dotnet/tools/dotnet-svcutil --outputDir AXLClient  --outputFile AXLClient --namespace *,AXLClient schema/AXLAPI.wsdl

Install the AXL web service HTTPS certificate:

Download the certificate from your target CUCM server:

echo -n | openssl s_client -connect ds-ucm1251.cisco.com:8443 | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > cucm.crt

Copy it to the local certificate trust store directory:
```
sudo cp cucm.crt /usr/local/share/ca-certificates/
```
Update the OS certificate trust list:
```
sudo update-ca-certificates
```

Install needed DotNet dependencies:
```
dotnet restore
```
Open the project directory in Visual Studio Code:
```
code .
```
Rename .env.example to .env, and edit it to specify your CUCM address and AXL user credentials (be sure to save the file!)
To run a specific sample, open the Run tab in VS Code, select the sample from the launch dropdown, and click the green Start Debugging arrow (or press F5)

To enable printing debug output of the XML request/response, set Debug=True in .env
When constructing request objects, it can be difficult to discern the names of elements that represent xsd:choice options, for example <name> and <uuid> in <getPhone>:

SoapCore models these options by creating ItemElementName elements with arbitarily assigned type numbers, e.g.: ItemChoiceType142

Intellisense can help greatly in figuring out which of these similarly-named elements belong to a particular parent element:

Peeking into the auto-generated AXL client file (AXLClient/AXLClient.cs) can also be informative: