{"id":19505819,"url":"https://github.com/joshooaj/bgprocess","last_synced_at":"2026-03-12T03:32:35.573Z","repository":{"id":144163758,"uuid":"595867715","full_name":"joshooaj/BGProcess","owner":"joshooaj","description":"Start a process and asynchronously access the STDIO streams","archived":false,"fork":false,"pushed_at":"2023-02-02T21:50:07.000Z","size":1316,"stargazers_count":5,"open_issues_count":1,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-10-31T04:38:52.862Z","etag":null,"topics":["powershell","process","stdio"],"latest_commit_sha":null,"homepage":"https://www.joshooaj.com/BGProcess","language":"PowerShell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joshooaj.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-02-01T00:59:26.000Z","updated_at":"2025-08-12T19:38:17.000Z","dependencies_parsed_at":null,"dependency_job_id":"3d3a8fe2-a1ac-4b22-8f7d-66ea43caeca8","html_url":"https://github.com/joshooaj/BGProcess","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/joshooaj/BGProcess","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshooaj%2FBGProcess","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshooaj%2FBGProcess/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshooaj%2FBGProcess/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshooaj%2FBGProcess/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joshooaj","download_url":"https://codeload.github.com/joshooaj/BGProcess/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshooaj%2FBGProcess/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30414317,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-12T00:40:14.898Z","status":"online","status_checked_at":"2026-03-12T02:00:07.260Z","response_time":114,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["powershell","process","stdio"],"created_at":"2024-11-10T22:34:19.277Z","updated_at":"2026-03-12T03:32:35.558Z","avatar_url":"https://github.com/joshooaj.png","language":"PowerShell","readme":"# Welcome\n[![Publish](https://github.com/joshooaj/BGProcess/actions/workflows/Publish.yml/badge.svg)](https://github.com/joshooaj/BGProcess/actions/workflows/Publish.yml)\n[![PublishDocs](https://github.com/joshooaj/BGProcess/actions/workflows/PublishDocs.yml/badge.svg)](https://github.com/joshooaj/BGProcess/actions/workflows/PublishDocs.yml)\n## Introduction\n\nIt can be complicated to read from the StandardOutput or StandardError streams\non a [`[System.Diagnostics.Process]`](https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.process?view=net-7.0) object - especially without the risk of\nblocking the terminal indefinitely.\n\nThis module is intended to simplify reading the output of a running process,\nand reacting to it by writing to the StandardInput stream. Imagine for example\nthat you are required to use a command-line utility which cannot be executed\nwith simple command-line arguments. Instead, the utility prompts you to fill in\none or more pieces of information. Reading from StandardOutput synchronously\ncan result in locking up your PowerShell session if you call a `Read` method\nand there is no data to be read from the stream yet.\n\nWhen you use the `Start-BGProcess` cmdlet, the process is started and both\nStandardOutput and StandardError streams are monitored asynchronously. When you\nuse `Read-BGProcess`, any data available from these streams will be returned\nwithout blocking. Combine this with `Write-BGProcess` and you can easily\nautomate a stubborn command-line tool that is not automation-ready.\n\n## Installation\n\nThe module can be installed from [PowerShell Gallery](https://www.powershellgallery.com/packages/BGProcess)\nby running the command `Install-Module -Name BGProcess`.\n\nTo install manually, you can download latest `BGProcess.zip` file from the\n[Releases](https://github.com/joshooaj/BGProcess/releases) section, and extract\nit to one of your PSModulePath's.\n\nType `$env:PSModulePath -split ';'` in a PowerShell terminal to see where\nPowerShell looks for modules on your system.\n\nWhen extracted to a standard module path, the full path to `BGProcess.psd1`\nshould be similar to...\n\n- __Current user:__ C:\\Users\\\u003cusername\u003e\\Documents\\WindowsPowerShell\\Modules\\BGProcess\\0.1.0\\BGProcess.psd1\n- __All users:__ C:\\Program Files\\WindowsPowerShell\\Modules\\BGProcess\\0.1.0\\BGProcess.psd1\n\n## Usage\n\nI can't think of a good reason to use `nslookup.exe` this way, but it is used\nas an example because it is readily available on any Windows system and if you\nlaunch it without arguments it will present you with a prompt.\n\nHere's a simple use case - see the screenshot below to see what it looks like\nin the terminal. In a more complex scenario you would inspect the response from\n`Read-BGProcess` and either wait for some particular string, or branch out and\nperform different actions depending on the content.\n\n```powershell linenums=\"1\"\n$nslookup = Start-BGProcess nslookup # (1)\n$nslookup | Read-BGProcess -Wait -MapErrorsToStdOut # (2)\n$nslookup | Write-BGProcess \"www.powershellgallery.com\" -PassThru | Read-BGProcess -Wait -Timeout (New-TimeSpan -Seconds 3) -MapErrorsToStdOut # (3)\n$nslookup | Write-BGProcess \"exit\" | Wait-BGProcess # (4)\n$nslookup | Format-List # (5)\n```\n\n1. Launches a windowless nslookup `[System.Diagnostics.Process]` and\n   encapsulates it in a [BGProcess] class which takes care of monitoring\n   stdout/stderr for you.\n2. Reads any data available on stdout and stderr. The `-MapErrorsToStdOut`\n   switch is used here because nslookup writes \"Non-authoritative answer:\" to\n   stderr and I'd rather see that as part of stdout. Also, since processes\n   don't always write output all at once, there's a default timeout of 1 second\n   before `Read-BGProcess` assumes there is no more data to be read.\n3. Writes a DNS name to the StandardInput stream, and then waits until the\n   process output has been idle for 3 seconds before returning control.\n4. Writes \"exit\" to StandardInput, and waits until the `nslookup.exe` process\n   exits.\n5. Writes the `$nslookup` `[BGProcess]` object to the terminal.\n\n![Screenshot of PowerShell terminal showing nslookup output](images/example1.png)\n\n## Known issues\n\n- When an application writes to both StandardOutput and StandardError, there is\n  no preservation of order for the output. The StandardError stream is written\n  out from `Read-BGProcess` before the StandardOutput stream, so even if the\n  text in the StandardError stream was written at the very end, it will be\n  output first. This might be mitigated by switching from reading from the\n  StandardOutput and StandardError BaseStreams to subscribing to the\n  [OutputDataReceived](https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.process.outputdatareceived?view=net-7.0) and [ErrorDataReceived](https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.process.errordatareceived?view=net-7.0) events. In theory, these events\n  should be fired in order, and then it should be easy to maintain the output\n  order. It may also reduce complexity by eliminating the need for runspaces.\n- On linux, it does not appear that the [Exited](https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.process.exited?view=net-7.0)\n  event handler gets called, so the `ExitCode` and `HasExited` properties do not\n  seem to be updated automatically. Something to look into.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoshooaj%2Fbgprocess","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoshooaj%2Fbgprocess","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoshooaj%2Fbgprocess/lists"}