about_AdsSymbolProvider.help.txt
|
# about_AdsSymbolProvider
The AdsSymbolProvider is a PowerShell provider that binds TwinCAT target device symbolic information to a PSDrive. ## SHORT DESCRIPTION PowerShell provider for browsing TwinCAT target device symbols via ADS. ## LONG DESCRIPTION The AdsSymbolProvider is a PowerShell NavigationCmdletProvider that exposes the symbolic information (PLC variables, data types, system symbols) of a TwinCAT ADS server as a navigable PSDrive. Once a drive is created, standard PowerShell commands (Get-ChildItem, Set-Location, Get-ItemProperty) can be used to browse the symbol tree. The provider also implements IPropertyCmdletProvider to allow reading symbol properties such as data type, size, and instance path. ## DRIVE INITIALIZATION Unlike the AdsFileProvider, the AdsSymbolProvider does not create default drives automatically. Drives must be created manually with New-PSDrive, specifying the target route and AMS port of the symbol server. ## LIMITATIONS The AdsSymbolProvider is prototypic and has known limitations: - Drives are never created automatically. You must always use New-PSDrive to create a symbol drive manually. - Browsing array elements does not work reliably because the square bracket characters [ and ] clash with PowerShell wildcard syntax. PowerShell interprets these as character-range patterns, which breaks navigation into array sub-elements (e.g. MAIN.myArray[0]). - For reliable symbol access including arrays, prefer the Get-TcSymbol and Read-TcValue cmdlets over PSDrive navigation. ## DYNAMIC PARAMETERS When creating a new drive with New-PSDrive, the following dynamic parameters are available: - Address (string) - Route name or IP address of the target - Port (int) - AMS port of the symbol server (default: 851) - Route (IRouteAddressed) - A route object (e.g. from Get-AdsRoute) ## THE ROOT PARAMETER -Root '' anchors the drive at the top of the symbol tree. An instance path can be given instead to anchor the drive inside the tree, so that paths below it become relative: ```powershell PS> New-PSDrive -Name MyMain -PSProvider AdsSymbolProvider -Address CX_01234 -Port 851 -Root '\MAIN' ``` A leading path separator is optional and a trailing one is ignored - -Root 'MAIN', '\MAIN' and 'MAIN\' are equivalent. ## VISIBLE PORTS The provider filters available ADS server ports to those commonly hosting symbol information: - 300-303 - TwinCAT system ports - 501 - Router port - 801, 811, 821, 831 - I/O task ports - 850-855 - PLC runtime ports (PLC 1 through PLC 6) - 27905-27910 - C++ module ports ## STANDARD POWERSHELL CMDLETS Once a PSDrive is created, the following standard PowerShell cmdlets work transparently with AdsSymbolProvider drives: - Get-ChildItem - Browses the symbol tree - Set-Location - Navigates into symbol sub-paths - Get-Item - Gets symbol information - Get-ItemProperty - Retrieves symbol properties (data type, size, instance path) ## RELATED TCXAEMGMT CMDLETS These cmdlets query symbol information directly via ADS sessions (without requiring a PSDrive) and offer additional features like recursive browsing and filtering: - Get-TcSymbol - Get symbols from a TwinCAT target (supports -Recurse and -Path wildcards) - Get-TcDataType - Get data types from a TwinCAT target (supports filtering by name and category) - Read-TcValue - Read symbol values by path - Write-TcValue - Write symbol values by path ## PREREQUISITES - TwinCAT 3 must be installed and running on the local system - A valid ADS route to the target must be configured - The target ADS server must be in RUN or CONFIG mode - The specified AMS port must host an active symbol server (e.g. a PLC runtime on port 851) ## EXAMPLE Binds the target device symbolic information to a PSDrive. To register a symbol server as PSDrive type (here the Target Route 'CX_01234' with AmsPort: 851) ```powershell PS> New-PSDrive -Name CX_01234_Symbols -PSProvider AdsSymbolProvider -Address CX_01234 -Port 851 -Root '' PS> cd CX_01234_Symbols: PS> CX_01234_Symbols:> dir ``` ## SEE ALSO [Get-TcSymbol Cmdlet](https://infosys.beckhoff.com/help/redirect.asp?F1=BeckhoffSearchNamespace.Get-TcSymbol&locale=en-US&codeLang=) [Get-TcDataType Cmdlet](https://infosys.beckhoff.com/help/redirect.asp?F1=BeckhoffSearchNamespace.Get-TcDataType&locale=en-US&codeLang=) [about_providers] (https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_providers) [Documentation TcXaeMgmt Module](https://infosys.beckhoff.com/content/1033/tc3_ads_ps_tcxaemgmt/index.html) [about_AdsFileProvider](https://infosys.beckhoff.com/help/redirect.asp?F1=BeckhoffSearchNamespace.about_AdsFileProvider&locale=en-US&codeLang=) [about_TcXaeMgmt](https://infosys.beckhoff.com/help/redirect.asp?F1=BeckhoffSearchNamespace.about_tcxaeMgmt&locale=en-US&codeLang=) [Beckhoff Homepage](https://www.beckhoff.com/) |