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 \TargetDir CX_01234 AdsFileProvider \TargetDir CX_05678 AdsFileProvider \TargetDir ``` 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 ``` ## 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 exposes TwinCAT standard directories as top-level folders: - BootDir - TwinCAT Boot folder (CurrentConfig, event logs) - BootProject - Boot project files (bootprj) - ConfigDir - TwinCAT configuration path - Generic - Freely-chosen file paths - InstallDir - TwinCAT installation path - RepositoryDir - TwinCAT repository directory - TargetDir - TwinCAT target path (routes, licenses, certificates) ## PATH STRUCTURE ADS paths follow a consistent format that combines an optional drive name, a StandardDirectory, and a relative path within that directory: ``` [DriveName:]\StandardDirectory[\RelativePath] ``` 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) always resolves to the local TwinCAT system, regardless of the machine name. This is a built-in path alias, not the actual PSDrive name. The automatic drive for the local system is named after the machine (Environment.MachineName): ``` Local:\TARGETDIR\Routes\StaticRoutes.xml ``` ## 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 files (bootprj) - BOOTDATA - Boot data files - CONFIGDIR - TwinCAT configuration path - GENERIC - Freely-chosen full file path - INSTALLDIR - TwinCAT installation path - REPOSITORYDIR - TwinCAT repository directory - TARGETDIR - TwinCAT target path (routes, licenses, certificates) ## USING PATHS WITH CMDLETS The Copy-AdsRemoteItem cmdlet automatically 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 # Wildcards in source paths Copy-AdsRemoteItem -Path c:\tmp\*.xml -Destination "Local:\TARGETDIR\configs\" -Force ``` The New-AdsRemoteItem and Remove-AdsRemoteItem cmdlets use bare ADS paths with the -Path parameter: ```powershell # Create a directory under TargetDir New-AdsRemoteItem -Path "\TARGETDIR\" -Name "MyFolder" -ItemType Directory # Create a file inside that directory New-AdsRemoteItem -Path "\TARGETDIR\MyFolder\" -Name "config.txt" -ItemType File # Remove a directory recursively Remove-AdsRemoteItem -Path "\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 ```powershell PS> New-PSDrive -name CX_01234 -PSProvider AdsFileProvider -Address CX_01234 -Root '' 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 > cd CX_01234:/BootDir PS CX_01234:\BootDir> dir Mode LastWriteTime Length Name ---- ------------- ------ ---- d---- 05.10.2021 10:36:34 CurrentConfig -a--- 05.10.2021 10:36:34 4563 CurrentConfig.tszip -a--- 05.10.2021 10:36:34 17113 CurrentConfig.xml -a--- 30.11.2021 16:11:31 126976 LoggedEvents.db d---- 27.10.2021 11:32:43 Plc ``` ## More Information about Providers ```powershell PS> get-help about_providers ``` ## Example: Create a new AdsFileProvider Drive to the TwinCAT Device CX_01234 ```powershell > New-PSDrive -name CX_01234 -PSProvider AdsFileProvider -Address CX_01234 -Root '' Name Used (GB) Free (GB) Provider Root CurrentLocation ---- --------- --------- -------- ---------- --------------- CX_01234 AdsFileProvider \TargetDir ``` ## Example: Browse the files on the TwinCAT Device CX_01234 ```powershell > cd CX_01234: 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: Read the content of the 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/) |