about_AdsFileProvider.help.txt
|
# about_AdsFileProvider
The AdsFileProvider is a PowerShell provider that enables browsing and managing files on remote TwinCAT devices via ADS. ## SHORT DESCRIPTION PowerShell provider for browsing and managing files on remote TwinCAT devices via ADS. ## LONG DESCRIPTION The AdsFileProvider is a PowerShell NavigationCmdletProvider that maps the file system of a remote TwinCAT target to a PSDrive. Once a drive is created, standard PowerShell file commands (Get-ChildItem, Set-Location, Get-Content, New-Item, Remove-Item, Copy-Item) can be used to browse, read, create, and delete files and directories on the device. The provider also implements IContentCmdletProvider (enabling Get-Content / Set-Content) and IPropertyCmdletProvider (enabling Get-ItemProperty). ## DRIVE INITIALIZATION When TwinCAT is running locally, the provider automatically creates default drives for every registered route (including the local system). Additional drives can be created manually with New-PSDrive. ## AUTOMATIC DRIVES On module import, the AdsFileProvider queries the local TwinCAT router for all registered routes (the same list returned by Get-AdsRoute) and creates a PSDrive for each one. A drive for the local system (named after the local host) is always created first, followed by one drive per remote route. If the TwinCAT System Service is not running, no automatic drives are created. ## LISTING AVAILABLE DRIVES Use Get-PSDrive with the -PSProvider filter to list all AdsFileProvider drives: ```powershell PS> Get-PSDrive -PSProvider AdsFileProvider Name Used (GB) Free (GB) Provider Root CurrentLocation ---- --------- --------- -------- ---------- --------------- IPC_01234 AdsFileProvider \ CX_01234 AdsFileProvider \ CX_05678 AdsFileProvider \ ``` The first drive (IPC_01234 in this example) is the local machine, named after Environment.MachineName. The remaining drives correspond to the route names from Get-AdsRoute: ```powershell PS> Get-AdsRoute Name Address NetId Transport IsActive ---- ------- ----- --------- -------- CX_01234 192.168.1.10 192.168.1.10.1.1 TCP/IP True CX_05678 192.168.1.20 192.168.1.20.1.1 TCP/IP True ``` ## CREATING A CUSTOM DRIVE If a route was added after module import, or if you want a drive with a custom name, use New-PSDrive with the AdsFileProvider dynamic parameters: ```powershell # Create a drive by route name or IP address PS> New-PSDrive -Name MyTarget -PSProvider AdsFileProvider -Root '' -Address CX_01234 # Create a drive from a route object (pipeline) PS> Get-AdsRoute -Address CX_01234 | New-PSDrive -Name MyTarget -PSProvider AdsFileProvider -Root '' # Create a drive using an explicit Route parameter PS> $route = Get-AdsRoute -Address CX_01234 PS> New-PSDrive -Name MyTarget -PSProvider AdsFileProvider -Root '' -Route $route ``` After creation the drive can be used like any other AdsFileProvider drive: ```powershell PS> cd MyTarget:\TargetDir PS MyTarget:\TargetDir> dir ``` ## THE ROOT PARAMETER The automatic drives use the drive root (\), which lists the StandardDirectories of the target. New-PSDrive -Root can instead anchor a drive at any existing directory of the target, so that paths below it become relative: ```powershell # Rooted at a StandardDirectory PS> New-PSDrive -Name MyBoot -PSProvider AdsFileProvider -Address CX_01234 -Root '\BOOTDIR' # Rooted at an absolute target directory below GENERIC PS> New-PSDrive -Name MyWin -PSProvider AdsFileProvider -Address CX_01234 -Root '\GENERIC\C:\Windows' PS> dir MyWin: # Rooted at the root of a target volume PS> New-PSDrive -Name MyC -PSProvider AdsFileProvider -Address CX_01234 -Root '\GENERIC\C:' PS> dir MyC:\ # lists C:\ of the target PS> cd MyC:\Windows\System32 ``` The value is verified when the drive is created; a path that does not exist on the target is rejected with "The Root parameter value '...' is invalid". A leading path separator is optional and a trailing one is ignored, and both separators are accepted - -Root 'BOOTDIR', '\BOOTDIR' and 'BOOTDIR\' are equivalent, as are '\GENERIC\C:' and 'GENERIC/C:/'. Each volume needs its own drive; the provider cannot enumerate the volumes of a target. A drive rooted at '\GENERIC' starts at the working directory of the target's System Service, and its volumes are addressed by a relative path, because PowerShell resolves a drive qualifier (C:) against its own drives before the provider is called: ```powershell PS> New-PSDrive -Name MyGen -PSProvider AdsFileProvider -Address CX_01234 -Root 'GENERIC' PS> cd MyGen: PS MyGen:\> dir .\C:\Windows # 'cd C:' would leave the drive ``` On a target with a POSIX file system (TwinCAT/BSD, TwinCAT/Linux) there is no volume qualifier, and a leading path separator of the remainder is swallowed by PowerShell path normalization, so the POSIX root cannot be used as a drive root. Use a '\GENERIC' drive there - its paths are resolved against the working directory of the System Service process, which is / for the shipped systemd unit. ## 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 (defaults to System Service) - Route (IRouteAddressed) - A route object (e.g. from Get-AdsRoute) ## ROOT DIRECTORIES The drive root lists the StandardDirectories of the target as top-level folders. BootDir, BootProject, ConfigDir, Generic, InstallDir, RepositoryDir, TargetDir and UserPath1 .. UserPath9 are queried, and only those the target actually resolves are shown - so the listing differs per target. See STANDARDDIRECTORY NAMES for the complete list of names accepted in a path. ## PATH STRUCTURE ADS paths follow a consistent format that combines an optional provider and drive name, a StandardDirectory, and a path within that directory: ``` [AdsFileProvider::][DriveName:]\StandardDirectory[\Path] ``` Three path forms are supported: - Bare path: \StandardDirectory\path Example: \TARGETDIR\Routes\StaticRoutes.xml - Drive-qualified: DriveName:\StandardDirectory\path Example: CX_01234:\TARGETDIR\Routes\StaticRoutes.xml - Provider-qualified: AdsFileProvider::DriveName:\StandardDirectory\path Example: AdsFileProvider::CX_01234:\TARGETDIR\file.txt The special drive name "Local" (case-insensitive) resolves to the local TwinCAT system, regardless of the machine name: ``` Local:\TARGETDIR\Routes\StaticRoutes.xml ``` This is a built-in path alias of the TcXaeMgmt cmdlets (Copy-AdsRemoteItem, Copy-AdsFile), not a PSDrive. PowerShell resolves drives before the provider is called, so standard cmdlets such as Get-ChildItem or Set-Location report "Cannot find drive" for Local: - use the automatic drive of the local system instead, which is named after the machine (Environment.MachineName). ## STANDARDDIRECTORY NAMES The first path segment after the drive separator must be one of the following StandardDirectory names (case-insensitive): - BOOTDIR - TwinCAT boot folder (CurrentConfig, event logs) - BOOTPROJECT - Boot project file (bootprj / bootprj-old) - BOOTDATA - Boot data file (bootdata / bootdata-old) - CONFIGDIR - TwinCAT configuration path - DATADIR - TwinCAT 3 data directory - GENERIC - An absolute path on the target file system (see below) - INSTALLDIR - TwinCAT runtime installation path - LICENSEDIR - TwinCAT license directory - REPOSITORYDIR - TwinCAT package/component repository directory - TARGETDIR - TwinCAT target path (routes, licenses, certificates) - USERPATH1 .. USERPATH9 - User-defined paths configured on the target BOOTDATA addresses a file rather than a directory. DATADIR and LICENSEDIR can be used in a path but are not listed at the drive root. All StandardDirectories except GENERIC are rooted at a directory that the target's TwinCAT System Service resolves from its own registry, so the remainder of the path is relative to that root. Note that INSTALLDIR is the runtime instance path (for example C:\ProgramData\Beckhoff\TwinCAT\3.1\Runtimes\UmRT_Default\3.1\), not the engineering (XAE) installation directory. ## THE GENERIC STANDARDDIRECTORY GENERIC is the only StandardDirectory that is not rooted at a TwinCAT directory. Everything after GENERIC is passed on to the target system as-is, so an absolute path of the target file system can be addressed directly, including the volume: ```powershell PS> Get-ChildItem CX_01234:\GENERIC\C: # root of the C: volume PS> Get-ChildItem CX_01234:\GENERIC\C:\Windows\System32 PS> Set-Location CX_01234:\GENERIC\C:\Windows PS> Test-Path CX_01234:\GENERIC\C:\Windows\notepad.exe ``` This also works with the TcXaeMgmt cmdlets: ```powershell PS> New-AdsRemoteItem -Path "\GENERIC\C:\tmp\" -Name MyFolder -ItemType Directory PS> Copy-AdsRemoteItem -Path "Local:\GENERIC\C:\tmp\data.bin" -Destination c:\tmp\ -Force PS> Remove-AdsRemoteItem -Path "\GENERIC\C:\tmp\MyFolder" -Recurse -Force ``` If the remainder is not absolute, the target resolves it against the working directory of its TwinCAT System Service process. A bare GENERIC therefore lists that working directory - which is a property of the target, not a browsable root: ```powershell # Lists the working directory of the target service process PS> Get-ChildItem CX_01234:\GENERIC ``` ## USING PATHS WITH CMDLETS Copy-AdsRemoteItem, New-AdsRemoteItem and Remove-AdsRemoteItem accept the same ADS path forms: bare, drive-qualified, Local alias and provider-qualified. The target system is selected with -NetId, -Address, -Route or -SessionId. If none of them is specified, a drive qualifier in the path selects the target; a bare path then falls back to the local system. A target parameter always takes precedence over the drive qualifier. The drive qualifier selects the target AND the root of the drive is applied, exactly as for the provider cmdlets. A path on a drive that is rooted deeper is therefore relative to that root: ```powershell PS> New-PSDrive -Name MyC -PSProvider AdsFileProvider -Address CX_01234 -Root '\GENERIC\C:' PS> Get-ChildItem 'MyC:\tmp' # relative to the drive root PS> Copy-AdsRemoteItem -Path 'MyC:\tmp\data.bin' -Destination c:\tmp\ -Force ``` A bare path (without a drive qualifier) is not affected by any drive root and always starts with a StandardDirectory: ```powershell PS> Copy-AdsRemoteItem -Path '\GENERIC\C:\tmp\data.bin' -Destination c:\tmp\ -Force -Address CX_01234 ``` The Copy-AdsRemoteItem cmdlet additionally detects the transfer direction from the path format. If a path matches the ADS path pattern it is treated as a remote ADS path; otherwise it is treated as a local file system path. ```powershell # Upload (local to ADS) — destination is an ADS path Copy-AdsRemoteItem -Path c:\tmp\Config.xml -Destination "Local:\BOOTDIR\CurrentConfig.xml" -Force # Download (ADS to local) — source is an ADS path Copy-AdsRemoteItem -Path "Local:\TARGETDIR\StaticRoutes.xml" -Destination c:\tmp\ -Force # Bare path with -Address (targets a remote system) Copy-AdsRemoteItem -Path "\TARGETDIR\ReadMe.txt" -Destination c:\tmp\ -Address CX_01234 # ADS-to-ADS copy (both paths are ADS paths) Copy-AdsRemoteItem -Path "Local:\TARGETDIR\source.txt" -Destination "Local:\BOOTDIR\copy.txt" -Force # Absolute target path below GENERIC Copy-AdsRemoteItem -Path "Local:\GENERIC\C:\tmp\data.bin" -Destination c:\tmp\ -Force # Wildcards in source paths Copy-AdsRemoteItem -Path c:\tmp\*.xml -Destination "Local:\TARGETDIR\configs\" -Force ``` ```powershell # Create a directory under TargetDir (bare path — local system) New-AdsRemoteItem -Path "\TARGETDIR\" -Name "MyFolder" -ItemType Directory # Create a file inside that directory New-AdsRemoteItem -Path "\TARGETDIR\MyFolder\" -Name "config.txt" -ItemType File # Create a directory at an absolute target path New-AdsRemoteItem -Path "\GENERIC\C:\tmp\" -Name "MyFolder" -ItemType Directory # Drive-qualified path — the drive selects the target system New-AdsRemoteItem -Path "CX_01234:\TARGETDIR\" -Name "MyFolder" -ItemType Directory # Remove a directory recursively Remove-AdsRemoteItem -Path "CX_01234:\TARGETDIR\MyFolder" -Recurse -Force ``` ## TCXAEMGMT CMDLETS The following TcXaeMgmt cmdlets operate on AdsFileProvider drives: - Copy-AdsFile - Copies files from/to TwinCAT targets (upload and download) - Copy-AdsRemoteItem - Copies files between ADS paths, local paths, or ADS-to-ADS - New-AdsRemoteItem - Creates files and directories on remote TwinCAT targets - Remove-AdsRemoteItem - Removes files and directories from TwinCAT targets ## STANDARD POWERSHELL CMDLETS Once a PSDrive is created, the following standard PowerShell cmdlets work transparently with AdsFileProvider drives: - New-Item - Creates files or directories on the remote target - Remove-Item - Deletes files or directories (supports -Recurse) - Get-Item / Get-ChildItem - Browses remote directories - Get-Content / Set-Content - Reads and writes file content - Test-Path - Checks if a remote path exists - Copy-Item - Copies files on the remote target ## PREREQUISITES - TwinCAT 3 must be installed and running on the local system - A valid ADS route to the target must be configured - The target device must be reachable via ADS ## EXAMPLE: CREATE A DRIVE AND LIST THE STANDARDDIRECTORIES ```powershell PS> New-PSDrive -name CX_01234 -PSProvider AdsFileProvider -Address CX_01234 -Root '' Name Used (GB) Free (GB) Provider Root CurrentLocation ---- --------- --------- -------- ---------- --------------- CX_01234 AdsFileProvider \ PS> dir CX_01234: Mode LastWriteTime Length Name ---- ------------- ------ ---- d---- 30.11.2021 16:11:31 BootDir d---- 03.12.2021 01:17:20 BootProject d---- 17.03.2021 14:33:53 ConfigDir d---- 03.12.2021 01:17:20 Generic d---- 18.06.2021 08:00:22 InstallDir d---- 03.12.2021 01:17:20 RepositoryDir d---- 03.12.2021 15:32:03 TargetDir ``` ## EXAMPLE: BROWSE THE FILES ON THE TWINCAT DEVICE CX_01234 ```powershell PS> cd CX_01234:\TargetDir PS CX_01234:\TargetDir> dir Mode LastWriteTime Length Name ---- ------------- ------ ---- d---- 26.11.2021 17:44:27 CACerts -a--- 14.03.2012 14:50:50 619 DefaultConfig.xml d---- 11.05.2021 14:42:45 License d---- 18.06.2021 08:01:03 Resource d---- 17.03.2021 15:15:51 Routes d---- 18.06.2021 08:00:33 StartMenuAdmin d---- 17.03.2021 14:33:35 StartUp -a--- 30.11.2021 18:46:08 2253 StaticRoutes.xml -a--- 01.02.2012 16:42:58 494 TargetFeatures.xml -a--- 17.03.2021 14:42:50 3113 TcSelfSigned.xml ``` ## EXAMPLE: BROWSE AN ABSOLUTE TARGET PATH ```powershell PS> cd CX_01234:\Generic\C:\Windows PS CX_01234:\Generic\C:\Windows> dir Mode LastWriteTime Length Name ---- ------------- ------ ---- d---- 18.06.2021 08:00:33 System32 d---- 17.03.2021 14:33:35 Temp -a--- 30.11.2021 18:46:08 74752 notepad.exe ``` ## EXAMPLE: READ THE CONTENT OF STATICROUTES.XML ON TARGET CX_01234 ```powershell PS CX_01234:\TargetDir> get-content .\StaticRoutes.xml <?xml version="1.0"?> <TcConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <RemoteConnections> <Route> <Name>TargetIPC</Name> <Address>172.17.60.147</Address> <NetId>172.17.60.147.1.1</NetId> <Type>TCP_IP</Type> <Tls IgnoreCn="true"> <Ca>...</Ca> </Tls> </Route> <Server> <Tls IgnoreCn="true"> <Ca>c:\twincat\3.1\target\CACerts\RootCA.pem</Ca> <Cert>c:\twincat\3.1\target\CACerts\TargetIPC.crt</Cert> <Key>c:\twincat\3.1\target\CACerts\TargetIPC.key</Key> </Tls> </Server> </RemoteConnections> </TcConfig> ``` ## SEE ALSO [Copy-AdsFile Cmdlet](https://infosys.beckhoff.com/help/redirect.asp?F1=BeckhoffSearchNamespace.Copy-AdsFile&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_AdsSymbolProvider](https://infosys.beckhoff.com/help/redirect.asp?F1=BeckhoffSearchNamespace.about_AdsSymbolProvider&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/) |