Write-MdpTransferObject

SYNOPSIS

Executes an MDP Service Transfer Object (asynchronous operation) on a TwinCAT target.

SYNTAX

NetIdPort (Default)

Write-MdpTransferObject [-NetId <AmsNetId>] [-Timeout <Int32>] -Module <MdpModuleType> -MethodName <String>
 -Value <Object> [-PollingRate <Int32>] [-OperationTimeout <Int32>] [-Quiet]
 [-WhatIf] [-Confirm] [<CommonParameters>]

AddressStr

Write-MdpTransferObject [-Address] <String> [-Timeout <Int32>] -Module <MdpModuleType> -MethodName <String>
 -Value <Object> [-PollingRate <Int32>] [-OperationTimeout <Int32>] [-Quiet]
 [-WhatIf] [-Confirm] [<CommonParameters>]

Route

Write-MdpTransferObject [-InputObject] <IRoute> [-Timeout <Int32>] -Module <MdpModuleType> -MethodName <String>
 -Value <Object> [-PollingRate <Int32>] [-OperationTimeout <Int32>] [-Quiet]
 [-WhatIf] [-Confirm] [<CommonParameters>]

Session

Write-MdpTransferObject -Session <ISession> [-Timeout <Int32>] -Module <MdpModuleType> -MethodName <String>
 -Value <Object> [-PollingRate <Int32>] [-OperationTimeout <Int32>] [-Quiet]
 [-WhatIf] [-Confirm] [<CommonParameters>]

DESCRIPTION

The Write-MdpTransferObject cmdlet writes trigger data to an MDP Service Transfer Object, optionally polls the operation status, and returns the result. Service Transfer Objects are asynchronous operations like AddUser, Reboot, AddRoute, ApplyNetworkSettings, etc.

Use Get-MdpModules -ServiceObjects to discover available operations on a target. The cmdlet supports ShouldProcess (-WhatIf / -Confirm) and requires confirmation by default (ConfirmImpact = High). Use -Quiet or -Force to suppress the confirmation prompt.

This cmdlet is preliminary and subject to change.

EXAMPLES

Example 1

PS> Write-MdpTransferObject -Module NIC -MethodName ApplyNetworkSettings -Value "1"

ModuleType   MethodName            Status  StatusDescription
----------   ----------            ------  -----------------
NIC          ApplyNetworkSettings   0      Success (no data)

Executes the ApplyNetworkSettings operation on the local NIC module and waits for completion.

Example 2

PS> Write-MdpTransferObject -Module NIC -MethodName ApplyNetworkSettings -Value "1" -NetId 5.62.192.46.1.1

ModuleType   MethodName            Status  StatusDescription
----------   ----------            ------  -----------------
NIC          ApplyNetworkSettings   0      Success (no data)

Executes the operation on a remote target system.

Example 3

PS> Write-MdpTransferObject -Module NIC -MethodName ApplyNetworkSettings -Value "1" -PollingRate 0 -Quiet

ModuleType   MethodName            Status  StatusDescription
----------   ----------            ------  -----------------
NIC          ApplyNetworkSettings   255    Fire-and-forget (not polled)

Fire-and-forget: sends the trigger and returns immediately without polling for completion.

Example 4

PS> Write-MdpTransferObject -Module UserManagement -MethodName AddUser -Value "newuser" -WhatIf
What if: Performing the operation "Write-MdpTransferObject" on target "Execute MDP operation 'Add User' on module 'UserManagement'".

Shows what would happen without executing the operation.

Example 5

PS> Write-MdpTransferObject -Module NIC -MethodName ApplyNetworkSettings -Value "1" -OperationTimeout 60 -PollingRate 500

ModuleType   MethodName            Status  StatusDescription
----------   ----------            ------  -----------------
NIC          ApplyNetworkSettings   0      Success (no data)

Executes the operation with a custom timeout of 60 seconds and a polling interval of 500 ms.

Example 6

# Multi-field operation using a hashtable - keys match the DTO constructor parameters (case-insensitive):
PS> Write-MdpTransferObject -Module FileSystemObject -MethodName 'CopyFile' -Value @{
>>     SourcePath      = 'C:\TwinCAT\Boot\OldConfig.xml'
>>     DestinationPath = 'C:\TwinCAT\Boot\Backup\OldConfig.xml'
>>     Flags           = 1
>> } -Quiet -Confirm:$false

ModuleType         MethodName  Status  StatusDescription    Output
----------         ----------  ------  -----------------    ------
FileSystemObject   CopyFile    0       Success (no data)

Copies a file on the target using a hashtable to specify multiple input fields. The hashtable keys (SourcePath, DestinationPath, Flags) are matched to the FsoCopyFileInput constructor parameters. This works on all PowerShell hosts (5.1+, 7.x).

Example 7

# Multi-field operation using a JSON string - parsed and mapped to the DTO constructor:
PS> $json = '{"SourcePath":"C:\\TwinCAT\\Boot\\Config.xml","DestinationPath":"C:\\Backup\\Config.xml","Flags":1}'
PS> Write-MdpTransferObject -Module FileSystemObject -MethodName 'CopyFile' -Value $json -Quiet -Confirm:$false

ModuleType         MethodName  Status  StatusDescription    Output
----------         ----------  ------  -----------------    ------
FileSystemObject   CopyFile    0       Success (no data)

Uses a JSON object string as input. JSON keys are matched case-insensitively to the DTO constructor parameters. Note: backslashes in file paths must be escaped as in JSON.

Example 8

# Multi-field operation using a pre-constructed typed DTO:
PS> $dto = [TwinCAT.Mdp.FsoCopyFileInput]::new('C:\Source\File.txt', 'C:\Dest\File.txt', 1)
PS> Write-MdpTransferObject -Module FileSystemObject -MethodName 'CopyFile' -Value $dto -Quiet -Confirm:$false

