Why Get-CsTopology can be evil

Recently while performing a web search, I came across a blog that recommended that users read the topology Xml returned from Get-CsTopology in order to provision a UCMA application.  This is really not a good practice and we actually seriously considered removing this cmdlet entirely from the product.  It only stayed due to internal dependencies and the requirement from a small number of partners for very advanced scenarios.

This is an interesting cmdlet for those interested in how the topology is actually constructed, but for all practical purposes this cmdlet should be ignored.  It is too tempting to make a few changes to the Xml and then call Publish-CsTopology with the changes - and this can have disastrous results if done incorrectly.

Instead, we provided a number of cmdlets that provide information about the topology.

Get-CsSite and Set-CsSite allow one to view the sites in the topology and make a few basic changes.  Note that new sites must be created using the topology builder.

Get-CsPool and Set-CsPool act similarly to the site cmdlets but for pools.

Get-CsService allows one to view the services in the topology.  Parameters exist allowing one to limit the results to a particular site.  Also, a parameter exists for each role type to retrieve only services of that role - for instance Get-CsService -Registrar will return all of the registrars in the topology.

To make changes to the ports and other aspects of services, a cmdlet exists for each role.  Therefore to change a registrar you must use Set-CsRegistrar.  Likewise Set-CsApplicationServer applies to applications servers, etc. 

Similar cmdlets exist for computers (Get-CsComputer) and net interfaces (Get-CsNetworkInterface).  SipDomains, which are also part of the topology document, can be access using Get-CsSipDomain and Set-CsSipDomain.

Therefore, for all practical purposes it is not necessary to view the topology document directly.  All of the information is more easily accessible through cmdlets.