Mention ExternalException for Set-Clipboard

[tylermontneyacc]

Prerequisites

• Existing Issue: Search the existing issues for this repository. If there is an issue that fits your needs do not file a new one. Subscribe, react, or comment on that issue instead.
• Descriptive Title: Write the title for this issue as a short synopsis. If possible, provide context. For example, "Typo in Get-Foo cmdlet" instead of "Typo."
• Verify Version: If there is a mismatch between documentation and the behavior on your system, ensure that the version you are using is the same as the documentation. Check this box if they match or the issue you are reporting is not version specific.

Links

• https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.management/set-clipboard?view=powershell-5.1

Summary

As this cmdlet is likely wrapping Clipboard.SetDataObject, the user may run into the clipboard being in-use.

Details

None.

Suggested Fix

The notes section should include this scenario and instruct the user to retry after a short period.

[sdwheeler]

The clipboard code is not using the .NET System.Windows.Forms.Clipboard class. On Windows it is using the Win32 SetClipboardData API.

On non-Windows, it's using native command line tools (xclip on Linux, pbcopy on macOS).

On all platforms, failures are silently ignored.

[tylermontneyacc]

The clipboard code is not using the .NET System.Windows.Forms.Clipboard class. On Windows it is using the Win32 SetClipboardData API.

Appreciate the clarification.

On all platforms, failures are silently ignored.

What does this mean? The user will see no output a failure occurred?

[sdwheeler]

What does this mean? The user will see no output a failure occurred?

Correct, if the API call or the native command fails to set the clipboard, no error is returned.

[tylermontneyacc]

If the clipboard is in-use, an error is returned:

Set-Clipboard : Requested Clipboard operation did not succeed.
At line:2 char:1
+ Set-Clipboard "abc"
+ ~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : NotSpecified: (:) [Set-Clipboard], ExternalException
    + FullyQualifiedErrorId : System.Runtime.InteropServices.ExternalException,Microsoft.PowerShell.Commands.SetClipbo
   ardCommand

This may be a PS5.1 issue. I cannot seem to replicate it in PS7+. Perhaps a separate issue, not informing the user of failure seems undesirable. (I have corrected my initial post to reflect.)

[sdwheeler]

Yeah, that is a 5.1 behavior that won't be changed. In PowerShell 7+ there are no exceptions defined.

[tylermontneyacc]

Right, hence the request to mention the behavior for 5.1's notes. Is this request still denied?

[sdwheeler]

Perhaps a separate issue, not informing the user of failure seems undesirable. (I have corrected my initial post to reflect.)

If you can reproduce a failure scenario in PowerShell 7, you should file an issue with the PowerShell team.

What are the steps to reproduce the problem in Windows PowerShell 5.1?

[tylermontneyacc]

Run this (crude) block in a few 5.1 tabs (Terminal) and you will eventually see failures:

for($i=0;$i -lt 999;$i++){
   Set-Clipboard "abc"
   Start-Sleep -Milliseconds 100
}

Since Windows is using the Win32 call for 7, it will fail the same. However, since there are no exceptions you won't know.

[sdwheeler]

After much internal digging, I see that Windows PowerShell 5.1 is using the System.Windows.Forms.Clipboard class.

PowerShell 7 is using the Win32 API directly, which likely won't have the issue because they open and close the clipboard. See Clipboard.cs#L180-L186.

I am still considering whether to add a note for 5.1.