ModuleType         MethodName  Status  StatusDescription    Output
----------         ----------  ------  -----------------    ------
FileSystemObject   CopyFile    0       Success (no data)

Passes a fully typed IMdpTransferInput DTO directly. This is the most explicit form and avoids any runtime type resolution. Use Get-MdpModules -ServiceObjects to discover the input type for each operation.

Example 9

# Reading structured output - operations that return data expose an Output property:
PS> $result = Write-MdpTransferObject -Module FileSystemObject -MethodName 'Dir' -Value 'C:\TwinCAT\Boot\*' -Quiet -Confirm:$false
PS> $result.Output

Entries          TotalSize  Path
-------          ---------  ----
{file1, file2}   4096       C:\TwinCAT\Boot

When the operation returns structured output (IMdpTransferOutput), the result's Output property is a PSObject with the DTO's public properties exposed as NoteProperties.

PARAMETERS

-NetId

NetId of the target system. Tab completion: Completes AmsNetId values from currently reachable routes on the local TwinCAT system.

Type: AmsNetId
Parameter Sets: NetIdPort
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Address

The address of the target system. This can be the RouteName, NetId, HostName, or IPAddress. Wildcards are permitted. Tab completion: Completes route names from currently reachable ADS systems on the local TwinCAT system.

Type: String
Parameter Sets: AddressStr
Aliases: Name

Required: True
Position: 0
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-InputObject

The route object to the target system. Can be piped from Get-AdsRoute. Tab completion: Completes route names from currently reachable ADS systems on the local TwinCAT system.

Type: IRoute
Parameter Sets: Route
Aliases: Destination, Route

Required: True
Position: 0
Default value: None
Accept pipeline input: True (ByValue)
Accept wildcard characters: False

-Session

An existing ADS session to use for communication.

Type: ISession
Parameter Sets: Session
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: True (ByValue)
Accept wildcard characters: False

-Timeout

The communication ADS timeout in milliseconds. A value of 0 disables the timeout. Default is 5000 ms.

Type: Int32
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: -1
Accept pipeline input: False
Accept wildcard characters: False

-Module

The MDP module type that owns the service transfer operation (e.g. NIC, UserManagement, TwinCAT, Firewall). Use Get-MdpModules -ServiceObjects to discover which module types support service transfer operations.

Possible values: Generic, AccessControl, NIC, Time, UserManagement, RAS, FTP, SMB, TwinCAT, Datastore, Software, CPU, Memory, Firewall, FileSystemObject, PLC, DisplayDevice, EWF, FBWF, SiliconDrive, OS, Raid, Fan, Mainboard, DiskManagement, UPS, PhysicalDrive, MassStorage, UWF, IO, Misc

Type: MdpModuleType
Parameter Sets: (All)
Aliases:
Accepted values: Generic, AccessControl, NIC, Time, UserManagement, RAS, FTP, SMB, TwinCAT, Datastore, Software, CPU, Memory, Firewall, FileSystemObject, PLC, DisplayDevice, EWF, FBWF, SiliconDrive, OS, Raid, Fan, Mainboard, DiskManagement, UPS, PhysicalDrive, MassStorage, UWF, IO, Misc

Required: True
Position: Named
Default value: Generic
Accept pipeline input: False
Accept wildcard characters: False

-MethodName

The method name of the service transfer operation to execute (e.g. AddUser, ApplyNetworkSettings, Reboot). Tab completion: Completes available method names based on the specified -Module parameter.

Type: String
Parameter Sets: (All)
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Value

The input data for the service transfer operation. Accepts multiple input formats depending on the operation's complexity:

  • String - For single-field operations (mkdir, Dir, GetFile, WriteFile, DeleteFile, DelRoute, DelShare). The string is the path or name.
  • Hashtable - For multi-field operations. Keys must match the DTO constructor parameter names (case-insensitive). Example: @{ SourcePath = "src.txt"; DestinationPath = "dst.txt"; Flags = 1 }
  • IMdpTransferInput DTO - A pre-constructed typed DTO object (e.g. [TwinCAT.Mdp.FsoCopyFileInput]::new("src.txt", "dst.txt", 1)).
  • JSON string - A JSON object string starting with '{'. Parsed and mapped to the DTO constructor parameters. Example: '{"SourcePath":"src.txt","DestinationPath":"dst.txt","Flags":1}' Use Get-MdpModules -ServiceObjects to discover available operations and their expected input types.
Type: Object
Parameter Sets: (All)
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-PollingRate

The polling interval in milliseconds for checking the operation status. Default is 250 ms. Set to 0 for fire-and-forget mode (the trigger is sent but the cmdlet does not wait for completion).

Type: Int32
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: 250
Accept pipeline input: False
Accept wildcard characters: False

-OperationTimeout

The maximum time in seconds to wait for the operation to complete. Default is 30 seconds. Set to 0 for fire-and-forget mode (the trigger is sent but the cmdlet does not wait for completion).

Type: Int32
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: 30
Accept pipeline input: False
Accept wildcard characters: False

-Quiet

Suppresses the confirmation prompt and executes the operation without further user interaction.

Type: SwitchParameter
Parameter Sets: (All)
Aliases: Silent

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-Confirm

Prompts you for confirmation before running the cmdlet.

Type: SwitchParameter
Parameter Sets: (All)
Aliases: cf

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.

Type: SwitchParameter
Parameter Sets: (All)
Aliases: wi

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

TwinCAT.IRoute

TwinCAT.ISession

OUTPUTS

NOTES