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:
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:
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:
# 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:
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: StandardDirectorypath
Example: TARGETDIRRoutesStaticRoutes.xml
- Drive-qualified: DriveName:StandardDirectorypath
Example: CX_01234:TARGETDIRRoutesStaticRoutes.xml
- Provider-qualified: AdsFileProvider::DriveName:StandardDirectorypath
Example: AdsFileProvider::CX_01234:TARGETDIRfile.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.
# 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:
# 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
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
PS> get-help about_providers
Example: Create a new AdsFileProvider Drive to the TwinCAT Device CX_01234
> 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
> 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
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>