Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Introduce a conceptual help topic about calling external programs (native applications)

Open
  • Is something wrong?
#5,152 6 comments 8 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
48/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Stale
Tech stack
powershell
Domain
documentation

Research direction

Start by reviewing about_Parsing, about_Quoting_Rules, about_Redirection, about_Pipelines, about_pwsh, and about_Operators, along with the related issues and RFC. Draft the proposed about_Native_Calls topic for the about_* section, covering the listed native-program behavior and linking those articles; done means the comprehensive guidance is added and included in the TOC.

Written by the indexing model from the issue text.

Description

area-about area-conceptual area-native-cmds issue-doc-idea

Related: #2361, https://github.com/PowerShell/PowerShell/issues/13068#issuecomment-653526374, and #6239

Summary of the new document or enhancement

Many special considerations apply when you call an external command-line executable (aka native application / utility), which aren't currently covered comprehensively, in one place:

  • That the only data type supported is text ([string]), both on input and output, and how raw byte data is fundamentally unsupported - both when collecting the output in PowerShell and when piping between native programs.

    • Update: v7.4 introduced raw byte support.

  • How there are syntax pitfalls due to PowerShell's extended set of metacharacters (compared to other shells) causing potential misinterpretation of arguments, which must be avoided with quoting (e.g., To pass literal @foo, which works unquoted in cmd.exe and bash, you must use '@foo' in PowerShell).

    • How --% can be used (primarily on Windows) to selectively deactivate PowerShell's parsing.

  • How "native globbing" is automatically applied to arguments such as *.txt on Unix-like platforms; that is, *.txt is implicitly replaced with the array of file names / paths matching that wildcard pattern.

  • How output data is sent through the pipeline line by line, resulting in an array of strings (lines), if collected in a variable.

  • How stderr (standard error) output is passed through to the host rather than going through PowerShell's error stream and can only be captured with a 2> redirection.

  • How redirections (>) generally do not pass the native program's output through as-is, but invariably treat it as [Console]::OutputEncoding encoded text that on writing to the target file is written with PowerShell's default encoding (BOM-less UTF-8 in PowerShell 6+, UTF-16LE in Windows PowerShell).

  • How external-program calls aren't integrated with PowerShell's error handling and require explicit checking of $? / $LASTEXITCODE to detect failure, except in PowerShell 7, where pipeline chain operators && and || can now be used. See also: the RFC that proposes improvements to the integration.

  • How &, the call operator, must be used to invoke executables whose paths are / must be quoted (as a whole) and/or contain variable references or subexpressions (this requirement isn't specific to external programs, but most likely to surface in that context).

  • How Start-Process is typically not the right tool for invoking external programs - see #6239.

Details of requested document:

  • Proposed title: about_Native_Calls
  • Propose location in the TOC: Among the `about_* topics
  • Target audience: end users
  • Purpose or scenario: guidance for invoking native command-line programs
  • List of related articles to link to: about_Parsing, about_Quoting_Rules, about_Redirection, about_Pipelines, about_pwsh, about_Operators (section "Pipeline chain operators && and ||")
Dominant language
PowerShell
Stars
2.6k
Forks
1.7k
Avg merge
10h 10m
Merged PRs (30d)
21

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from MicrosoftDocs/PowerShell-Docs

All issues in MicrosoftDocs/PowerShell-Docs

Similar issues

More Documentation issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.