From cb44c72763efb87ae98bb64a7dcb82c369910c7c Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 20 Nov 2025 15:28:46 -0600 Subject: [PATCH 1/2] Retire PS SDK Programmers Guide --- .openpublishing.publish.config.json | 7 +- redir/.openpublishing.redirection.json | 165 ---- redir/.openpublishing.redirection.sdk.json | 444 +++++++++++ ...d-verbs-for-windows-powershell-commands.md | 2 - ...reating-a-cmdlet-to-access-a-data-store.md | 419 ++++++---- ...ing-a-custom-windows-powershell-snap-in.md | 24 +- .../accessdbprovidersample01-code-sample.md | 31 - .../accessdbprovidersample02-code-sample.md | 30 - .../accessdbprovidersample03-code-sample.md | 29 - .../accessdbprovidersample04-code-sample.md | 21 - .../accessdbprovidersample05-code-sample.md | 20 - .../accessdbprovidersample06-code-sample.md | 29 - ...ing-a-basic-windows-powershell-provider.md | 164 ---- ...a-windows-powershell-container-provider.md | 717 ------------------ ...g-a-windows-powershell-content-provider.md | 414 ---------- ...ing-a-windows-powershell-drive-provider.md | 235 ------ ...ting-a-windows-powershell-item-provider.md | 491 ------------ ...-windows-powershell-navigation-provider.md | 447 ----------- ...-a-windows-powershell-property-provider.md | 289 ------- ...igning-your-windows-powershell-provider.md | 242 ------ .../prog-guide/getproc01-code-samples.md | 21 - .../getproc01-csharp-sample-code.md | 28 - .../getproc01-vb-net-sample-code.md | 23 - .../prog-guide/getproc02-code-samples.md | 26 - .../getproc02-csharp-sample-code.md | 20 - .../getproc02-vb-net-sample-code.md | 20 - .../prog-guide/getproc03-code-samples.md | 26 - .../getproc03-csharp-sample-code.md | 29 - .../getproc03-vb-net-sample-code.md | 16 - .../prog-guide/getproc04-code-samples.md | 26 - .../getproc04-csharp-sample-code.md | 28 - .../getproc04-vb-net-sample-code.md | 23 - .../prog-guide/getproc05-code-samples.md | 20 - .../getproc05-csharp-sample-code.md | 14 - .../getproc05-vb-net-sample-code.md | 427 ----------- ...to-create-a-windows-powershell-provider.md | 72 -- .../prog-guide/runspace01-code-samples.md | 21 - .../runspace01-csharp-code-sample.md | 29 - .../runspace01-vb-net-code-sample.md | 64 -- .../prog-guide/runspace02-code-samples.md | 19 - .../runspace02-csharp-code-sample.md | 19 - .../runspace02-vb-net-code-sample.md | 79 -- .../prog-guide/runspace03-code-samples.md | 30 - .../runspace03-csharp-code-sample.md | 31 - .../runspace03-vb-net-code-sample.md | 109 --- .../prog-guide/runspace04-code-samples.md | 28 - .../runspace04-vb-net-code-sample.md | 110 --- .../prog-guide/runspace05-code-sample.md | 29 - .../prog-guide/runspace06-code-sample.md | 30 - .../prog-guide/runspace07-code-sample.md | 29 - .../prog-guide/runspace08-code-sample.md | 20 - .../prog-guide/runspace09-code-sample.md | 18 - .../prog-guide/runspace10-code-sample.md | 27 - .../prog-guide/stopproc01-code-samples.md | 23 - .../stopproc01-csharp-sample-code.md | 23 - .../stopprocesssample04-code-samples.md | 26 - .../stopprocesssample04-csharp-sample-code.md | 27 - .../stopprocesssample04-vb-net-sample-code.md | 472 ------------ .../prog-guide/windows-powershell-concepts.md | 37 - .../windows-powershell-programmer-s-guide.md | 157 ---- .../windows-powershell-sample-code.md | 50 -- reference/docs-conceptual/developer/toc.yml | 126 --- 62 files changed, 726 insertions(+), 5946 deletions(-) create mode 100644 redir/.openpublishing.redirection.sdk.json delete mode 100644 reference/docs-conceptual/developer/prog-guide/accessdbprovidersample01-code-sample.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/accessdbprovidersample02-code-sample.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/accessdbprovidersample03-code-sample.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/accessdbprovidersample04-code-sample.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/accessdbprovidersample05-code-sample.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/accessdbprovidersample06-code-sample.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/creating-a-basic-windows-powershell-provider.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/creating-a-windows-powershell-container-provider.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/creating-a-windows-powershell-content-provider.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/creating-a-windows-powershell-drive-provider.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/creating-a-windows-powershell-item-provider.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/creating-a-windows-powershell-navigation-provider.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/creating-a-windows-powershell-property-provider.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/designing-your-windows-powershell-provider.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/getproc01-code-samples.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/getproc01-csharp-sample-code.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/getproc01-vb-net-sample-code.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/getproc02-code-samples.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/getproc02-csharp-sample-code.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/getproc02-vb-net-sample-code.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/getproc03-code-samples.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/getproc03-csharp-sample-code.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/getproc03-vb-net-sample-code.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/getproc04-code-samples.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/getproc04-csharp-sample-code.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/getproc04-vb-net-sample-code.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/getproc05-code-samples.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/getproc05-csharp-sample-code.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/getproc05-vb-net-sample-code.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/how-to-create-a-windows-powershell-provider.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/runspace01-code-samples.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/runspace01-csharp-code-sample.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/runspace01-vb-net-code-sample.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/runspace02-code-samples.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/runspace02-csharp-code-sample.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/runspace02-vb-net-code-sample.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/runspace03-code-samples.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/runspace03-csharp-code-sample.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/runspace03-vb-net-code-sample.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/runspace04-code-samples.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/runspace04-vb-net-code-sample.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/runspace05-code-sample.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/runspace06-code-sample.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/runspace07-code-sample.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/runspace08-code-sample.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/runspace09-code-sample.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/runspace10-code-sample.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/stopproc01-code-samples.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/stopproc01-csharp-sample-code.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/stopprocesssample04-code-samples.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/stopprocesssample04-csharp-sample-code.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/stopprocesssample04-vb-net-sample-code.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/windows-powershell-concepts.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/windows-powershell-programmer-s-guide.md delete mode 100644 reference/docs-conceptual/developer/prog-guide/windows-powershell-sample-code.md diff --git a/.openpublishing.publish.config.json b/.openpublishing.publish.config.json index 2cfecf73f826..fd2ea38c768e 100644 --- a/.openpublishing.publish.config.json +++ b/.openpublishing.publish.config.json @@ -18,12 +18,6 @@ "path_to_root": "_themes", "url": "https://github.com/Microsoft/templates.docs.msft" }, - { - "branch": "main", - "branch_mapping": {}, - "path_to_root": "powershell-sdk-samples", - "url": "https://github.com/MicrosoftDocs/powershell-sdk-samples" - }, { "branch": "master", "path_to_root": "_themes.pdf", @@ -78,6 +72,7 @@ "redir/.openpublishing.redirection.dsc.json", "redir/.openpublishing.redirection.gallery.json", "redir/.openpublishing.redirection.psget.json", + "redir/.openpublishing.redirection.sdk.json", "redir/.openpublishing.redirection.virtual.json", "redir/.openpublishing.redirection.wmf.json" ], diff --git a/redir/.openpublishing.redirection.json b/redir/.openpublishing.redirection.json index 11a6b20b5a79..c1a1a161abae 100644 --- a/redir/.openpublishing.redirection.json +++ b/redir/.openpublishing.redirection.json @@ -205,11 +205,6 @@ "redirect_url": "/powershell/scripting/install/powershell-on-arm", "source_path": "../reference/docs-conceptual/install/PowerShell-Core-on-Arm.md" }, - { - "redirect_document_id": false, - "redirect_url": "/powershell/module/microsoft.powershell.core/about/about_psmodulepath", - "source_path": "../reference/docs-conceptual/developer/module/modifying-the-psmodulepath-installation-path.md" - }, { "redirect_document_id": false, "redirect_url": "/powershell/module/microsoft.powershell.core/about/about_Tab_Expansion", @@ -290,11 +285,6 @@ "redirect_url": "/powershell/scripting/community/2020-update", "source_path": "../reference/docs-conceptual/community/2020-Q4.md" }, - { - "redirect_document_id": false, - "redirect_url": "/powershell/scripting/developer/windows-powershell", - "source_path": "../reference/docs-conceptual/developer/index.md" - }, { "redirect_document_id": false, "redirect_url": "/powershell/scripting/windows-powershell/wmf/overview", @@ -390,31 +380,6 @@ "redirect_url": "/powershell/scripting/windows-powershell/whats-new/what-s-new-in-windows-powershell-50", "source_path": "../reference/docs-conceptual/whats-new/what-s-new-in-windows-powershell-50.md" }, - { - "redirect_document_id": false, - "redirect_url": "/powershell/scripting/developer/cmdlet/cmdlet-overview", - "source_path": "../reference/docs-conceptual/developer/cmdlet/writing-a-windows-powershell-cmdlet.md" - }, - { - "redirect_document_id": false, - "redirect_url": "/powershell/scripting/developer/format/wide-view-basic", - "source_path": "../reference/docs-conceptual/developer/format/examples-of-formatting-files.md" - }, - { - "redirect_document_id": false, - "redirect_url": "/powershell/scripting/developer/format/formatting-file-overview", - "source_path": "../reference/docs-conceptual/developer/format/writing-a-powershell-formatting-file.md" - }, - { - "redirect_document_id": false, - "redirect_url": "/powershell/scripting/developer/hosting/windows-powershell-host-quickstart", - "source_path": "../reference/docs-conceptual/developer/hosting/writing-a-windows-powershell-host-application.md" - }, - { - "redirect_document_id": false, - "redirect_url": "/powershell/scripting/developer/provider/windows-powershell-provider-quickstart", - "source_path": "../reference/docs-conceptual/developer/provider/writing-a-windows-powershell-provider.md" - }, { "redirect_document_id": false, "redirect_url": "/powershell/scripting/overview", @@ -670,126 +635,6 @@ "redirect_url": "/powershell/scripting/dev-cross-plat/vscode/using-vscode-for-remote-editing-and-debugging", "source_path": "../reference/docs-conceptual/components/vscode/using-vscode-for-remote-editing-and-debugging.md" }, - { - "redirect_document_id": false, - "redirect_url": "/powershell/scripting/developer/module/how-to-create-a-windows-powershell-snap-in", - "source_path": "../reference/docs-conceptual/developer/cmdlet/how-to-create-a-windows-powershell-snap-in.md" - }, - { - "redirect_document_id": false, - "redirect_url": "/powershell/scripting/developer/module/how-to-import-cmdlets-using-modules", - "source_path": "../reference/docs-conceptual/developer/cmdlet/how-to-import-cmdlets-using-modules.md" - }, - { - "redirect_document_id": false, - "redirect_url": "/powershell/scripting/developer/module/modules-and-snap-ins", - "source_path": "../reference/docs-conceptual/developer/cmdlet/modules-and-snap-ins.md" - }, - { - "redirect_document_id": false, - "redirect_url": "/powershell/scripting/developer/module/registering-cmdlets", - "source_path": "../reference/docs-conceptual/developer/cmdlet/registering-cmdlets.md" - }, - { - "redirect_document_id": false, - "redirect_url": "/powershell/scripting/developer/module/writing-a-custom-windows-powershell-snap-in", - "source_path": "../reference/docs-conceptual/developer/cmdlet/writing-a-custom-windows-powershell-snap-in.md" - }, - { - "redirect_document_id": false, - "redirect_url": "/powershell/scripting/developer/module/writing-a-windows-powershell-snap-in", - "source_path": "../reference/docs-conceptual/developer/cmdlet/writing-a-windows-powershell-snap-in.md" - }, - { - "redirect_document_id": false, - "redirect_url": "/powershell/scripting/developer/help/file-types-permitted-in-an-updatable-help-cab-file", - "source_path": "../reference/docs-conceptual/developer/module/file-types-permitted-in-an-updatable-help-cab-file.md" - }, - { - "redirect_document_id": false, - "redirect_url": "/powershell/scripting/developer/help/helpinfo-xml-sample-file", - "source_path": "../reference/docs-conceptual/developer/module/helpinfo-xml-sample-file.md" - }, - { - "redirect_document_id": false, - "redirect_url": "/powershell/scripting/developer/help/helpinfo-xml-schema", - "source_path": "../reference/docs-conceptual/developer/module/helpinfo-xml-schema.md" - }, - { - "redirect_document_id": false, - "redirect_url": "/powershell/scripting/developer/help/how-to-create-a-helpinfo-xml-file", - "source_path": "../reference/docs-conceptual/developer/module/how-to-create-a-helpinfo-xml-file.md" - }, - { - "redirect_document_id": false, - "redirect_url": "/powershell/scripting/developer/help/how-to-create-and-upload-cab-files", - "source_path": "../reference/docs-conceptual/developer/module/how-to-create-and-upload-cab-files.md" - }, - { - "redirect_document_id": false, - "redirect_url": "/powershell/scripting/developer/help/how-to-name-a-helpinfo-xml-file", - "source_path": "../reference/docs-conceptual/developer/module/how-to-name-a-helpinfo-xml-file.md" - }, - { - "redirect_document_id": false, - "redirect_url": "/powershell/scripting/developer/help/how-to-name-an-updatable-help-cab-file", - "source_path": "../reference/docs-conceptual/developer/module/how-to-name-an-updatable-help-cab-file.md" - }, - { - "redirect_document_id": false, - "redirect_url": "/powershell/scripting/developer/help/how-to-prepare-updatable-help-cab-files", - "source_path": "../reference/docs-conceptual/developer/module/how-to-prepare-updatable-help-cab-files.md" - }, - { - "redirect_document_id": false, - "redirect_url": "/powershell/scripting/developer/help/how-to-set-helpinfo-xml-version-numbers", - "source_path": "../reference/docs-conceptual/developer/module/how-to-set-helpinfo-xml-version-numbers.md" - }, - { - "redirect_document_id": false, - "redirect_url": "/powershell/scripting/developer/help/how-to-test-updatable-help", - "source_path": "../reference/docs-conceptual/developer/module/how-to-test-updatable-help.md" - }, - { - "redirect_document_id": false, - "redirect_url": "/powershell/scripting/developer/help/how-to-update-help-files", - "source_path": "../reference/docs-conceptual/developer/module/how-to-update-help-files.md" - }, - { - "redirect_document_id": false, - "redirect_url": "/powershell/scripting/developer/help/how-updatable-help-works", - "source_path": "../reference/docs-conceptual/developer/module/how-updatable-help-works.md" - }, - { - "redirect_document_id": false, - "redirect_url": "/powershell/scripting/developer/help/naming-help-files", - "source_path": "../reference/docs-conceptual/developer/module/naming-help-files.md" - }, - { - "redirect_document_id": false, - "redirect_url": "/powershell/scripting/developer/help/supporting-online-help", - "source_path": "../reference/docs-conceptual/developer/module/supporting-online-help.md" - }, - { - "redirect_document_id": false, - "redirect_url": "/powershell/scripting/developer/help/supporting-updatable-help", - "source_path": "../reference/docs-conceptual/developer/module/supporting-updatable-help.md" - }, - { - "redirect_document_id": false, - "redirect_url": "/powershell/scripting/developer/help/updatable-help-authoring-step-by-step", - "source_path": "../reference/docs-conceptual/developer/module/updatable-help-authoring-step-by-step.md" - }, - { - "redirect_document_id": false, - "redirect_url": "/powershell/scripting/developer/help/updatable-help-overview", - "source_path": "../reference/docs-conceptual/developer/module/updatable-help-overview.md" - }, - { - "redirect_document_id": false, - "redirect_url": "/powershell/scripting/developer/help/writing-help-for-windows-powershell-modules", - "source_path": "../reference/docs-conceptual/developer/module/writing-help-for-windows-powershell-modules.md" - }, { "redirect_document_id": false, "redirect_url": "/powershell/scripting/windows-powershell/starting-the-windows-powershell-2.0-engine", @@ -904,16 +749,6 @@ "redirect_document_id": false, "redirect_url": "/powershell/scripting/windows-powershell/wmf/whats-new/sil-overview", "source_path": "../reference/docs-conceptual/wmf/whats-new/sil-overview.md" - }, - { - "redirect_document_id": false, - "redirect_url": "/powershell/scripting/developer/cmdlet/requesting-confirmation-from-cmdlets", - "source_path": "../reference/docs-conceptual/developer/cmdlet/how-to-request-confirmations.md" - }, - { - "redirect_document_id": false, - "redirect_url": "/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", - "source_path": "../reference/docs-conceptual/developer/prog-guide/how-to-create-a-console-shell.md" } ] } diff --git a/redir/.openpublishing.redirection.sdk.json b/redir/.openpublishing.redirection.sdk.json new file mode 100644 index 000000000000..4a2365553db5 --- /dev/null +++ b/redir/.openpublishing.redirection.sdk.json @@ -0,0 +1,444 @@ +{ + "redirections": [ + { + "redirect_document_id": false, + "redirect_url": "/powershell/scripting/developer/windows-powershell", + "source_path": "../reference/docs-conceptual/developer/index.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/accessdbprovidersample01-code-sample.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/accessdbprovidersample02-code-sample.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/accessdbprovidersample03-code-sample.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/accessdbprovidersample04-code-sample.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/accessdbprovidersample05-code-sample.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/accessdbprovidersample06-code-sample.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/creating-a-basic-windows-powershell-provider.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/creating-a-windows-powershell-container-provider.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/creating-a-windows-powershell-content-provider.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/creating-a-windows-powershell-drive-provider.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/creating-a-windows-powershell-item-provider.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/creating-a-windows-powershell-navigation-provider.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/creating-a-windows-powershell-property-provider.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/designing-your-windows-powershell-provider.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/getproc01-code-samples.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/getproc01-csharp-sample-code.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/getproc01-vb-net-sample-code.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/getproc02-code-samples.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/getproc02-csharp-sample-code.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/getproc02-vb-net-sample-code.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/getproc03-code-samples.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/getproc03-csharp-sample-code.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/getproc03-vb-net-sample-code.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/getproc04-code-samples.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/getproc04-csharp-sample-code.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/getproc04-vb-net-sample-code.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/getproc05-code-samples.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/getproc05-csharp-sample-code.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/getproc05-vb-net-sample-code.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/how-to-create-a-windows-powershell-provider.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/runspace01-code-samples.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/runspace01-csharp-code-sample.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/runspace01-vb-net-code-sample.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/runspace02-code-samples.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/runspace02-csharp-code-sample.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/runspace02-vb-net-code-sample.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/runspace03-code-samples.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/runspace03-csharp-code-sample.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/runspace03-vb-net-code-sample.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/runspace04-code-samples.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/runspace04-vb-net-code-sample.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/runspace05-code-sample.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/runspace06-code-sample.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/runspace07-code-sample.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/runspace08-code-sample.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/runspace09-code-sample.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/runspace10-code-sample.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/stopproc01-code-samples.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/stopproc01-csharp-sample-code.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/stopprocesssample04-code-samples.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/stopprocesssample04-csharp-sample-code.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/stopprocesssample04-vb-net-sample-code.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/windows-powershell-concepts.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/windows-powershell-programmer-s-guide.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/previous-versions/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "reference/docs-conceptual/developer/prog-guide/windows-powershell-sample-code.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/powershell/module/microsoft.powershell.core/about/about_psmodulepath", + "source_path": "../reference/docs-conceptual/developer/module/modifying-the-psmodulepath-installation-path.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/powershell/scripting/developer/cmdlet/cmdlet-overview", + "source_path": "../reference/docs-conceptual/developer/cmdlet/writing-a-windows-powershell-cmdlet.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/powershell/scripting/developer/format/wide-view-basic", + "source_path": "../reference/docs-conceptual/developer/format/examples-of-formatting-files.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/powershell/scripting/developer/format/formatting-file-overview", + "source_path": "../reference/docs-conceptual/developer/format/writing-a-powershell-formatting-file.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/powershell/scripting/developer/hosting/windows-powershell-host-quickstart", + "source_path": "../reference/docs-conceptual/developer/hosting/writing-a-windows-powershell-host-application.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/powershell/scripting/developer/provider/windows-powershell-provider-quickstart", + "source_path": "../reference/docs-conceptual/developer/provider/writing-a-windows-powershell-provider.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/powershell/scripting/developer/module/how-to-create-a-windows-powershell-snap-in", + "source_path": "../reference/docs-conceptual/developer/cmdlet/how-to-create-a-windows-powershell-snap-in.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/powershell/scripting/developer/module/how-to-import-cmdlets-using-modules", + "source_path": "../reference/docs-conceptual/developer/cmdlet/how-to-import-cmdlets-using-modules.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/powershell/scripting/developer/module/modules-and-snap-ins", + "source_path": "../reference/docs-conceptual/developer/cmdlet/modules-and-snap-ins.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/powershell/scripting/developer/module/registering-cmdlets", + "source_path": "../reference/docs-conceptual/developer/cmdlet/registering-cmdlets.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/powershell/scripting/developer/module/writing-a-custom-windows-powershell-snap-in", + "source_path": "../reference/docs-conceptual/developer/cmdlet/writing-a-custom-windows-powershell-snap-in.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/powershell/scripting/developer/module/writing-a-windows-powershell-snap-in", + "source_path": "../reference/docs-conceptual/developer/cmdlet/writing-a-windows-powershell-snap-in.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/powershell/scripting/developer/help/file-types-permitted-in-an-updatable-help-cab-file", + "source_path": "../reference/docs-conceptual/developer/module/file-types-permitted-in-an-updatable-help-cab-file.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/powershell/scripting/developer/help/helpinfo-xml-sample-file", + "source_path": "../reference/docs-conceptual/developer/module/helpinfo-xml-sample-file.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/powershell/scripting/developer/help/helpinfo-xml-schema", + "source_path": "../reference/docs-conceptual/developer/module/helpinfo-xml-schema.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/powershell/scripting/developer/help/how-to-create-a-helpinfo-xml-file", + "source_path": "../reference/docs-conceptual/developer/module/how-to-create-a-helpinfo-xml-file.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/powershell/scripting/developer/help/how-to-create-and-upload-cab-files", + "source_path": "../reference/docs-conceptual/developer/module/how-to-create-and-upload-cab-files.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/powershell/scripting/developer/help/how-to-name-a-helpinfo-xml-file", + "source_path": "../reference/docs-conceptual/developer/module/how-to-name-a-helpinfo-xml-file.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/powershell/scripting/developer/help/how-to-name-an-updatable-help-cab-file", + "source_path": "../reference/docs-conceptual/developer/module/how-to-name-an-updatable-help-cab-file.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/powershell/scripting/developer/help/how-to-prepare-updatable-help-cab-files", + "source_path": "../reference/docs-conceptual/developer/module/how-to-prepare-updatable-help-cab-files.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/powershell/scripting/developer/help/how-to-set-helpinfo-xml-version-numbers", + "source_path": "../reference/docs-conceptual/developer/module/how-to-set-helpinfo-xml-version-numbers.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/powershell/scripting/developer/help/how-to-test-updatable-help", + "source_path": "../reference/docs-conceptual/developer/module/how-to-test-updatable-help.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/powershell/scripting/developer/help/how-to-update-help-files", + "source_path": "../reference/docs-conceptual/developer/module/how-to-update-help-files.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/powershell/scripting/developer/help/how-updatable-help-works", + "source_path": "../reference/docs-conceptual/developer/module/how-updatable-help-works.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/powershell/scripting/developer/help/naming-help-files", + "source_path": "../reference/docs-conceptual/developer/module/naming-help-files.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/powershell/scripting/developer/help/supporting-online-help", + "source_path": "../reference/docs-conceptual/developer/module/supporting-online-help.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/powershell/scripting/developer/help/supporting-updatable-help", + "source_path": "../reference/docs-conceptual/developer/module/supporting-updatable-help.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/powershell/scripting/developer/help/updatable-help-authoring-step-by-step", + "source_path": "../reference/docs-conceptual/developer/module/updatable-help-authoring-step-by-step.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/powershell/scripting/developer/help/updatable-help-overview", + "source_path": "../reference/docs-conceptual/developer/module/updatable-help-overview.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/powershell/scripting/developer/help/writing-help-for-windows-powershell-modules", + "source_path": "../reference/docs-conceptual/developer/module/writing-help-for-windows-powershell-modules.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/powershell/scripting/developer/cmdlet/requesting-confirmation-from-cmdlets", + "source_path": "../reference/docs-conceptual/developer/cmdlet/how-to-request-confirmations.md" + }, + { + "redirect_document_id": false, + "redirect_url": "/powershell/scripting/developer/prog-guide/windows-powershell-programmer-s-guide", + "source_path": "../reference/docs-conceptual/developer/prog-guide/how-to-create-a-console-shell.md" + } + ] +} diff --git a/reference/docs-conceptual/developer/cmdlet/approved-verbs-for-windows-powershell-commands.md b/reference/docs-conceptual/developer/cmdlet/approved-verbs-for-windows-powershell-commands.md index 408f7e4fc9cd..55bd02c0e859 100644 --- a/reference/docs-conceptual/developer/cmdlet/approved-verbs-for-windows-powershell-commands.md +++ b/reference/docs-conceptual/developer/cmdlet/approved-verbs-for-windows-powershell-commands.md @@ -252,11 +252,9 @@ lifecycle, or security verb names verbs. - [System.Management.Automation.VerbsSecurity][104] - [System.Management.Automation.VerbsOther][102] - [Cmdlet Declaration][03] -- [Windows PowerShell Programmer's Guide][01] - [Windows PowerShell Shell SDK][02] -[01]: ../prog-guide/windows-powershell-programmer-s-guide.md [02]: ../windows-powershell-reference.md [03]: ./cmdlet-class-declaration.md [04]: xref:System.Management.Automation.Host.BufferCellType diff --git a/reference/docs-conceptual/developer/cmdlet/creating-a-cmdlet-to-access-a-data-store.md b/reference/docs-conceptual/developer/cmdlet/creating-a-cmdlet-to-access-a-data-store.md index 922fd0877358..e6992c90c7fb 100644 --- a/reference/docs-conceptual/developer/cmdlet/creating-a-cmdlet-to-access-a-data-store.md +++ b/reference/docs-conceptual/developer/cmdlet/creating-a-cmdlet-to-access-a-data-store.md @@ -5,17 +5,34 @@ title: Creating a Cmdlet to Access a Data Store --- # Creating a Cmdlet to Access a Data Store -This section describes how to create a cmdlet that accesses stored data by way of a Windows PowerShell provider. This type of cmdlet uses the Windows PowerShell provider infrastructure of the Windows PowerShell runtime and, therefore, the cmdlet class must derive from the [System.Management.Automation.PSCmdlet](/dotnet/api/System.Management.Automation.PSCmdlet) base class. +This section describes how to create a cmdlet that accesses stored data by way of a Windows +PowerShell provider. This type of cmdlet uses the Windows PowerShell provider infrastructure of the +Windows PowerShell runtime and, therefore, the cmdlet class must derive from the +[System.Management.Automation.PSCmdlet][16] base class. -The Select-Str cmdlet described here can locate and select strings in a file or object. The patterns used to identify the string can be specified explicitly through the `Path` parameter of the cmdlet or implicitly through the `Script` parameter. +The Select-Str cmdlet described here can locate and select strings in a file or object. The patterns +used to identify the string can be specified explicitly through the `Path` parameter of the cmdlet +or implicitly through the `Script` parameter. -The cmdlet is designed to use any Windows PowerShell provider that derives from [System.Management.Automation.Provider.IContentCmdletProvider](/dotnet/api/System.Management.Automation.Provider.IContentCmdletProvider). For example, the cmdlet can specify the FileSystem provider or the Variable provider that is provided by Windows PowerShell. For more information aboutWindows PowerShell providers, see [Designing Your Windows PowerShell provider](../prog-guide/designing-your-windows-powershell-provider.md). +The cmdlet is designed to use any Windows PowerShell provider that derives from +[System.Management.Automation.Provider.IContentCmdletProvider][13]. For example, the cmdlet can +specify the FileSystem provider or the Variable provider that is provided by Windows PowerShell. For +more information aboutWindows PowerShell providers, see [Designing Your Windows PowerShell +provider][01]. ## Defining the Cmdlet Class -The first step in cmdlet creation is always naming the cmdlet and declaring the .NET class that implements the cmdlet. This cmdlet detects certain strings, so the verb name chosen here is "Select", defined by the [System.Management.Automation.VerbsCommon](/dotnet/api/System.Management.Automation.VerbsCommon) class. The noun name "Str" is used because the cmdlet acts upon strings. In the declaration below, note that the cmdlet verb and noun name are reflected in the name of the cmdlet class. For more information about approved cmdlet verbs, see [Cmdlet Verb Names](./approved-verbs-for-windows-powershell-commands.md). +The first step in cmdlet creation is always naming the cmdlet and declaring the .NET class that +implements the cmdlet. This cmdlet detects certain strings, so the verb name chosen here is +"Select", defined by the [System.Management.Automation.VerbsCommon][20] class. The noun name "Str" +is used because the cmdlet acts upon strings. In the declaration below, note that the cmdlet verb +and noun name are reflected in the name of the cmdlet class. For more information about approved +cmdlet verbs, see [Cmdlet Verb Names][05]. -The .NET class for this cmdlet must derive from the [System.Management.Automation.PSCmdlet](/dotnet/api/System.Management.Automation.PSCmdlet) base class, because it provides the support needed by the Windows PowerShell runtime to expose the Windows PowerShell provider infrastructure. Note that this cmdlet also makes use of the .NET Framework regular expressions classes, such as [System.Text.RegularExpressions.Regex](/dotnet/api/System.Text.RegularExpressions.Regex). +The .NET class for this cmdlet must derive from the [System.Management.Automation.PSCmdlet][16] base +class, because it provides the support needed by the Windows PowerShell runtime to expose the +Windows PowerShell provider infrastructure. Note that this cmdlet also makes use of the .NET +Framework regular expressions classes, such as [System.Text.RegularExpressions.Regex][21]. The following code is the class definition for this Select-Str cmdlet. @@ -24,18 +41,27 @@ The following code is the class definition for this Select-Str cmdlet. public class SelectStringCommand : PSCmdlet ``` -This cmdlet defines a default parameter set by adding the `DefaultParameterSetName` attribute keyword to the class declaration. The default parameter set `PatternParameterSet` is used when the `Script` parameter is not specified. For more information about this parameter set, see the `Pattern` and `Script` parameter discussion in the following section. +This cmdlet defines a default parameter set by adding the `DefaultParameterSetName` attribute +keyword to the class declaration. The default parameter set `PatternParameterSet` is used when the +`Script` parameter is not specified. For more information about this parameter set, see the +`Pattern` and `Script` parameter discussion in the following section. ## Defining Parameters for Data Access -This cmdlet defines several parameters that allow the user to access and examine stored data. These parameters include a `Path` parameter that indicates the location of the data store, a `Pattern` parameter that specifies the pattern to be used in the search, and several other parameters that support how the search is performed. +This cmdlet defines several parameters that allow the user to access and examine stored data. These +parameters include a `Path` parameter that indicates the location of the data store, a `Pattern` +parameter that specifies the pattern to be used in the search, and several other parameters that +support how the search is performed. > [!NOTE] -> For more information about the basics of defining parameters, see [Adding Parameters that Process Command Line Input](./adding-parameters-that-process-command-line-input.md). +> For more information about the basics of defining parameters, see [Adding Parameters that Process +> Command Line Input][04]. ### Declaring the Path Parameter -To locate the data store, this cmdlet must use a Windows PowerShell path to identify the Windows PowerShell provider that is designed to access the data store. Therefore, it defines a `Path` parameter of type string array to indicate the location of the provider. +To locate the data store, this cmdlet must use a Windows PowerShell path to identify the Windows +PowerShell provider that is designed to access the data store. Therefore, it defines a `Path` +parameter of type string array to indicate the location of the provider. ```csharp [Parameter( @@ -58,13 +84,21 @@ private string[] paths; Note that this parameter belongs to two different parameter sets and that it has an alias. -Two [System.Management.Automation.ParameterAttribute](/dotnet/api/System.Management.Automation.ParameterAttribute) attributes declare that the `Path` parameter belongs to the `ScriptParameterSet` and the `PatternParameterSet`. For more information about parameter sets, see [Adding Parameter Sets to a Cmdlet](./adding-parameter-sets-to-a-cmdlet.md). +Two [System.Management.Automation.ParameterAttribute][12] attributes declare that the `Path` +parameter belongs to the `ScriptParameterSet` and the `PatternParameterSet`. For more information +about parameter sets, see [Adding Parameter Sets to a Cmdlet][03]. -The [System.Management.Automation.AliasAttribute](/dotnet/api/System.Management.Automation.AliasAttribute) attribute declares a `PSPath` alias for the `Path` parameter. Declaring this alias is strongly recommended for consistency with other cmdlets that access Windows PowerShell providers. For more information aboutWindows PowerShell paths, see "PowerShell Path Concepts" in [How Windows PowerShell Works](/previous-versions//ms714658(v=vs.85)). +The [System.Management.Automation.AliasAttribute][08] attribute declares a `PSPath` alias for the +`Path` parameter. Declaring this alias is strongly recommended for consistency with other cmdlets +that access Windows PowerShell providers. For more information aboutWindows PowerShell paths, see +"PowerShell Path Concepts" in [How Windows PowerShell Works][24]. ### Declaring the Pattern Parameter -To specify the patterns to search for, this cmdlet declares a `Pattern` parameter that is an array of strings. A positive result is returned when any of the patterns are found in the data store. Note that these patterns can be compiled into an array of compiled regular expressions or an array of wildcard patterns used for literal searches. +To specify the patterns to search for, this cmdlet declares a `Pattern` parameter that is an array +of strings. A positive result is returned when any of the patterns are found in the data store. Note +that these patterns can be compiled into an array of compiled regular expressions or an array of +wildcard patterns used for literal searches. ```csharp [Parameter( @@ -81,13 +115,22 @@ private Regex[] regexPattern; private WildcardPattern[] wildcardPattern; ``` -When this parameter is specified, the cmdlet uses the default parameter set `PatternParameterSet`. In this case, the cmdlet uses the patterns specified here to select strings. In contrast, the `Script` parameter could also be used to provide a script that contains the patterns. The `Script` and `Pattern` parameters define two separate parameter sets, so they are mutually exclusive. +When this parameter is specified, the cmdlet uses the default parameter set `PatternParameterSet`. +In this case, the cmdlet uses the patterns specified here to select strings. In contrast, the +`Script` parameter could also be used to provide a script that contains the patterns. The `Script` +and `Pattern` parameters define two separate parameter sets, so they are mutually exclusive. ### Declaring Search Support Parameters -This cmdlet defines the following support parameters that can be used to modify the search capabilities of the cmdlet. +This cmdlet defines the following support parameters that can be used to modify the search +capabilities of the cmdlet. -The `Script` parameter specifies a script block that can be used to provide an alternate search mechanism for the cmdlet. The script must contain the patterns used for matching and return a [System.Management.Automation.PSObject](/dotnet/api/System.Management.Automation.PSObject) object. Note that this parameter is also the unique parameter that identifies the `ScriptParameterSet` parameter set. When the Windows PowerShell runtime sees this parameter, it uses only parameters that belong to the `ScriptParameterSet` parameter set. +The `Script` parameter specifies a script block that can be used to provide an alternate search +mechanism for the cmdlet. The script must contain the patterns used for matching and return a +[System.Management.Automation.PSObject][18] object. Note that this parameter is also the unique +parameter that identifies the `ScriptParameterSet` parameter set. When the Windows PowerShell +runtime sees this parameter, it uses only parameters that belong to the `ScriptParameterSet` +parameter set. ```csharp [Parameter( @@ -102,7 +145,10 @@ public ScriptBlock Script ScriptBlock script; ``` -The `SimpleMatch` parameter is a switch parameter that indicates whether the cmdlet is to explicitly match the patterns as they are supplied. When the user specifies the parameter at the command line (`true`), the cmdlet uses the patterns as they are supplied. If the parameter is not specified (`false`), the cmdlet uses regular expressions. The default for this parameter is `false`. +The `SimpleMatch` parameter is a switch parameter that indicates whether the cmdlet is to explicitly +match the patterns as they are supplied. When the user specifies the parameter at the command line +(`true`), the cmdlet uses the patterns as they are supplied. If the parameter is not specified +(`false`), the cmdlet uses regular expressions. The default for this parameter is `false`. ```csharp [Parameter] @@ -114,7 +160,12 @@ public SwitchParameter SimpleMatch private bool simpleMatch; ``` -The `CaseSensitive` parameter is a switch parameter that indicates whether a case-sensitive search is performed. When the user specifies the parameter at the command line (`true`), the cmdlet checks for the uppercase and lowercase of characters when comparing patterns. If the parameter is not specified (`false`), the cmdlet does not distinguish between uppercase and lowercase. For example "MyFile" and "myfile" would both be returned as positive hits. The default for this parameter is `false`. +The `CaseSensitive` parameter is a switch parameter that indicates whether a case-sensitive search +is performed. When the user specifies the parameter at the command line (`true`), the cmdlet checks +for the uppercase and lowercase of characters when comparing patterns. If the parameter is not +specified (`false`), the cmdlet does not distinguish between uppercase and lowercase. For example +"MyFile" and "myfile" would both be returned as positive hits. The default for this parameter is +`false`. ```csharp [Parameter] @@ -126,7 +177,10 @@ public SwitchParameter CaseSensitive private bool caseSensitive; ``` -The `Exclude` and `Include` parameters identify items that are explicitly excluded from or included in the search. By default, the cmdlet will search all items in the data store. However, to limit the search performed by the cmdlet, these parameters can be used to explicitly indicate items to be included in the search or omitted. +The `Exclude` and `Include` parameters identify items that are explicitly excluded from or included +in the search. By default, the cmdlet will search all items in the data store. However, to limit the +search performed by the cmdlet, these parameters can be used to explicitly indicate items to be +included in the search or omitted. ```csharp [Parameter] @@ -165,13 +219,21 @@ internal WildcardPattern[] include = null; ### Declaring Parameter Sets -This cmdlet uses two parameter sets (`ScriptParameterSet` and `PatternParameterSet`, which is the default) as the names of two parameter sets used in data access. `PatternParameterSet` is the default parameter set and is used when the `Pattern` parameter is specified. `ScriptParameterSet` is used when the user specifies an alternate search mechanism through the `Script` parameter. For more information about parameter sets, see [Adding Parameter Sets to a Cmdlet](./adding-parameter-sets-to-a-cmdlet.md). +This cmdlet uses two parameter sets (`ScriptParameterSet` and `PatternParameterSet`, which is the +default) as the names of two parameter sets used in data access. `PatternParameterSet` is the +default parameter set and is used when the `Pattern` parameter is specified. `ScriptParameterSet` is +used when the user specifies an alternate search mechanism through the `Script` parameter. For more +information about parameter sets, see [Adding Parameter Sets to a Cmdlet][03]. ## Overriding Input Processing Methods -Cmdlets must override one or more of the input processing methods for the [System.Management.Automation.PSCmdlet](/dotnet/api/System.Management.Automation.PSCmdlet) class. For more information about the input processing methods, see [Creating Your First Cmdlet](./creating-a-cmdlet-without-parameters.md). +Cmdlets must override one or more of the input processing methods for the +[System.Management.Automation.PSCmdlet][16] class. For more information about the input processing +methods, see [Creating Your First Cmdlet][07]. -This cmdlet overrides the [System.Management.Automation.Cmdlet.BeginProcessing](/dotnet/api/System.Management.Automation.Cmdlet.BeginProcessing) method to build an array of compiled regular expressions at startup. This increases performance during searches that do not use simple matching. +This cmdlet overrides the [System.Management.Automation.Cmdlet.BeginProcessing][09] method to build +an array of compiled regular expressions at startup. This increases performance during searches that +do not use simple matching. ```csharp protected override void BeginProcessing() @@ -250,7 +312,9 @@ protected override void BeginProcessing() }// End of function BeginProcessing(). ``` -This cmdlet also overrides the [System.Management.Automation.Cmdlet.ProcessRecord](/dotnet/api/System.Management.Automation.Cmdlet.ProcessRecord) method to process the string selections that the user makes on the command line. It writes the results of string selection in the form of a custom object by calling a private **MatchString** method. +This cmdlet also overrides the [System.Management.Automation.Cmdlet.ProcessRecord][10] method to +process the string selections that the user makes on the command line. It writes the results of +string selection in the form of a custom object by calling a private **MatchString** method. ```csharp protected override void ProcessRecord() @@ -361,13 +425,24 @@ protected override void ProcessRecord() ## Accessing Content -Your cmdlet must open the provider indicated by the Windows PowerShell path so that it can access the data. The [System.Management.Automation.SessionState](/dotnet/api/System.Management.Automation.SessionState) object for the runspace is used for access to the provider, while the [System.Management.Automation.PSCmdlet.InvokeProvider*](/dotnet/api/System.Management.Automation.PSCmdlet.InvokeProvider) property of the cmdlet is used to open the provider. Access to content is provided by retrieval of the [System.Management.Automation.ProviderIntrinsics](/dotnet/api/System.Management.Automation.ProviderIntrinsics) object for the provider opened. +Your cmdlet must open the provider indicated by the Windows PowerShell path so that it can access +the data. The [System.Management.Automation.SessionState][19] object for the runspace is used for +access to the provider, while the [System.Management.Automation.PSCmdlet.InvokeProvider*][17] +property of the cmdlet is used to open the provider. Access to content is provided by retrieval of +the [System.Management.Automation.ProviderIntrinsics][14] object for the provider opened. -This sample Select-Str cmdlet uses the [System.Management.Automation.ProviderIntrinsics.Content*](/dotnet/api/System.Management.Automation.ProviderIntrinsics.Content) property to expose the content to scan. It can then call the [System.Management.Automation.ContentCmdletProviderIntrinsics.GetReader*](/dotnet/api/System.Management.Automation.ContentCmdletProviderIntrinsics.GetReader) method, passing the required Windows PowerShell path. +This sample Select-Str cmdlet uses the +[System.Management.Automation.ProviderIntrinsics.Content*][15] property to expose the content to +scan. It can then call the +[System.Management.Automation.ContentCmdletProviderIntrinsics.GetReader*][11] method, passing the +required Windows PowerShell path. ## Code Sample -The following code shows the implementation of this version of this Select-Str cmdlet. Note that this code includes the cmdlet class, private methods used by the cmdlet, and the Windows PowerShell snap-in code used to register the cmdlet. For more information about registering the cmdlet, see [Building the Cmdlet](#defining-the-cmdlet-class). +The following code shows the implementation of this version of this Select-Str cmdlet. Note that +this code includes the cmdlet class, private methods used by the cmdlet, and the Windows PowerShell +snap-in code used to register the cmdlet. For more information about registering the cmdlet, see +[Building the Cmdlet][25]. ```csharp // @@ -1078,140 +1153,178 @@ namespace Microsoft.Samples.PowerShell.Commands ## Building the Cmdlet -After implementing a cmdlet, you must register it with Windows PowerShell through a Windows PowerShell snap-in. For more information about registering cmdlets, see [How to Register Cmdlets, Providers, and Host Applications](/previous-versions//ms714644(v=vs.85)). +After implementing a cmdlet, you must register it with Windows PowerShell through a Windows +PowerShell snap-in. For more information about registering cmdlets, see [How to Register Cmdlets, +Providers, and Host Applications][23]. ## Testing the Cmdlet -When your cmdlet has been registered with Windows PowerShell, you can test it by running it on the command line. The following procedure can be used to test the sample Select-Str cmdlet. - -1. Start Windows PowerShell, and search the Notes file for occurrences of lines with the expression ".NET". Note that the quotation marks around the name of the path are required only if the path consists of more than one word. - - ```powershell - Select-Str -Path "notes" -Pattern ".NET" -SimpleMatch=$false - ``` - - The following output appears. - - ```output - IgnoreCase : True - LineNumber : 8 - Line : Because Windows PowerShell works directly with .NET objects, there is often a .NET object - Path : C:\PowerShell-Progs\workspace\Samples\SelectStr\notes - Pattern : .NET - IgnoreCase : True - LineNumber : 21 - Line : You should normally define the class for a cmdlet in a .NET namespace - Path : C:\PowerShell-Progs\workspace\Samples\SelectStr\notes - Pattern : .NET - ``` - -2. Search the Notes file for occurrences of lines with the word "over", followed by any other text. The `SimpleMatch` parameter is using the default value of `false`. The search is case-insensitive because the `CaseSensitive` parameter is set to `false`. - - ```powershell - Select-Str -Path notes -Pattern "over*" -SimpleMatch -CaseSensitive:$false - ``` - - The following output appears. - - ```output - IgnoreCase : True - LineNumber : 45 - Line : Override StopProcessing - Path : C:\PowerShell-Progs\workspace\Samples\SelectStr\notes - Pattern : over* - IgnoreCase : True - LineNumber : 49 - Line : overriding the StopProcessing method - Path : C:\PowerShell-Progs\workspace\Samples\SelectStr\notes - Pattern : over* - ``` - -3. Search the Notes file using a regular expression as the pattern. The cmdlet searches for alphabetical characters and blank spaces enclosed in parentheses. - - ```powershell - Select-Str -Path notes -Pattern "\([A-Za-z:blank:]" -SimpleMatch:$false - ``` - - The following output appears. - - ```output - IgnoreCase : True - LineNumber : 1 - Line : Advisory Guidelines (Consider Following) - Path : C:\PowerShell-Progs\workspace\Samples\SelectStr\notes - Pattern : \([A-Za-z:blank:] - IgnoreCase : True - LineNumber : 53 - Line : If your cmdlet has objects that are not disposed of (written to the pipeline) - Path : C:\PowerShell-Progs\workspace\Samples\SelectStr\notes - Pattern : \([A-Za-z:blank:] - ``` +When your cmdlet has been registered with Windows PowerShell, you can test it by running it on the +command line. The following procedure can be used to test the sample Select-Str cmdlet. + +1. Start Windows PowerShell, and search the Notes file for occurrences of lines with the expression + ".NET". Note that the quotation marks around the name of the path are required only if the path + consists of more than one word. + + ```powershell + Select-Str -Path "notes" -Pattern ".NET" -SimpleMatch=$false + ``` + The following output appears. + ```output + IgnoreCase : True + LineNumber : 8 + Line : Because Windows PowerShell works directly with .NET objects, there is often a .NET object + Path : C:\PowerShell-Progs\workspace\Samples\SelectStr\notes + Pattern : .NET + IgnoreCase : True + LineNumber : 21 + Line : You should normally define the class for a cmdlet in a .NET namespace + Path : C:\PowerShell-Progs\workspace\Samples\SelectStr\notes + Pattern : .NET + ``` + +2. Search the Notes file for occurrences of lines with the word "over", followed by any other text. + The `SimpleMatch` parameter is using the default value of `false`. The search is case-insensitive + because the `CaseSensitive` parameter is set to `false`. + + ```powershell + Select-Str -Path notes -Pattern "over*" -SimpleMatch -CaseSensitive:$false + ``` + + The following output appears. + + ```Output + IgnoreCase : True + LineNumber : 45 + Line : Override StopProcessing + Path : C:\PowerShell-Progs\workspace\Samples\SelectStr\notes + Pattern : over* + IgnoreCase : True + LineNumber : 49 + Line : overriding the StopProcessing method + Path : C:\PowerShell-Progs\workspace\Samples\SelectStr\notes + Pattern : over* + ``` + +3. Search the Notes file using a regular expression as the pattern. The cmdlet searches for + alphabetical characters and blank spaces enclosed in parentheses. + + ```powershell + Select-Str -Path notes -Pattern "\([A-Za-z:blank:]" -SimpleMatch:$false + ``` + + The following output appears. + + ```Output + IgnoreCase : True + LineNumber : 1 + Line : Advisory Guidelines (Consider Following) + Path : C:\PowerShell-Progs\workspace\Samples\SelectStr\notes + Pattern : \([A-Za-z:blank:] + IgnoreCase : True + LineNumber : 53 + Line : If your cmdlet has objects that are not disposed of (written to the pipeline) + Path : C:\PowerShell-Progs\workspace\Samples\SelectStr\notes + Pattern : \([A-Za-z:blank:] + ``` 4. Perform a case-sensitive search of the Notes file for occurrences of the word "Parameter". - ```powershell - Select-Str -Path notes -Pattern Parameter -CaseSensitive - ``` - - The following output appears. - - ```output - IgnoreCase : False - LineNumber : 6 - Line : Support an InputObject Parameter - Path : C:\PowerShell-Progs\workspace\Samples\SelectStr\notes - Pattern : Parameter - IgnoreCase : False - LineNumber : 30 - Line : Support Force Parameter - Path : C:\PowerShell-Progs\workspace\Samples\SelectStr\notes - Pattern : Parameter - ``` - -5. Search the Variable provider shipped with Windows PowerShell for variables that have numerical values from 0 through 9. - - ```powershell - Select-Str -Path * -Pattern "[0-9]" - ``` - - The following output appears. - - ```output - IgnoreCase : True - LineNumber : 1 - Line : 64 - Path : Variable:\MaximumHistoryCount - Pattern : [0-9] - ``` - -6. Use a script block to search the file SelectStrCommandSample.cs for the string "Pos". The `-cmatch` operator performs a case-insensitive pattern match. - - ```powershell - Select-Str -Path "SelectStrCommandSample.cs" -Script { if ($args[0] -cmatch "Pos"){ return $true } return $false } - ``` - - The following output appears. - - ```output - IgnoreCase : True - LineNumber : 37 - Line : Position = 0. - Path : C:\PowerShell-Progs\workspace\Samples\SelectStr\SelectStrCommandSample.cs - Pattern : - ``` + ```powershell + Select-Str -Path notes -Pattern Parameter -CaseSensitive + ``` + + The following output appears. + + ```Output + IgnoreCase : False + LineNumber : 6 + Line : Support an InputObject Parameter + Path : C:\PowerShell-Progs\workspace\Samples\SelectStr\notes + Pattern : Parameter + IgnoreCase : False + LineNumber : 30 + Line : Support Force Parameter + Path : C:\PowerShell-Progs\workspace\Samples\SelectStr\notes + Pattern : Parameter + ``` + +5. Search the Variable provider shipped with Windows PowerShell for variables that have numerical + values from 0 through 9. + + ```powershell + Select-Str -Path * -Pattern "[0-9]" + ``` + + The following output appears. + + ```Output + IgnoreCase : True + LineNumber : 1 + Line : 64 + Path : Variable:\MaximumHistoryCount + Pattern : [0-9] + ``` + +6. Use a script block to search the file SelectStrCommandSample.cs for the string "Pos". The + `-cmatch` operator performs a case-insensitive pattern match. + + ```powershell + Select-Str -Path "SelectStrCommandSample.cs" -Script { + if ($args[0] -cmatch "Pos"){ return $true } + return $false + } + ``` + + The following output appears. + + ```Output + IgnoreCase : True + LineNumber : 37 + Line : Position = 0. + Path : C:\PowerShell-Progs\workspace\Samples\SelectStr\SelectStrCommandSample.cs + Pattern : + ``` ## See Also -[How to Create a Windows PowerShell Cmdlet](/powershell/scripting/developer/cmdlet/writing-a-windows-powershell-cmdlet) - -[Creating Your First Cmdlet](./creating-a-cmdlet-without-parameters.md) - -[Creating a Cmdlet that Modifies the System](./creating-a-cmdlet-that-modifies-the-system.md) - -[Design Your Windows PowerShell Provider](../prog-guide/designing-your-windows-powershell-provider.md) - -[How Windows PowerShell Works](/previous-versions//ms714658(v=vs.85)) - -[How to Register Cmdlets, Providers, and Host Applications](/previous-versions//ms714644(v=vs.85)) - -[Windows PowerShell SDK](../windows-powershell-reference.md) +[How to Create a Windows PowerShell Cmdlet][22] + +[Creating Your First Cmdlet][07] + +[Creating a Cmdlet that Modifies the System][06] + +[Design Your Windows PowerShell Provider][01] + +[How Windows PowerShell Works][24] + +[How to Register Cmdlets, Providers, and Host Applications][23]) + +[Windows PowerShell SDK][02] + + + +[01]: /previous-versions/powershell/scripting/developer/prog-guide/designing-your-windows-powershell-provider +[02]: ../windows-powershell-reference.md +[03]: ./adding-parameter-sets-to-a-cmdlet.md +[05]: ./approved-verbs-for-windows-powershell-commands.md +[06]: ./creating-a-cmdlet-that-modifies-the-system.md +[07]: ./creating-a-cmdlet-without-parameters.md +[08]: /dotnet/api/System.Management.Automation.AliasAttribute +[09]: /dotnet/api/System.Management.Automation.Cmdlet.BeginProcessing +[10]: /dotnet/api/System.Management.Automation.Cmdlet.ProcessRecord +[11]: /dotnet/api/System.Management.Automation.ContentCmdletProviderIntrinsics.GetReader +[12]: /dotnet/api/System.Management.Automation.ParameterAttribute +[13]: /dotnet/api/System.Management.Automation.Provider.IContentCmdletProvider +[14]: /dotnet/api/System.Management.Automation.ProviderIntrinsics +[15]: /dotnet/api/System.Management.Automation.ProviderIntrinsics.Content +[16]: /dotnet/api/System.Management.Automation.PSCmdlet +[17]: /dotnet/api/System.Management.Automation.PSCmdlet.InvokeProvider +[18]: /dotnet/api/System.Management.Automation.PSObject +[19]: /dotnet/api/System.Management.Automation.SessionState +[20]: /dotnet/api/System.Management.Automation.VerbsCommon +[21]: /dotnet/api/System.Text.RegularExpressions.Regex +[22]: /powershell/scripting/developer/cmdlet/writing-a-windows-powershell-cmdlet +[23]: /previous-versions//ms714644(v=vs.85) +[24]: /previous-versions//ms714658(v=vs.85) +[25]: #defining-the-cmdlet-class diff --git a/reference/docs-conceptual/developer/module/writing-a-custom-windows-powershell-snap-in.md b/reference/docs-conceptual/developer/module/writing-a-custom-windows-powershell-snap-in.md index 3100c9a7f1c3..e50c42b2af33 100644 --- a/reference/docs-conceptual/developer/module/writing-a-custom-windows-powershell-snap-in.md +++ b/reference/docs-conceptual/developer/module/writing-a-custom-windows-powershell-snap-in.md @@ -9,13 +9,13 @@ This example shows how to write a Windows PowerShell snap-in that registers spec With this type of snap-in, you specify which cmdlets, providers, types, or formats to register. For more information about how to write a snap-in that registers all the cmdlets and providers in an -assembly, see [Writing a Windows PowerShell Snap-in](./writing-a-windows-powershell-snap-in.md). +assembly, see [Writing a Windows PowerShell Snap-in][02]. ## To write a Windows PowerShell Snap-in that registers specific cmdlets. 1. Add the RunInstallerAttribute attribute. 2. Create a public class that derives from the - [System.Management.Automation.CustomPSSnapIn](/dotnet/api/System.Management.Automation.CustomPSSnapIn) + [System.Management.Automation.CustomPSSnapIn][03] class. In this example, the class name is "CustomPSSnapinTest". @@ -47,7 +47,7 @@ assembly, see [Writing a Windows PowerShell Snap-in](./writing-a-windows-powersh > Test-HelloWorld and Test-CustomSnapinTest cmdlets". 8. Specify the cmdlets that belong to the custom snap-in (optional) using the - [System.Management.Automation.Runspaces.CmdletConfigurationEntry](/dotnet/api/System.Management.Automation.Runspaces.CmdletConfigurationEntry) + [System.Management.Automation.Runspaces.CmdletConfigurationEntry][04] class. The information added here includes the name of the cmdlet, its .NET type, and the cmdlet Help file name (the format of the cmdlet Help file name should be `name.dll-help.xml`). @@ -212,13 +212,19 @@ public class CustomPSSnapinTest : CustomPSSnapIn } ``` -For more information about registering snap-ins, see -[How to Register Cmdlets, Providers, and Host Applications](/previous-versions/ms714644(v=vs.85)) -in the -[Windows PowerShell Programmer's Guide](../prog-guide/windows-powershell-programmer-s-guide.md). +For more information about registering snap-ins, see [How to Register Cmdlets, Providers, and Host +Applications][05] in the [Windows PowerShell Programmer's Guide][06]. ## See Also -[How to Register Cmdlets, Providers, and Host Applications](/previous-versions/ms714644(v=vs.85)) +[How to Register Cmdlets, Providers, and Host Applications][05] -[Windows PowerShell Shell SDK](../windows-powershell-reference.md) +[Windows PowerShell Shell SDK][01] + + +[01]: ../windows-powershell-reference.md +[02]: ./writing-a-windows-powershell-snap-in.md +[03]: /dotnet/api/System.Management.Automation.CustomPSSnapIn +[04]: /dotnet/api/System.Management.Automation.Runspaces.CmdletConfigurationEntry +[05]: /previous-versions/ms714644(v=vs.85) +[06]: /previous-versions/powershell/scripting/developer/prog-guide/designing-your-windows-powershell-provider diff --git a/reference/docs-conceptual/developer/prog-guide/accessdbprovidersample01-code-sample.md b/reference/docs-conceptual/developer/prog-guide/accessdbprovidersample01-code-sample.md deleted file mode 100644 index acee5942aea1..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/accessdbprovidersample01-code-sample.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -description: AccessDbProviderSample01 Code Sample -ms.date: 09/13/2016 -title: AccessDbProviderSample01 Code Sample ---- -# AccessDbProviderSample01 Code Sample - -The following code shows the implementation of the Windows PowerShell provider described in -[Creating a Basic Windows PowerShell Provider](./creating-a-basic-windows-powershell-provider.md). -This implementation provides methods for starting and stopping the provider, and although it does -not provide a means to access a data store or to get or set the data in the data store, it does -provide the basic functionality that is required by all providers. - -> [!NOTE] -> You can download the C# source file (AccessDBSampleProvider01.cs) for this provider by using the -> Windows Software Development Kit for Windows Vista and Microsoft .NET Framework 3.0 Runtime -> Components. For download instructions, see -> [How to Install Windows PowerShell and Download the Windows PowerShell SDK](/powershell/scripting/developer/installing-the-windows-powershell-sdk). -> The downloaded source files are available in the **\** directory. For more -> information about other Windows PowerShell provider implementations, see -> [Designing Your Windows PowerShell Provider](./designing-your-windows-powershell-provider.md). - -## Code Sample - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/AccessDBProviderSample01/AccessDBProviderSample01.cs" range="11-30"::: - -## See Also - -[Windows PowerShell Programmer's Guide](./windows-powershell-programmer-s-guide.md) - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/accessdbprovidersample02-code-sample.md b/reference/docs-conceptual/developer/prog-guide/accessdbprovidersample02-code-sample.md deleted file mode 100644 index fac3764b11f9..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/accessdbprovidersample02-code-sample.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -description: AccessDbProviderSample02 Code Sample -ms.date: 09/13/2016 -title: AccessDbProviderSample02 Code Sample ---- -# AccessDbProviderSample02 Code Sample - -The following code shows the implementation of the Windows PowerShell provider described in -[Creating a Windows PowerShell Drive Provider](./creating-a-windows-powershell-drive-provider.md). -This implementation creates a path, makes a connection to an Access database, and then removes the -drive. - -> [!NOTE] -> You can download the C# source file (AccessDBSampleProvider02.cs) for this provider using the -> Microsoft Windows Software Development Kit for Windows Vista and Microsoft .NET Framework 3.0 -> Runtime Components. For download instructions, see -> [How to Install Windows PowerShell and Download the Windows PowerShell SDK](/powershell/scripting/developer/installing-the-windows-powershell-sdk). -> The downloaded source files are available in the **\** directory. For more -> information about other Windows PowerShell provider implementations, see -> [Designing Your Windows PowerShell Provider](./designing-your-windows-powershell-provider.md). - -## Code Sample - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/AccessDBProviderSample02/AccessDBProviderSample02.cs" range="11-154"::: - -## See Also - -[Windows PowerShell Programmer's Guide](./windows-powershell-programmer-s-guide.md) - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/accessdbprovidersample03-code-sample.md b/reference/docs-conceptual/developer/prog-guide/accessdbprovidersample03-code-sample.md deleted file mode 100644 index adbf43574f91..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/accessdbprovidersample03-code-sample.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -description: AccessDbProviderSample03 Code Sample -ms.date: 09/13/2016 -title: AccessDbProviderSample03 Code Sample ---- -# AccessDbProviderSample03 Code Sample - -The following code shows the implementation of the Windows PowerShell provider described in -[Creating a Windows PowerShell Item Provider](./creating-a-windows-powershell-item-provider.md). -This provider that can manipulate the data in a data store. - -> [!NOTE] -> You can download the C# source file (AccessDBSampleProvider03.cs) for this provider using the -> Microsoft Windows Software Development Kit for Windows Vista and .NET Framework 3.0 Runtime -> Components. For download instructions, see -> [How to Install Windows PowerShell and Download the Windows PowerShell SDK](/powershell/scripting/developer/installing-the-windows-powershell-sdk). -> The downloaded source files are available in the **\** directory. For more -> information about other Windows PowerShell provider implementations, see -> [Designing Your Windows PowerShell Provider](./designing-your-windows-powershell-provider.md). - -## Code Sample - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/AccessDBProviderSample03/AccessDBProviderSample03.cs" range="11-976"::: - -## See Also - -[Windows PowerShell Programmer's Guide](./windows-powershell-programmer-s-guide.md) - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/accessdbprovidersample04-code-sample.md b/reference/docs-conceptual/developer/prog-guide/accessdbprovidersample04-code-sample.md deleted file mode 100644 index e761deef1a4e..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/accessdbprovidersample04-code-sample.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -description: AccessDbProviderSample04 Code Sample -ms.date: 09/13/2016 -title: AccessDbProviderSample04 Code Sample ---- -# AccessDbProviderSample04 Code Sample - -The following code shows the implementation of the Windows PowerShell provider described in -[Creating a Windows PowerShell Container Provider](./creating-a-windows-powershell-container-provider.md). -This provider works on multi-layer data stores. For this type of data store, the top level of the -store contains the root items and each subsequent level is referred to as a node of child items. By -allowing the user to work on these child nodes, a user can interact hierarchically through the data -store. - -## Code Sample - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/AccessDBProviderSample04/AccessDBProviderSample04.cs" range="11-1635"::: - -## See Also - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/accessdbprovidersample05-code-sample.md b/reference/docs-conceptual/developer/prog-guide/accessdbprovidersample05-code-sample.md deleted file mode 100644 index 0765358ccf21..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/accessdbprovidersample05-code-sample.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -description: AccessDbProviderSample05 Code Sample -ms.date: 09/13/2016 -title: AccessDbProviderSample05 Code Sample ---- -# AccessDbProviderSample05 Code Sample - -The following code shows the implementation of the Windows PowerShell navigation provider described -in -[Creating a Windows PowerShell Navigation Provider](./creating-a-windows-powershell-navigation-provider.md). -This provider supports recursive commands, nested containers, and relative paths that allow it to -navigate the data store. - -## Code Sample - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/AccessDBProviderSample05/AccessDBProviderSample05.cs" range="11-1960"::: - -## See Also - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/accessdbprovidersample06-code-sample.md b/reference/docs-conceptual/developer/prog-guide/accessdbprovidersample06-code-sample.md deleted file mode 100644 index 94741673f050..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/accessdbprovidersample06-code-sample.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -description: AccessDbProviderSample06 Code Sample -ms.date: 09/13/2016 -title: AccessDbProviderSample06 Code Sample ---- -# AccessDbProviderSample06 Code Sample - -The following code shows the implementation of the Windows PowerShell content provider described in -[Creating a Windows PowerShell Content Provider](./creating-a-windows-powershell-content-provider.md). -This provider enables the user to manipulate the contents of the items in a data store. - -> [!NOTE] -> You can download the C# source file (AccessDBSampleProvider06.cs) for this provider by using the -> Microsoft Windows Software Development Kit for Windows Vista and Microsoft .NET Framework 3.0 -> Runtime Components. For download instructions, see -> [How to Install Windows PowerShell and Download the Windows PowerShell SDK](/powershell/scripting/developer/installing-the-windows-powershell-sdk). -> The downloaded source files are available in the **\** directory. For more -> information about other Windows PowerShell provider implementations, see -> [Designing Your Windows PowerShell Provider](./designing-your-windows-powershell-provider.md). - -## Code Sample - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/AccessDBProviderSample06/AccessDBProviderSample06.cs" range="11-2399"::: - -## See Also - -[Windows PowerShell Programmer's Guide](./windows-powershell-programmer-s-guide.md) - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/creating-a-basic-windows-powershell-provider.md b/reference/docs-conceptual/developer/prog-guide/creating-a-basic-windows-powershell-provider.md deleted file mode 100644 index 475c5a871807..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/creating-a-basic-windows-powershell-provider.md +++ /dev/null @@ -1,164 +0,0 @@ ---- -description: Creating a Basic Windows PowerShell Provider -ms.date: 09/13/2016 -title: Creating a Basic Windows PowerShell Provider ---- -# Creating a Basic Windows PowerShell Provider - -This topic is the starting point for learning how to create a Windows PowerShell provider. The basic -provider described here provides methods for starting and stopping the provider, and although this -provider does not provide a means to access a data store or to get or set the data in the data -store, it does provide the basic functionality that is required by all providers. - -As mentioned previously, the basic provider described here implements methods for starting and -stopping the provider. The Windows PowerShell runtime calls these methods to initialize and -uninitialize the provider. - -> [!NOTE] -> You can find a sample of this provider in the AccessDBSampleProvider01.cs file provided by Windows -> PowerShell. - -## Defining the Windows PowerShell Provider Class - -The first step in creating a Windows PowerShell provider is to define its .NET class. This basic -provider defines a class called `AccessDBProvider` that derives from the -[System.Management.Automation.Provider.CmdletProvider](/dotnet/api/System.Management.Automation.Provider.CmdletProvider) -base class. - -It is recommended that you place your provider classes in a `Providers` namespace of your API -namespace, for example, xxx.PowerShell.Providers. This provider uses the -`Microsoft.Samples.PowerShell.Provider` namespace, in which all Windows PowerShell provider samples -run. - -> [!NOTE] -> The class for a Windows PowerShell provider must be explicitly marked as public. Classes not -> marked as public will default to internal and will not be found by the Windows PowerShell runtime. - -Here is the class definition for this basic provider: - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/AccessDBProviderSample01/AccessDBProviderSample01.cs" range="23-24"::: - -Right before the class definition, you must declare the -[System.Management.Automation.Provider.CmdletProviderAttribute](/dotnet/api/System.Management.Automation.Provider.CmdletProviderAttribute) -attribute, with the syntax [CmdletProvider()]. - -You can set attribute keywords to further declare the class if necessary. Notice that the -[System.Management.Automation.Provider.CmdletProviderAttribute](/dotnet/api/System.Management.Automation.Provider.CmdletProviderAttribute) -attribute declared here includes two parameters. The first attribute parameter specifies the -default-friendly name for the provider, which the user can modify later. The second parameter -specifies the Windows PowerShell-defined capabilities that the provider exposes to the Windows -PowerShell runtime during command processing. The possible values for the provider capabilities are -defined by the -[System.Management.Automation.Provider.ProviderCapabilities](/dotnet/api/System.Management.Automation.Provider.ProviderCapabilities) -enumeration. Because this is a base provider, it supports no capabilities. - -> [!NOTE] -> The fully qualified name of the Windows PowerShell provider includes the assembly name and other -> attributes determined by Windows PowerShell upon registration of the provider. - -## Defining Provider-Specific State Information - -The -[System.Management.Automation.Provider.CmdletProvider](/dotnet/api/System.Management.Automation.Provider.CmdletProvider) -base class and all derived classes are considered stateless because the Windows PowerShell runtime -creates provider instances only as required. Therefore, if your provider requires full control and -state maintenance for provider-specific data, it must derive a class from the -[System.Management.Automation.ProviderInfo](/dotnet/api/System.Management.Automation.ProviderInfo) -class. Your derived class should define the members necessary to maintain the state so that the -provider-specific data can be accessed when the Windows PowerShell runtime calls the -[System.Management.Automation.Provider.CmdletProvider.Start*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Start) -method to initialize the provider. - -A Windows PowerShell provider can also maintain connection-based state. For more information about -maintaining connection state, see -[Creating a PowerShell Drive Provider](./creating-a-windows-powershell-drive-provider.md). - -## Initializing the Provider - -To initialize the provider, the Windows PowerShell runtime calls the -[System.Management.Automation.Provider.CmdletProvider.Start*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Start) -method when Windows PowerShell is started. For the most part, your provider can use the default -implementation of this method, which simply returns the -[System.Management.Automation.ProviderInfo](/dotnet/api/System.Management.Automation.ProviderInfo) -object that describes your provider. However, in the case where you want to add additional -initialization information, you should implement your own -[System.Management.Automation.Provider.CmdletProvider.Start*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Start) -method that returns a modified version of the -[System.Management.Automation.ProviderInfo](/dotnet/api/System.Management.Automation.ProviderInfo) -object that is passed to your provider. In general, this method should return the provided -[System.Management.Automation.ProviderInfo](/dotnet/api/System.Management.Automation.ProviderInfo) -object passed to it or a modified -[System.Management.Automation.ProviderInfo](/dotnet/api/System.Management.Automation.ProviderInfo) -object that contains other initialization information. - -This basic provider does not override this method. However, the following code shows the default implementation of this method: - - - -The provider can maintain the state of provider-specific information as described in -[Defining Provider-specific Data State](#defining-provider-specific-state-information). In this -case, your implementation must override the -[System.Management.Automation.Provider.CmdletProvider.Start*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Start) -method to return an instance of the derived class. - -## Start Dynamic Parameters - -Your provider implementation of the -[System.Management.Automation.Provider.CmdletProvider.Start*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Start) -method might require additional parameters. In this case, the provider should override the -[System.Management.Automation.Provider.CmdletProvider.StartDynamicParameters*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.StartDynamicParameters) -method and return an object that has properties and fields with parsing attributes similar to a -cmdlet class or a -[System.Management.Automation.RuntimeDefinedParameterDictionary](/dotnet/api/System.Management.Automation.RuntimeDefinedParameterDictionary) -object. - -This basic provider does not override this method. However, the following code shows the default implementation of this method: - - - -## Uninitializing the Provider - -To free resources that the Windows PowerShell provider uses, your provider should implement its own -[System.Management.Automation.Provider.CmdletProvider.Stop*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Stop) -method. This method is called by the Windows PowerShell runtime to uninitialize the provider at the -close of a session. - -This basic provider does not override this method. However, the following code shows the default -implementation of this method: - - - -## Code Sample - -For complete sample code, see -[AccessDbProviderSample01 Code Sample](./accessdbprovidersample01-code-sample.md). - -## Testing the Windows PowerShell Provider - -Once your Windows PowerShell provider has been registered with Windows PowerShell, you can test it -by running the supported cmdlets on the command line. For this basic provider, run the new shell and -use the `Get-PSProvider` cmdlet to retrieve the list of providers and ensure that the AccessDb -provider is present. - -```powershell -Get-PSProvider -``` - -The following output appears: - -```Output -Name Capabilities Drives ----- ------------ ------ -AccessDb None {} -Alias ShouldProcess {Alias} -Environment ShouldProcess {Env} -FileSystem Filter, ShouldProcess {C, Z} -Function ShouldProcess {function} -Registry ShouldProcess {HKLM, HKCU} -``` - -## See Also - -[Creating Windows PowerShell Providers](./how-to-create-a-windows-powershell-provider.md) - -[Designing Your Windows PowerShell Provider](./designing-your-windows-powershell-provider.md) diff --git a/reference/docs-conceptual/developer/prog-guide/creating-a-windows-powershell-container-provider.md b/reference/docs-conceptual/developer/prog-guide/creating-a-windows-powershell-container-provider.md deleted file mode 100644 index 15c3e2cb6bdd..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/creating-a-windows-powershell-container-provider.md +++ /dev/null @@ -1,717 +0,0 @@ ---- -description: Creating a Windows PowerShell Container Provider -ms.date: 09/13/2016 -title: Creating a Windows PowerShell Container Provider ---- -# Creating a Windows PowerShell Container Provider - -This topic describes how to create a Windows PowerShell provider that can work on multi-layer data -stores. For this type of data store, the top level of the store contains the root items and each -subsequent level is referred to as a node of child items. By allowing the user to work on these -child nodes, a user can interact hierarchically through the data store. - -Providers that can work on multi-level data stores are referred to as Windows PowerShell container -providers. However, be aware that a Windows PowerShell container provider can be used only when -there is one container (no nested containers) with items in it. If there are nested containers, then -you must implement a Windows PowerShell navigation provider. For more information about implementing -Windows PowerShell navigation provider, see -[Creating a Windows PowerShell Navigation Provider](./creating-a-windows-powershell-navigation-provider.md). - -> [!NOTE] -> You can download the C# source file (AccessDBSampleProvider04.cs) for this provider using the -> Microsoft Windows Software Development Kit for Windows Vista and .NET Framework 3.0 Runtime -> Components. For download instructions, see -> [How to Install Windows PowerShell and Download the Windows PowerShell SDK](/powershell/scripting/developer/installing-the-windows-powershell-sdk). -> The downloaded source files are available in the **\** directory. For more -> information about other Windows PowerShell provider implementations, see -> [Designing Your Windows PowerShell Provider](./designing-your-windows-powershell-provider.md). - -The Windows PowerShell container provider described here defines the database as its single -container, with the tables and rows of the database defined as items of the container. - -> [!CAUTION] -> Be aware that this design assumes a database that has a field with the name ID, and that the type -> of the field is LongInteger. - -## Defining a Windows PowerShell Container Provider Class - -A Windows PowerShell container provider must define a .NET class that derives from the -[System.Management.Automation.Provider.ContainerCmdletProvider](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider) -base class. Here is the class definition for the Windows PowerShell container provider described in -this section. - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/AccessDBProviderSample04/AccessDBProviderSample04.cs" range="34-35"::: - -Notice that in this class definition, the -[System.Management.Automation.Provider.CmdletProviderAttribute](/dotnet/api/System.Management.Automation.Provider.CmdletProviderAttribute) -attribute includes two parameters. The first parameter specifies a user-friendly name for the -provider that is used by Windows PowerShell. The second parameter specifies the Windows PowerShell -specific capabilities that the provider exposes to the Windows PowerShell runtime during command -processing. For this provider, there are no Windows PowerShell specific capabilities that are added. - -## Defining Base Functionality - -As described in -[Designing Your Windows PowerShell Provider](./designing-your-windows-powershell-provider.md), the -[System.Management.Automation.Provider.ContainerCmdletProvider](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider) -class derives from several other classes that provided different provider functionality. A Windows -PowerShell container provider, therefore, needs to define all of the functionality provided by those -classes. - -To implement functionality for adding session-specific initialization information and for releasing -resources that are used by the provider, see -[Creating a Basic Windows PowerShell Provider](./creating-a-basic-windows-powershell-provider.md). -However, most providers (including the provider described here) can use the default implementation -of this functionality that is provided by Windows PowerShell. - -To get access to the data store, the provider must implement the methods of the -[System.Management.Automation.Provider.DriveCmdletProvider](/dotnet/api/System.Management.Automation.Provider.DriveCmdletProvider) -base class. For more information about implementing these methods, see -[Creating a Windows PowerShell Drive Provider](./creating-a-windows-powershell-drive-provider.md). - -To manipulate the items of a data store, such as getting, setting, and clearing items, the provider -must implement the methods provided by the -[System.Management.Automation.Provider.ItemCmdletProvider](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider) -base class. For more information about implementing these methods, see -[Creating a Windows PowerShell Item Provider](./creating-a-windows-powershell-item-provider.md). - -## Retrieving Child Items - -To retrieve a child item, the Windows PowerShell container provider must override the -[System.Management.Automation.Provider.ContainerCmdletProvider.GetChildItems*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.GetChildItems) -method to support calls from the `Get-ChildItem` cmdlet. This method retrieves child items from the -data store and writes them to the pipeline as objects. If the `recurse` parameter of the cmdlet is -specified, the method retrieves all children regardless of what level they are at. If the `recurse` -parameter is not specified, the method retrieves only a single level of children. - -Here is the implementation of the -[System.Management.Automation.Provider.ContainerCmdletProvider.GetChildItems*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.GetChildItems) -method for this provider. Notice that this method retrieves the child items in all database tables -when the path indicates the Access database, and retrieves the child items from the rows of that -table if the path indicates a data table. - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/AccessDBProviderSample04/AccessDBProviderSample04.cs" range="311-362"::: - -#### Things to Remember About Implementing GetChildItems - -The following conditions may apply to your implementation of -[System.Management.Automation.Provider.ContainerCmdletProvider.GetChildItems*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.GetChildItems): - -- When defining the provider class, a Windows PowerShell container provider might declare provider - capabilities of ExpandWildcards, Filter, Include, or Exclude, from the - [System.Management.Automation.Provider.ProviderCapabilities](/dotnet/api/System.Management.Automation.Provider.ProviderCapabilities) - enumeration. In these cases, the implementation of the - [System.Management.Automation.Provider.ContainerCmdletProvider.GetChildItems*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.GetChildItems) - method needs to ensure that the path passed to the method meets the requirements of the specified - capabilities. To do this, the method should access the appropriate property, for example, the - [System.Management.Automation.Provider.CmdletProvider.Exclude*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Exclude) - and - [System.Management.Automation.Provider.CmdletProvider.Include*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Include) - properties. - -- The implementation of this method should take into account any form of access to the item that - might make the item visible to the user. For example, if a user has write access to a file through - the FileSystem provider (supplied by Windows PowerShell), but not read access, the file still - exists and - [System.Management.Automation.Provider.ItemCmdletProvider.ItemExists*](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider.ItemExists) - returns `true`. Your implementation might require the checking of a parent item to see if the - child can be enumerated. - -- When writing multiple items, the - [System.Management.Automation.Provider.ContainerCmdletProvider.GetChildItems*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.GetChildItems) - method can take some time. You can design your provider to write the items using the - [System.Management.Automation.Provider.CmdletProvider.WriteItemObject*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.WriteItemObject) - method one at a time. Using this technique will present the items to the user in a stream. - -- Your implementation of - [System.Management.Automation.Provider.ContainerCmdletProvider.GetChildItems*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.GetChildItems) - is responsible for preventing infinite recursion when there are circular links, and the like. An - appropriate terminating exception should be thrown to reflect such a condition. - -## Attaching Dynamic Parameters to the Get-ChildItem Cmdlet - -Sometimes the `Get-ChildItem` cmdlet that calls -[System.Management.Automation.Provider.ContainerCmdletProvider.GetChildItems*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.GetChildItems) -requires additional parameters that are specified dynamically at runtime. To provide these dynamic -parameters, the Windows PowerShell container provider must implement the -[System.Management.Automation.Provider.ContainerCmdletProvider.GetChildItemsDynamicParameters*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.GetChildItemsDynamicParameters) -method. This method retrieves dynamic parameters for the item at the indicated path and returns an -object that has properties and fields with parsing attributes similar to a cmdlet class or a -[System.Management.Automation.RuntimeDefinedParameterDictionary](/dotnet/api/System.Management.Automation.RuntimeDefinedParameterDictionary) -object. The Windows PowerShell runtime uses the returned object to add the parameters to the -`Get-ChildItem` cmdlet. - -This Windows PowerShell container provider does not implement this method. However, the following -code is the default implementation of this method. - - - -## Retrieving Child Item Names - -To retrieve the names of child items, the Windows PowerShell container provider must override the -[System.Management.Automation.Provider.ContainerCmdletProvider.GetChildNames*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.GetChildNames) -method to support calls from the `Get-ChildItem` cmdlet when its `Name` parameter is specified. This -method retrieves the names of the child items for the specified path or child item names for all -containers if the `returnAllContainers` parameter of the cmdlet is specified. A child name is the -leaf portion of a path. For example, the child name for the path C:\windows\system32\abc.dll is -"abc.dll". The child name for the directory C:\windows\system32 is "system32". - -Here is the implementation of the -[System.Management.Automation.Provider.ContainerCmdletProvider.GetChildNames*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.GetChildNames) -method for this provider. Notice that the method retrieves table names if the specified path -indicates the Access database (drive) and row numbers if the path indicates a table. - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/AccessDBProviderSample04/AccessDBProviderSample04.cs" range="369-411"::: - -#### Things to Remember About Implementing GetChildNames - -The following conditions may apply to your implementation of -[System.Management.Automation.Provider.ContainerCmdletProvider.GetChildItems*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.GetChildItems): - -- When defining the provider class, a Windows PowerShell container provider might declare provider - capabilities of ExpandWildcards, Filter, Include, or Exclude, from the - [System.Management.Automation.Provider.ProviderCapabilities](/dotnet/api/System.Management.Automation.Provider.ProviderCapabilities) - enumeration. In these cases, the implementation of the - [System.Management.Automation.Provider.ContainerCmdletProvider.GetChildItems*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.GetChildItems) - method needs to ensure that the path passed to the method meets the requirements of the specified - capabilities. To do this, the method should access the appropriate property, for example, the - [System.Management.Automation.Provider.CmdletProvider.Exclude*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Exclude) - and - [System.Management.Automation.Provider.CmdletProvider.Include*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Include) - properties. - - > [!NOTE] - > An exception to this rule occurs when the `returnAllContainers` parameter of the cmdlet is - > specified. In this case, the method should retrieve any child name for a container, even if it - > does not match the values of the - > [System.Management.Automation.Provider.CmdletProvider.Filter*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Filter), - > [System.Management.Automation.Provider.CmdletProvider.Include*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Include), - > or - > [System.Management.Automation.Provider.CmdletProvider.Exclude*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Exclude) - > properties. - -- By default, overrides of this method should not retrieve names of objects that are generally - hidden from the user unless the - [System.Management.Automation.Provider.CmdletProvider.Force*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Force) - property is specified. If the specified path indicates a container, the - [System.Management.Automation.Provider.CmdletProvider.Force*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Force) - property is not required. - -- Your implementation of - [System.Management.Automation.Provider.ContainerCmdletProvider.GetChildNames*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.GetChildNames) - is responsible for preventing infinite recursion when there are circular links, and the like. An - appropriate terminating exception should be thrown to reflect such a condition. - -## Attaching Dynamic Parameters to the Get-ChildItem Cmdlet (Name) - -Sometimes the `Get-ChildItem` cmdlet (with the `Name` parameter) requires additional parameters that -are specified dynamically at runtime. To provide these dynamic parameters, the Windows PowerShell -container provider must implement the -[System.Management.Automation.Provider.ContainerCmdletProvider.GetChildNamesDynamicParameters*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.GetChildNamesDynamicParameters) -method. This method retrieves the dynamic parameters for the item at the indicated path and returns -an object that has properties and fields with parsing attributes similar to a cmdlet class or a -[System.Management.Automation.RuntimeDefinedParameterDictionary](/dotnet/api/System.Management.Automation.RuntimeDefinedParameterDictionary) -object. The Windows PowerShell runtime uses the returned object to add the parameters to the -`Get-ChildItem` cmdlet. - -This provider does not implement this method. However, the following code is the default -implementation of this method. - - - -## Renaming Items - -To rename an item, a Windows PowerShell container provider must override the -[System.Management.Automation.Provider.ContainerCmdletProvider.RenameItem*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.RenameItem) -method to support calls from the `Rename-Item` cmdlet. This method changes the name of the item at -the specified path to the new name provided. The new name must always be relative to the parent item -(container). - -This provider does not override the -[System.Management.Automation.Provider.ContainerCmdletProvider.RenameItem*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.RenameItem) -method. However, the following is the default implementation. - - - -#### Things to Remember About Implementing RenameItem - -The following conditions may apply to your implementation of -[System.Management.Automation.Provider.ContainerCmdletProvider.RenameItem*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.RenameItem): - -- When defining the provider class, a Windows PowerShell container provider might declare provider - capabilities of ExpandWildcards, Filter, Include, or Exclude, from the - [System.Management.Automation.Provider.ProviderCapabilities](/dotnet/api/System.Management.Automation.Provider.ProviderCapabilities) - enumeration. In these cases, the implementation of the - [System.Management.Automation.Provider.ContainerCmdletProvider.GetChildItems*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.GetChildItems) - method needs to ensure that the path passed to the method meets the requirements of the specified - capabilities. To do this, the method should access the appropriate property, for example, the - [System.Management.Automation.Provider.CmdletProvider.Exclude*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Exclude) - and - [System.Management.Automation.Provider.CmdletProvider.Include*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Include) - properties. - -- The - [System.Management.Automation.Provider.ContainerCmdletProvider.RenameItem*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.RenameItem) - method is intended for the modification of the name of an item only, and not for move operations. - Your implementation of the method should write an error if the `newName` parameter contains path - separators, or might otherwise cause the item to change its parent location. - -- By default, overrides of this method should not rename objects unless the - [System.Management.Automation.Provider.CmdletProvider.Force*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Force) - property is specified. If the specified path indicates a container, the - [System.Management.Automation.Provider.CmdletProvider.Force*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Force) - property is not required. - -- Your implementation of the - [System.Management.Automation.Provider.ContainerCmdletProvider.RenameItem*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.RenameItem) - method should call - [System.Management.Automation.Provider.CmdletProvider.ShouldProcess](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldProcess) - and check its return value before making any changes to the data store. This method is used to - confirm execution of an operation when a change is made to system state, for example, renaming - files. - [System.Management.Automation.Provider.CmdletProvider.ShouldProcess](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldProcess) - sends the name of the resource to be changed to the user, with the Windows PowerShell runtime - taking into account any command line settings or preference variables in determining what should - be displayed. - - After the call to - [System.Management.Automation.Provider.CmdletProvider.ShouldProcess](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldProcess) - returns `true`, the - [System.Management.Automation.Provider.ContainerCmdletProvider.RenameItem*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.RenameItem) - method should call the - [System.Management.Automation.Provider.CmdletProvider.ShouldContinue](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldContinue) - method. This method sends a message a confirmation message to the user to allow additional - feedback to say if the operation should be continued. A provider should call - [System.Management.Automation.Provider.CmdletProvider.ShouldContinue](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldContinue) - as an additional check for potentially dangerous system modifications. - -## Attaching Dynamic Parameters to the Rename-Item Cmdlet - -Sometimes the `Rename-Item` cmdlet requires additional parameters that are specified dynamically at -runtime. To provide these dynamic parameters, Windows PowerShell container provider must implement -the -[System.Management.Automation.Provider.ContainerCmdletProvider.RenameItemDynamicParameters*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.RenameItemDynamicParameters) -method. This method retrieves the parameters for the item at the indicated path and returns an -object that has properties and fields with parsing attributes similar to a cmdlet class or a -[System.Management.Automation.RuntimeDefinedParameterDictionary](/dotnet/api/System.Management.Automation.RuntimeDefinedParameterDictionary) -object. The Windows PowerShell runtime uses the returned object to add the parameters to the -`Rename-Item` cmdlet. - -This container provider does not implement this method. However, the following code is the default -implementation of this method. - - - -## Creating New Items - -To create new items, a container provider must implement the -[System.Management.Automation.Provider.ContainerCmdletProvider.NewItem*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.NewItem) -method to support calls from the `New-Item` cmdlet. This method creates a data item located at the -specified path. The `type` parameter of the cmdlet contains the provider-defined type for the new -item. For example, the FileSystem provider uses a `type` parameter with a value of "file" or -"directory". The `newItemValue` parameter of the cmdlet specifies a provider-specific value for the -new item. - -Here is the implementation of the -[System.Management.Automation.Provider.ContainerCmdletProvider.NewItem*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.NewItem) -method for this provider. - -```csharp -protected override void NewItem( string path, string type, object newItemValue ) -{ - // Create the new item here after - // performing necessary validations - // - // WriteItemObject(newItemValue, path, false); - - // Example - // - // if (ShouldProcess(path, "new item")) - // { - // // Create a new item and then call WriteObject - // WriteObject(newItemValue, path, false); - // } - -} // NewItem -``` - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/AccessDBProviderSample04/AccessDBProviderSample04.cs" range="939-955"::: - -#### Things to Remember About Implementing NewItem - -The following conditions may apply to your implementation of -[System.Management.Automation.Provider.ContainerCmdletProvider.NewItem*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.NewItem): - -- The - [System.Management.Automation.Provider.ContainerCmdletProvider.NewItem*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.NewItem) - method should perform a case-insensitive comparison of the string passed in the `type` parameter. - It should also allow for least ambiguous matches. For example, for the types "file" and - "directory", only the first letter is required to disambiguate. If the `type` parameter indicates - a type your provider cannot create, the - [System.Management.Automation.Provider.ContainerCmdletProvider.NewItem*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.NewItem) - method should write an ArgumentException with a message indicating the types the provider can - create. - -- For the `newItemValue` parameter, the implementation of the - [System.Management.Automation.Provider.ContainerCmdletProvider.NewItem*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.NewItem) - method is recommended to accept strings at a minimum. It should also accept the type of object - that is retrieved by the - [System.Management.Automation.Provider.ItemCmdletProvider.GetItem*](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider.GetItem) - method for the same path. The - [System.Management.Automation.Provider.ContainerCmdletProvider.NewItem*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.NewItem) - method can use the - [System.Management.Automation.LanguagePrimitives.ConvertTo*](/dotnet/api/System.Management.Automation.LanguagePrimitives.ConvertTo) - method to convert types to the desired type. - -- Your implementation of the - [System.Management.Automation.Provider.ContainerCmdletProvider.NewItem*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.NewItem) - method should call - [System.Management.Automation.Provider.CmdletProvider.ShouldProcess](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldProcess) - and check its return value before making any changes to the data store. After the call to - [System.Management.Automation.Provider.CmdletProvider.ShouldProcess](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldProcess) - returns true, the - [System.Management.Automation.Provider.ContainerCmdletProvider.NewItem*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.NewItem) - method should call the - [System.Management.Automation.Provider.CmdletProvider.ShouldContinue](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldContinue) - method as an additional check for potentially dangerous system modifications. - -## Attaching Dynamic Parameters to the New-Item Cmdlet - -Sometimes the `New-Item` cmdlet requires additional parameters that are specified dynamically at -runtime. To provide these dynamic parameters, the container provider must implement the -[System.Management.Automation.Provider.ContainerCmdletProvider.NewItemDynamicParameters*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.NewItemDynamicParameters) -method. This method retrieves the parameters for the item at the indicated path and returns an -object that has properties and fields with parsing attributes similar to a cmdlet class or a -[System.Management.Automation.RuntimeDefinedParameterDictionary](/dotnet/api/System.Management.Automation.RuntimeDefinedParameterDictionary) -object. The Windows PowerShell runtime uses the returned object to add the parameters to the -`New-Item` cmdlet. - -This provider does not implement this method. However, the following code is the default implementation of this method. - - - -## Removing Items - -To remove items, the Windows PowerShell provider must override the -[System.Management.Automation.Provider.ContainerCmdletProvider.RemoveItem*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.RemoveItem) -method to support calls from the `Remove-Item` cmdlet. This method deletes an item from the data -store at the specified path. If the `recurse` parameter of the `Remove-Item` cmdlet is set to -`true`, the method removes all child items regardless of their level. If the parameter is set to -`false`, the method removes only a single item at the specified path. - -This provider does not support item removal. However, the following code is the default -implementation of -[System.Management.Automation.Provider.ContainerCmdletProvider.RemoveItem*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.RemoveItem). - - - -#### Things to Remember About Implementing RemoveItem - -The following conditions may apply to your implementation of -[System.Management.Automation.Provider.ContainerCmdletProvider.NewItem*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.NewItem): - -- When defining the provider class, a Windows PowerShell container provider might declare provider - capabilities of ExpandWildcards, Filter, Include, or Exclude, from the - [System.Management.Automation.Provider.ProviderCapabilities](/dotnet/api/System.Management.Automation.Provider.ProviderCapabilities) - enumeration. In these cases, the implementation of the - [System.Management.Automation.Provider.ContainerCmdletProvider.GetChildItems*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.GetChildItems) - method needs to ensure that the path passed to the method meets the requirements of the specified - capabilities. To do this, the method should access the appropriate property, for example, the - [System.Management.Automation.Provider.CmdletProvider.Exclude*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Exclude) - and - [System.Management.Automation.Provider.CmdletProvider.Include*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Include) - properties. - -- By default, overrides of this method should not remove objects unless the - [System.Management.Automation.Provider.CmdletProvider.Force*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Force) - property is set to true. If the specified path indicates a container, the - [System.Management.Automation.Provider.CmdletProvider.Force*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Force) - property is not required. - -- Your implementation of - [System.Management.Automation.Provider.ContainerCmdletProvider.RemoveItem*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.RemoveItem) - is responsible for preventing infinite recursion when there are circular links, and the like. An - appropriate terminating exception should be thrown to reflect such a condition. - -- Your implementation of the - [System.Management.Automation.Provider.ContainerCmdletProvider.RemoveItem*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.RemoveItem) - method should call - [System.Management.Automation.Provider.CmdletProvider.ShouldProcess](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldProcess) - and check its return value before making any changes to the data store. After the call to - [System.Management.Automation.Provider.CmdletProvider.ShouldProcess](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldProcess) - returns `true`, the - [System.Management.Automation.Provider.ContainerCmdletProvider.RemoveItem*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.RemoveItem) - method should call the - [System.Management.Automation.Provider.CmdletProvider.ShouldContinue](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldContinue) - method as an additional check for potentially dangerous system modifications. - -## Attaching Dynamic Parameters to the Remove-Item Cmdlet - -Sometimes the `Remove-Item` cmdlet requires additional parameters that are specified dynamically at -runtime. To provide these dynamic parameters, the container provider must implement the -[System.Management.Automation.Provider.ContainerCmdletProvider.RemoveItemDynamicParameters*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.RemoveItemDynamicParameters) -method to handle these parameters. This method retrieves the dynamic parameters for the item at the -indicated path and returns an object that has properties and fields with parsing attributes similar -to a cmdlet class or a -[System.Management.Automation.RuntimeDefinedParameterDictionary](/dotnet/api/System.Management.Automation.RuntimeDefinedParameterDictionary) -object. The Windows PowerShell runtime uses the returned object to add the parameters to the -`Remove-Item` cmdlet. - -This container provider does not implement this method. However, the following code is the default -implementation of -[System.Management.Automation.Provider.ContainerCmdletProvider.RemoveItemDynamicParameters*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.RemoveItemDynamicParameters). - - - -## Querying for Child Items - -To check to see if child items exist at the specified path, the Windows PowerShell container -provider must override the -[System.Management.Automation.Provider.ContainerCmdletProvider.HasChildItems*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.HasChildItems) -method. This method returns `true` if the item has children, and `false` otherwise. For a null or -empty path, the method considers any items in the data store to be children and returns `true`. - -Here is the override for the -[System.Management.Automation.Provider.ContainerCmdletProvider.HasChildItems*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.HasChildItems) -method. If there are more than two path parts created by the ChunkPath helper method, the method -returns `false`, since only a database container and a table container are defined. For more -information about this helper method, see the ChunkPath method is discussed in -[Creating a Windows PowerShell Item Provider](./creating-a-windows-powershell-item-provider.md). - -```csharp -protected override bool HasChildItems( string path ) -{ - return false; -} // HasChildItems -``` - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/AccessDBProviderSample04/AccessDBProviderSample04.cs" range="1094-1097"::: - -#### Things to Remember About Implementing HasChildItems - -The following conditions may apply to your implementation of -[System.Management.Automation.Provider.ContainerCmdletProvider.HasChildItems*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.HasChildItems): - -- If the container provider exposes a root that contains interesting mount points, the - implementation of the - [System.Management.Automation.Provider.ContainerCmdletProvider.HasChildItems*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.HasChildItems) - method should return `true` when a null or an empty string is passed in for the path. - -## Copying Items - -To copy items, the container provider must implement the -[System.Management.Automation.Provider.ContainerCmdletProvider.CopyItem](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.CopyItem) -method to support calls from the `Copy-Item` cmdlet. This method copies a data item from the -location indicated by the `path` parameter of the cmdlet to the location indicated by the `copyPath` -parameter. If the `recurse` parameter is specified, the method copies all sub-containers. If the -parameter is not specified, the method copies only a single level of items. - -This provider does not implement this method. However, the following code is the default implementation of [System.Management.Automation.Provider.ContainerCmdletProvider.CopyItem](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.CopyItem). - - - -#### Things to Remember About Implementing CopyItem - -The following conditions may apply to your implementation of -[System.Management.Automation.Provider.ContainerCmdletProvider.CopyItem](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.CopyItem): - -- When defining the provider class, a Windows PowerShell container provider might declare provider - capabilities of ExpandWildcards, Filter, Include, or Exclude, from the - [System.Management.Automation.Provider.ProviderCapabilities](/dotnet/api/System.Management.Automation.Provider.ProviderCapabilities) - enumeration. In these cases, the implementation of the - [System.Management.Automation.Provider.ContainerCmdletProvider.GetChildItems*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.GetChildItems) - method needs to ensure that the path passed to the method meets the requirements of the specified - capabilities. To do this, the method should access the appropriate property, for example, the - [System.Management.Automation.Provider.CmdletProvider.Exclude*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Exclude) - and - [System.Management.Automation.Provider.CmdletProvider.Include*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Include) - properties. - -- By default, overrides of this method should not copy objects over existing objects unless the - [System.Management.Automation.Provider.CmdletProvider.Force*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Force) - property is set to `true`. For example, the FileSystem provider will not copy C:\temp\abc.txt over - an existing C:\abc.txt file unless the - [System.Management.Automation.Provider.CmdletProvider.Force*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Force) - property is set to `true`. If the path specified in the `copyPath` parameter exists and indicates - a container, the - [System.Management.Automation.Provider.CmdletProvider.Force*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Force) - property is not required. In this case, - [System.Management.Automation.Provider.ContainerCmdletProvider.CopyItem](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.CopyItem) - should copy the item indicated by the `path` parameter to the container indicated by the - `copyPath` parameter as a child. - -- Your implementation of - [System.Management.Automation.Provider.ContainerCmdletProvider.CopyItem](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.CopyItem) - is responsible for preventing infinite recursion when there are circular links, and the like. An - appropriate terminating exception should be thrown to reflect such a condition. - -- Your implementation of the - [System.Management.Automation.Provider.ContainerCmdletProvider.CopyItem](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.CopyItem) - method should call - [System.Management.Automation.Provider.CmdletProvider.ShouldProcess](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldProcess) - and check its return value before making any changes to the data store. After the call to - [System.Management.Automation.Provider.CmdletProvider.ShouldProcess](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldProcess) - returns true, the - [System.Management.Automation.Provider.ContainerCmdletProvider.CopyItem](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.CopyItem) - method should call the - [System.Management.Automation.Provider.CmdletProvider.ShouldContinue](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldContinue) - method as an additional check for potentially dangerous system modifications. For more information - about calling these methods, see [Rename Items](#renaming-items). - -## Attaching Dynamic Parameters to the Copy-Item Cmdlet - -Sometimes the `Copy-Item` cmdlet requires additional parameters that are specified dynamically at -runtime. To provide these dynamic parameters, the Windows PowerShell container provider must -implement the -[System.Management.Automation.Provider.ContainerCmdletProvider.CopyItemDynamicParameters*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.CopyItemDynamicParameters) -method to handle these parameters. This method retrieves the parameters for the item at the -indicated path and returns an object that has properties and fields with parsing attributes similar -to a cmdlet class or a -[System.Management.Automation.RuntimeDefinedParameterDictionary](/dotnet/api/System.Management.Automation.RuntimeDefinedParameterDictionary) -object. The Windows PowerShell runtime uses the returned object to add the parameters to the -`Copy-Item` cmdlet. - -This provider does not implement this method. However, the following code is the default -implementation of -[System.Management.Automation.Provider.ContainerCmdletProvider.CopyItemDynamicParameters*](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider.CopyItemDynamicParameters). - - - -## Code Sample - -For complete sample code, see -[AccessDbProviderSample04 Code Sample](./accessdbprovidersample04-code-sample.md). - -## Building the Windows PowerShell Provider - -See [How to Register Cmdlets, Providers, and Host Applications](/previous-versions/ms714644(v=vs.85)). - -## Testing the Windows PowerShell Provider - -When your Windows PowerShell provider has been registered with Windows PowerShell, you can test it -by running the supported cmdlets on the command line. Be aware that the following example output -uses a fictitious Access database. - -1. Run the `Get-ChildItem` cmdlet to retrieve the list of child items from a Customers table in the - Access database. - - ```powershell - Get-ChildItem mydb:customers - ``` - - The following output appears. - - ```output - PSPath : AccessDB::customers - PSDrive : mydb - PSProvider : System.Management.Automation.ProviderInfo - PSIsContainer : True - Data : System.Data.DataRow - Name : Customers - RowCount : 91 - Columns : - ``` - -2. Run the `Get-ChildItem` cmdlet again to retrieve the data of a table. - - ```powershell - (Get-ChildItem mydb:customers).Data - ``` - - The following output appears. - - ```output - TABLE_CAT : C:\PS\northwind - TABLE_SCHEM : - TABLE_NAME : Customers - TABLE_TYPE : TABLE - REMARKS : - ``` - -3. Now use the `Get-Item` cmdlet to retrieve the items at row 0 in the data table. - - ```powershell - Get-Item mydb:\customers\0 - ``` - - The following output appears. - - ```output - PSPath : AccessDB::customers\0 - PSDrive : mydb - PSProvider : System.Management.Automation.ProviderInfo - PSIsContainer : False - Data : System.Data.DataRow - RowNumber : 0 - ``` - -4. Reuse `Get-Item` to retrieve the data for the items in row 0. - - ```powershell - (Get-Item mydb:\customers\0).Data - ``` - - The following output appears. - - ```output - CustomerID : 1234 - CompanyName : Fabrikam - ContactName : Eric Gruber - ContactTitle : President - Address : 4567 Main Street - City : Buffalo - Region : NY - PostalCode : 98052 - Country : USA - Phone : (425) 555-0100 - Fax : (425) 555-0101 - ``` - -5. Now use the `New-Item` cmdlet to add a row to an existing table. The `Path` parameter specifies - the full path to the row, and must indicate a row number that is greater than the existing number - of rows in the table. The `Type` parameter indicates `Row` to specify that type of item to add. - Finally, the `Value` parameter specifies a comma-delimited list of column values for the row. - - ```powershell - New-Item -Path mydb:\Customers\3 -ItemType "Row" -Value "3,CustomerFirstName,CustomerLastName,CustomerEmailAddress,CustomerTitle,CustomerCompany,CustomerPhone, CustomerAddress,CustomerCity,CustomerState,CustomerZip,CustomerCountry" - ``` - -6. Verify the correctness of the new item operation as follows. - - ```none - PS mydb:\> cd Customers - PS mydb:\Customers> (Get-Item 3).Data - ``` - - The following output appears. - - ```output - ID : 3 - FirstName : Eric - LastName : Gruber - Email : ericgruber@fabrikam.com - Title : President - Company : Fabrikam - WorkPhone : (425) 555-0100 - Address : 4567 Main Street - City : Buffalo - State : NY - Zip : 98052 - Country : USA - ``` - -## See Also - -[Creating Windows PowerShell Providers](./how-to-create-a-windows-powershell-provider.md) - -[Designing Your Windows PowerShell Provider](./designing-your-windows-powershell-provider.md) - -[Implementing an Item Windows PowerShell Provider](./creating-a-windows-powershell-item-provider.md) - -[Implementing a Navigation Windows PowerShell Provider](./creating-a-windows-powershell-navigation-provider.md) - -[How to Register Cmdlets, Providers, and Host Applications](/previous-versions/ms714644(v=vs.85)) - -[Windows PowerShell SDK](../windows-powershell-reference.md) - -[Windows PowerShell Programmer's Guide](./windows-powershell-programmer-s-guide.md) diff --git a/reference/docs-conceptual/developer/prog-guide/creating-a-windows-powershell-content-provider.md b/reference/docs-conceptual/developer/prog-guide/creating-a-windows-powershell-content-provider.md deleted file mode 100644 index 4112b7a8c120..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/creating-a-windows-powershell-content-provider.md +++ /dev/null @@ -1,414 +0,0 @@ ---- -description: Creating a Windows PowerShell Content Provider -ms.date: 09/13/2016 -title: Creating a Windows PowerShell Content Provider ---- -# Creating a Windows PowerShell Content Provider - -This topic describes how to create a Windows PowerShell provider that enables the user to manipulate -the contents of the items in a data store. As a consequence, a provider that can manipulate the -contents of items is referred to as a Windows PowerShell content provider. - -> [!NOTE] -> You can download the C# source file (AccessDBSampleProvider06.cs) for this provider using the -> Microsoft Windows Software Development Kit for Windows Vista and .NET Framework 3.0 Runtime -> Components. For download instructions, see -> [How to Install Windows PowerShell and Download the Windows PowerShell SDK](/powershell/scripting/developer/installing-the-windows-powershell-sdk). -> The downloaded source files are available in the **\** directory. For more -> information about other Windows PowerShell provider implementations, see -> [Designing Your Windows PowerShell Provider](./designing-your-windows-powershell-provider.md). - -## Define the Windows PowerShell Content Provider Class - -A Windows PowerShell content provider must create a .NET class that supports the -[System.Management.Automation.Provider.IContentCmdletProvider](/dotnet/api/System.Management.Automation.Provider.IContentCmdletProvider) -interface. Here is the class definition for the item provider described in this section. - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/AccessDBProviderSample06/AccessDBProviderSample06.cs" range="32-33"::: - -Note that in this class definition, the -[System.Management.Automation.Provider.CmdletProviderAttribute](/dotnet/api/System.Management.Automation.Provider.CmdletProviderAttribute) -attribute includes two parameters. The first parameter specifies a user-friendly name for the -provider that is used by Windows PowerShell. The second parameter specifies the Windows PowerShell -specific capabilities that the provider exposes to the Windows PowerShell runtime during command -processing. For this provider, there are no added Windows PowerShell specific capabilities. - -## Define Functionality of Base Class - -As described in -[Design Your Windows PowerShell Provider](./designing-your-windows-powershell-provider.md), the -[System.Management.Automation.Provider.NavigationCmdletProvider](/dotnet/api/System.Management.Automation.Provider.NavigationCmdletProvider) -class derives from several other classes that provided different provider functionality. A Windows -PowerShell content provider, therefore, typically defines all of the functionality provided by those -classes. - -For more information about how to implement functionality for adding session-specific initialization -information and for releasing resources that are used by the provider, see -[Creating a Basic Windows PowerShell Provider](./creating-a-basic-windows-powershell-provider.md). -However, most providers, including the provider described here, can use the default implementation -of this functionality that is provided by Windows PowerShell. - -To access the data store, the provider must implement the methods of the -[System.Management.Automation.Provider.DriveCmdletProvider](/dotnet/api/System.Management.Automation.Provider.DriveCmdletProvider) -base class. For more information about implementing these methods, see -[Creating a Windows PowerShell Drive Provider](./creating-a-windows-powershell-drive-provider.md). - -To manipulate the items of a data store, such as getting, setting, and clearing items, the provider -must implement the methods provided by the -[System.Management.Automation.Provider.ItemCmdletProvider](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider) -base class. For more information about implementing these methods, see -[Creating a Windows PowerShell Item Provider](./creating-a-windows-powershell-item-provider.md). - -To work on multi-layer data stores, the provider must implement the methods provided by the -[System.Management.Automation.Provider.ContainerCmdletProvider](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider) -base class. For more information about implementing these methods, see -[Creating a Windows PowerShell Container Provider](./creating-a-windows-powershell-container-provider.md). - -To support recursive commands, nested containers, and relative paths, the provider must implement -the -[System.Management.Automation.Provider.NavigationCmdletProvider](/dotnet/api/System.Management.Automation.Provider.NavigationCmdletProvider) -base class. In addition, this Windows PowerShell content provider can attaches -[System.Management.Automation.Provider.IContentCmdletProvider](/dotnet/api/System.Management.Automation.Provider.IContentCmdletProvider) -interface to the -[System.Management.Automation.Provider.NavigationCmdletProvider](/dotnet/api/System.Management.Automation.Provider.NavigationCmdletProvider) -base class, and must therefore implement the methods provided by that class. For more information, -see implementing those methods, see -[Implement a Navigation Windows PowerShell Provider](./creating-a-windows-powershell-navigation-provider.md). - -## Implementing a Content Reader - -To read content from an item, a provider must implements a content reader class that derives from -[System.Management.Automation.Provider.IContentReader](/dotnet/api/System.Management.Automation.Provider.IContentReader). -The content reader for this provider allows access to the contents of a row in a data table. The -content reader class defines a **Read** method that retrieves the data from the indicated row and -returns a list representing that data, a **Seek** method that moves the content reader, a **Close** -method that closes the content reader, and a **Dispose** method. - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/AccessDBProviderSample06/AccessDBProviderSample06.cs" range="2115-2241"::: - -## Implementing a Content Writer - -To write content to an item, a provider must implement a content writer class derives from -[System.Management.Automation.Provider.IContentWriter](/dotnet/api/System.Management.Automation.Provider.IContentWriter). -The content writer class defines a **Write** method that writes the specified row content, a -**Seek** method that moves the content writer, a **Close** method that closes the content writer, -and a **Dispose** method. - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/AccessDBProviderSample06/AccessDBProviderSample06.cs" range="2250-2394"::: - -## Retrieving the Content Reader - -To get content from an item, the provider must implement the -[System.Management.Automation.Provider.IContentCmdletProvider.GetContentReader*](/dotnet/api/System.Management.Automation.Provider.IContentCmdletProvider.GetContentReader) -to support the `Get-Content` cmdlet. This method returns the content reader for the item located at -the specified path. The reader object can then be opened to read the content. - -Here is the implementation of -[System.Management.Automation.Provider.IContentCmdletProvider.GetContentReader*](/dotnet/api/System.Management.Automation.Provider.IContentCmdletProvider.GetContentReader) -for this method for this provider. - -```csharp -public IContentReader GetContentReader(string path) -{ - string tableName; - int rowNumber; - - PathType type = GetNamesFromPath(path, out tableName, out rowNumber); - - if (type == PathType.Invalid) - { - ThrowTerminatingInvalidPathException(path); - } - else if (type == PathType.Row) - { - throw new InvalidOperationException("contents can be obtained only for tables"); - } - - return new AccessDBContentReader(path, this); -} // GetContentReader -``` - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/AccessDBProviderSample06/AccessDBProviderSample06.cs" range="1829-1846"::: - -#### Things to Remember About Implementing GetContentReader - -The following conditions may apply to an implementation of -[System.Management.Automation.Provider.IContentCmdletProvider.GetContentReader*](/dotnet/api/System.Management.Automation.Provider.IContentCmdletProvider.GetContentReader): - -- When defining the provider class, a Windows PowerShell content provider might declare provider - capabilities of ExpandWildcards, Filter, Include, or Exclude, from the - [System.Management.Automation.Provider.ProviderCapabilities](/dotnet/api/System.Management.Automation.Provider.ProviderCapabilities) - enumeration. In these cases, the implementation of the - [System.Management.Automation.Provider.IContentCmdletProvider.GetContentReader*](/dotnet/api/System.Management.Automation.Provider.IContentCmdletProvider.GetContentReader) - method must ensure that the path passed to the method meets the requirements of the specified - capabilities. To do this, the method should access the appropriate property, for example, the - [System.Management.Automation.Provider.CmdletProvider.Exclude*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Exclude) - and - [System.Management.Automation.Provider.CmdletProvider.Include*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Include) - properties. - -- By default, overrides of this method should not retrieve a reader for objects that are hidden from - the user unless the - [System.Management.Automation.Provider.CmdletProvider.Force*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Force) - property is set to `true`. An error should be written if the path represents an item that is - hidden from the user and - [System.Management.Automation.Provider.CmdletProvider.Force*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Force) - is set to `false`. - -## Attaching Dynamic Parameters to the Get-Content Cmdlet - -The `Get-Content` cmdlet might require additional parameters that are specified dynamically at -runtime. To provide these dynamic parameters, the Windows PowerShell content provider must implement -the -[System.Management.Automation.Provider.IContentCmdletProvider.GetContentReaderdynamicparameters*](/dotnet/api/System.Management.Automation.Provider.IContentCmdletProvider.GetContentReaderDynamicParameters) -method. This method retrieves dynamic parameters for the item at the indicated path and returns an -object that has properties and fields with parsing attributes similar to a cmdlet class or a -[System.Management.Automation.RuntimeDefinedParameterDictionary](/dotnet/api/System.Management.Automation.RuntimeDefinedParameterDictionary) -object. The Windows PowerShell runtime uses the returned object to add the parameters to the cmdlet. - -This Windows PowerShell container provider does not implement this method. However, the following -code is the default implementation of this method. - -```csharp -public object GetContentReaderDynamicParameters(string path) -{ - return null; -} -``` - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/AccessDBProviderSample06/AccessDBProviderSample06.cs" range="1853-1856"::: - -## Retrieving the Content Writer - -To write content to an item, the provider must implement the -[System.Management.Automation.Provider.IContentCmdletProvider.GetContentWriter*](/dotnet/api/System.Management.Automation.Provider.IContentCmdletProvider.GetContentWriter) -to support the `Set-Content` and `Add-Content` cmdlets. This method returns the content writer for -the item located at the specified path. - -Here is the implementation of -[System.Management.Automation.Provider.IContentCmdletProvider.GetContentWriter*](/dotnet/api/System.Management.Automation.Provider.IContentCmdletProvider.GetContentWriter) -for this method. - -```csharp -public IContentWriter GetContentWriter(string path) -{ - string tableName; - int rowNumber; - - PathType type = GetNamesFromPath(path, out tableName, out rowNumber); - - if (type == PathType.Invalid) - { - ThrowTerminatingInvalidPathException(path); - } - else if (type == PathType.Row) - { - throw new InvalidOperationException("contents can be added only to tables"); - } - - return new AccessDBContentWriter(path, this); -} -``` - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/AccessDBProviderSample06/AccessDBProviderSample06.cs" range="1863-1880"::: - -#### Things to Remember About Implementing GetContentWriter - -The following conditions may apply to your implementation of -[System.Management.Automation.Provider.IContentCmdletProvider.GetContentWriter*](/dotnet/api/System.Management.Automation.Provider.IContentCmdletProvider.GetContentWriter): - -- When defining the provider class, a Windows PowerShell content provider might declare provider - capabilities of ExpandWildcards, Filter, Include, or Exclude, from the - [System.Management.Automation.Provider.ProviderCapabilities](/dotnet/api/System.Management.Automation.Provider.ProviderCapabilities) - enumeration. In these cases, the implementation of the - [System.Management.Automation.Provider.IContentCmdletProvider.GetContentWriter*](/dotnet/api/System.Management.Automation.Provider.IContentCmdletProvider.GetContentWriter) - method must ensure that the path passed to the method meets the requirements of the specified - capabilities. To do this, the method should access the appropriate property, for example, the - [System.Management.Automation.Provider.CmdletProvider.Exclude*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Exclude) - and - [System.Management.Automation.Provider.CmdletProvider.Include*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Include) - properties. - -- By default, overrides of this method should not retrieve a writer for objects that are hidden from - the user unless the - [System.Management.Automation.Provider.CmdletProvider.Force*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Force) - property is set to `true`. An error should be written if the path represents an item that is - hidden from the user and - [System.Management.Automation.Provider.CmdletProvider.Force*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Force) - is set to `false`. - -## Attaching Dynamic Parameters to the Add-Content and Set-Content Cmdlets - -The `Add-Content` and `Set-Content` cmdlets might require additional dynamic parameters that are -added a runtime. To provide these dynamic parameters, the Windows PowerShell content provider must -implement the -[System.Management.Automation.Provider.IContentCmdletProvider.GetContentWriterDynamicParameters*](/dotnet/api/System.Management.Automation.Provider.IContentCmdletProvider.GetContentWriterDynamicParameters) -method to handle these parameters. This method retrieves dynamic parameters for the item at the -indicated path and returns an object that has properties and fields with parsing attributes similar -to a cmdlet class or a -[System.Management.Automation.RuntimeDefinedParameterDictionary](/dotnet/api/System.Management.Automation.RuntimeDefinedParameterDictionary) -object. The Windows PowerShell runtime uses the returned object to add the parameters to the -cmdlets. - -This Windows PowerShell container provider does not implement this method. However, the following -code is the default implementation of this method. - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/AccessDBProviderSample06/AccessDBProviderSample06.cs" range="1887-1890"::: - -## Clearing Content - -Your content provider implements the -[System.Management.Automation.Provider.IContentCmdletProvider.ClearContent*](/dotnet/api/System.Management.Automation.Provider.IContentCmdletProvider.ClearContent) -method in support of the `Clear-Content` cmdlet. This method removes the contents of the item at the -specified path, but leaves the item intact. - -Here is the implementation of the -[System.Management.Automation.Provider.IContentCmdletProvider.ClearContent*](/dotnet/api/System.Management.Automation.Provider.IContentCmdletProvider.ClearContent) -method for this provider. - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/AccessDBProviderSample06/AccessDBProviderSample06.cs" range="1775-1812"::: - -#### Things to Remember About Implementing ClearContent - -The following conditions may apply to an implementation of -[System.Management.Automation.Provider.IContentCmdletProvider.ClearContent*](/dotnet/api/System.Management.Automation.Provider.IContentCmdletProvider.ClearContent): - -- When defining the provider class, a Windows PowerShell content provider might declare provider - capabilities of ExpandWildcards, Filter, Include, or Exclude, from the - [System.Management.Automation.Provider.ProviderCapabilities](/dotnet/api/System.Management.Automation.Provider.ProviderCapabilities) - enumeration. In these cases, the implementation of the - [System.Management.Automation.Provider.IContentCmdletProvider.ClearContent*](/dotnet/api/System.Management.Automation.Provider.IContentCmdletProvider.ClearContent) - method must ensure that the path passed to the method meets the requirements of the specified - capabilities. To do this, the method should access the appropriate property, for example, the - [System.Management.Automation.Provider.CmdletProvider.Exclude*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Exclude) - and - [System.Management.Automation.Provider.CmdletProvider.Include*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Include) - properties. - -- By default, overrides of this method should not clear the contents of objects that are hidden from - the user unless the - [System.Management.Automation.Provider.CmdletProvider.Force*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Force) - property is set to `true`. An error should be written if the path represents an item that is - hidden from the user and - [System.Management.Automation.Provider.CmdletProvider.Force*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Force) - is set to `false`. - -- Your implementation of the - [System.Management.Automation.Provider.IContentCmdletProvider.ClearContent*](/dotnet/api/System.Management.Automation.Provider.IContentCmdletProvider.ClearContent) - method should call - [System.Management.Automation.Provider.CmdletProvider.ShouldProcess](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldProcess) - and verify its return value before making any changes to the data store. This method is used to - confirm execution of an operation when a change is made to the data store, such as clearing - content. The - [System.Management.Automation.Provider.CmdletProvider.ShouldProcess](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldProcess) - method sends the name of the resource to be changed to the user, with the Windows PowerShell - runtime handling any command-line settings or preference variables in determining what should be - displayed. - - After the call to - [System.Management.Automation.Provider.CmdletProvider.ShouldProcess](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldProcess) - returns `true`, the - [System.Management.Automation.Provider.IContentCmdletProvider.ClearContent*](/dotnet/api/System.Management.Automation.Provider.IContentCmdletProvider.ClearContent) - method should call the - [System.Management.Automation.Provider.CmdletProvider.ShouldContinue](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldContinue) - method. This method sends a message to the user to allow feedback to verify if the operation - should be continued. The call to - [System.Management.Automation.Provider.CmdletProvider.ShouldContinue](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldContinue) - allows an additional check for potentially dangerous system modifications. - -## Attaching Dynamic Parameters to the Clear-Content Cmdlet - -The `Clear-Content` cmdlet might require additional dynamic parameters that are added at runtime. To -provide these dynamic parameters, the Windows PowerShell content provider must implement the -[System.Management.Automation.Provider.IContentCmdletProvider.ClearContentDynamicParameters*](/dotnet/api/System.Management.Automation.Provider.IContentCmdletProvider.ClearContentDynamicParameters) -method to handle these parameters. This method retrieves the parameters for the item at the -indicated path. This method retrieves dynamic parameters for the item at the indicated path and -returns an object that has properties and fields with parsing attributes similar to a cmdlet class -or a -[System.Management.Automation.RuntimeDefinedParameterDictionary](/dotnet/api/System.Management.Automation.RuntimeDefinedParameterDictionary) -object. The Windows PowerShell runtime uses the returned object to add the parameters to the cmdlet. - -This Windows PowerShell container provider does not implement this method. However, the following code is the default implementation of this method. - -```csharp -public object ClearContentDynamicParameters(string path) -{ - return null; -} -``` - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/AccessDBProviderSample06/AccessDBProviderSample06.cs" range="1819-1822"::: - -## Code Sample - -For complete sample code, see [AccessDbProviderSample06 Code Sample](./accessdbprovidersample06-code-sample.md). - -## Defining Object Types and Formatting - -When writing a provider, it may be necessary to add members to existing objects or define new -objects. When this is done, you must create a Types file that Windows PowerShell can use to identify -the members of the object and a Format file that defines how the object is displayed. For more -information, see -[Extending Object Types and Formatting](/previous-versions/ms714665(v=vs.85)). - -## Building the Windows PowerShell Provider - -See [How to Register Cmdlets, Providers, and Host Applications](/previous-versions/ms714644(v=vs.85)). - -## Testing the Windows PowerShell Provider - -When your Windows PowerShell provider has been registered with Windows PowerShell, you can test it -by running the supported cmdlets on the command line. For example, test the sample content provider. - -Use the `Get-Content` cmdlet to retrieve the contents of specified item in the database table at the -path specified by the `Path` parameter. The `ReadCount` parameter specifies the number of items for -the defined content reader to read (default 1). With the following command entry, the cmdlet -retrieves two rows (items) from the table and displays their contents. Note that the following -example output uses a fictitious Access database. - -```powershell -Get-Content -Path mydb:\Customers -ReadCount 2 -``` - -```Output -ID : 1 -FirstName : Eric -LastName : Gruber -Email : ericgruber@fabrikam.com -Title : President -Company : Fabrikam -WorkPhone : (425) 555-0100 -Address : 4567 Main Street -City : Buffalo -State : NY -Zip : 98052 -Country : USA -ID : 2 -FirstName : Eva -LastName : Corets -Email : evacorets@cohowinery.com -Title : Sales Representative -Company : Coho Winery -WorkPhone : (360) 555-0100 -Address : 8910 Main Street -City : Cabmerlot -State : WA -Zip : 98089 -Country : USA -``` - -## See Also - -[Creating Windows PowerShell providers](./how-to-create-a-windows-powershell-provider.md) - -[Design Your Windows PowerShell provider](./designing-your-windows-powershell-provider.md) - -[Extending Object Types and Formatting](/previous-versions//ms714665(v=vs.85)) - -[Implement a Navigation Windows PowerShell provider](./creating-a-windows-powershell-navigation-provider.md) - -[How to Register Cmdlets, Providers, and Host Applications](/previous-versions/ms714644(v=vs.85)) - -[Windows PowerShell SDK](../windows-powershell-reference.md) - -[Windows PowerShell Programmer's Guide](./windows-powershell-programmer-s-guide.md) diff --git a/reference/docs-conceptual/developer/prog-guide/creating-a-windows-powershell-drive-provider.md b/reference/docs-conceptual/developer/prog-guide/creating-a-windows-powershell-drive-provider.md deleted file mode 100644 index c021c26f9f0b..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/creating-a-windows-powershell-drive-provider.md +++ /dev/null @@ -1,235 +0,0 @@ ---- -description: Creating a Windows PowerShell Drive Provider -ms.date: 09/13/2016 -title: Creating a Windows PowerShell Drive Provider -ms.custom: sfi-ropc-nochange ---- -# Creating a Windows PowerShell Drive Provider - -This topic describes how to create a Windows PowerShell drive provider that provides a way to access -a data store through a Windows PowerShell drive. This type of provider is also referred to as -Windows PowerShell drive providers. The Windows PowerShell drives used by the provider provide the -means to connect to the data store. - -The Windows PowerShell drive provider described here provides access to a Microsoft Access database. -For this provider, the Windows PowerShell drive represents the database (it is possible to add any -number of drives to a drive provider), the top-level containers of the drive represent the tables in -the database, and the items of the containers represent the rows in the tables. - -## Defining the Windows PowerShell Provider Class - -Your drive provider must define a .NET class that derives from the -[System.Management.Automation.Provider.DriveCmdletProvider](/dotnet/api/System.Management.Automation.Provider.DriveCmdletProvider) -base class. Here is the class definition for this drive provider: - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/AccessDBProviderSample02/AccessDBProviderSample02.cs" range="29-30"::: - -Notice that in this example, the -[System.Management.Automation.Provider.CmdletProviderAttribute](/dotnet/api/System.Management.Automation.Provider.CmdletProviderAttribute) -attribute specifies a user-friendly name for the provider and the Windows PowerShell specific -capabilities that the provider exposes to the Windows PowerShell runtime during command processing. -The possible values for the provider capabilities are defined by the -[System.Management.Automation.Provider.ProviderCapabilities](/dotnet/api/System.Management.Automation.Provider.ProviderCapabilities) -enumeration. This drive provider does not support any of these capabilities. - -## Defining Base Functionality - -As described in -[Design Your Windows PowerShell Provider](./designing-your-windows-powershell-provider.md), the -[System.Management.Automation.Provider.DriveCmdletProvider](/dotnet/api/System.Management.Automation.Provider.DriveCmdletProvider) -class derives from the -[System.Management.Automation.Provider.CmdletProvider](/dotnet/api/System.Management.Automation.Provider.CmdletProvider) -base class that defines the methods needed for initializing and uninitializing the provider. To -implement functionality for adding session-specific initialization information and for releasing -resources that are used by the provider, see -[Creating a Basic Windows PowerShell Provider](./creating-a-basic-windows-powershell-provider.md). -However, most providers (including the provider described here) can use the default implementation -of this functionality that is provided by Windows PowerShell. - -## Creating Drive State Information - -All Windows PowerShell providers are considered stateless, which means that your drive provider -needs to create any state information that is needed by the Windows PowerShell runtime when it calls -your provider. - -For this drive provider, state information includes the connection to the database that is kept as -part of the drive information. Here is code that shows how this information is stored in the -[System.Management.Automation.PSDriveinfo](/dotnet/api/System.Management.Automation.PSDriveInfo) -object that describes the drive: - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/AccessDBProviderSample02/AccessDBProviderSample02.cs" range="130-151"::: - -## Creating a Drive - -To allow the Windows PowerShell runtime to create a drive, the drive provider must implement the -[System.Management.Automation.Provider.DriveCmdletProvider.NewDrive*](/dotnet/api/System.Management.Automation.Provider.DriveCmdletProvider.NewDrive) -method. The following code shows the implementation of the -[System.Management.Automation.Provider.DriveCmdletProvider.NewDrive*](/dotnet/api/System.Management.Automation.Provider.DriveCmdletProvider.NewDrive) -method for this drive provider: - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/AccessDBProviderSample02/AccessDBProviderSample02.cs" range="42-84"::: - -Your override of this method should do the following: - -- Verify that the - [System.Management.Automation.PSDriveinfo.Root*](/dotnet/api/System.Management.Automation.PSDriveInfo.Root) - member exists and that a connection to the data store can be made. -- Create a drive and populate the connection member, in support of the `New-PSDrive` cmdlet. -- Validate the - [System.Management.Automation.PSDriveinfo](/dotnet/api/System.Management.Automation.PSDriveInfo) - object for the proposed drive. -- Modify the - [System.Management.Automation.PSDriveinfo](/dotnet/api/System.Management.Automation.PSDriveInfo) - object that describes the drive with any required performance or reliability information, or - provide extra data for callers using the drive. -- Handle failures using the - [System.Management.Automation.Provider.CmdletProvider.WriteError](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.WriteError) - method and then return `null`. - - This method returns either the drive information that was passed to the method or a - provider-specific version of it. - -## Attaching Dynamic Parameters to NewDrive - -The `New-PSDrive` cmdlet supported by your drive provider might require additional parameters. To -attach these dynamic parameters to the cmdlet, the provider implements the -[System.Management.Automation.Provider.DriveCmdletProvider.NewDriveDynamicParameters*](/dotnet/api/System.Management.Automation.Provider.DriveCmdletProvider.NewDriveDynamicParameters) -method. This method returns an object that has properties and fields with parsing attributes similar -to a cmdlet class or a -[System.Management.Automation.RuntimeDefinedParameterDictionary](/dotnet/api/System.Management.Automation.RuntimeDefinedParameterDictionary) -object. - -This drive provider does not override this method. However, the following code shows the default -implementation of this method: - - - -## Removing a Drive - -To close the database connection, the drive provider must implement the -[System.Management.Automation.Provider.DriveCmdletProvider.RemoveDrive*](/dotnet/api/System.Management.Automation.Provider.DriveCmdletProvider.RemoveDrive) -method. This method closes the connection to the drive after cleaning up any provider-specific -information. - -The following code shows the implementation of the -[System.Management.Automation.Provider.DriveCmdletProvider.RemoveDrive*](/dotnet/api/System.Management.Automation.Provider.DriveCmdletProvider.RemoveDrive) -method for this drive provider: - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/AccessDBProviderSample02/AccessDBProviderSample02.cs" range="91-116"::: - -If the drive can be removed, the method should return the information passed to the method through -the `drive` parameter. If the drive cannot be removed, the method should write an exception and then -return `null`. If your provider does not override this method, the default implementation of this -method just returns the drive information passed as input. - -## Initializing Default Drives - -Your drive provider implements the -[System.Management.Automation.Provider.DriveCmdletProvider.InitializeDefaultDrives*](/dotnet/api/System.Management.Automation.Provider.DriveCmdletProvider.InitializeDefaultDrives) -method to mount drives. For example, the Active Directory provider might mount a drive for the -default naming context if the computer is joined to a domain. - -This method returns a collection of drive information about the initialized drives, or an empty -collection. The call to this method is made after the Windows PowerShell runtime calls the -[System.Management.Automation.Provider.CmdletProvider.Start*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Start) -method to initialize the provider. - -This drive provider does not override the -[System.Management.Automation.Provider.DriveCmdletProvider.InitializeDefaultDrives*](/dotnet/api/System.Management.Automation.Provider.DriveCmdletProvider.InitializeDefaultDrives) -method. However, the following code shows the default implementation, which returns an empty drive -collection: - - - -#### Things to Remember About Implementing InitializeDefaultDrives - -All drive providers should mount a root drive to help the user with discoverability. The root drive -might list locations that serve as roots for other mounted drives. For example, the Active Directory -provider might create a drive that lists the naming contexts found in the `namingContext` attributes -on the root Distributed System Environment (DSE). This helps users discover mount points for other -drives. - -## Code Sample - -For complete sample code, see -[AccessDbProviderSample02 Code Sample](./accessdbprovidersample02-code-sample.md). - -## Testing the Windows PowerShell Drive Provider - -When your Windows PowerShell provider has been registered with Windows PowerShell, you can test it -by running the supported cmdlets on the command line, including any cmdlets made available by -derivation. Let's test the sample drive provider. - -1. Run the `Get-PSProvider` cmdlet to retrieve the list of providers to ensure that the AccessDB drive provider is present: - - **PS> `Get-PSProvider`** - - The following output appears: - - ```Output - Name Capabilities Drives - ---- ------------ ------ - AccessDB None {} - Alias ShouldProcess {Alias} - Environment ShouldProcess {Env} - FileSystem Filter, ShouldProcess {C, Z} - Function ShouldProcess {function} - Registry ShouldProcess {HKLM, HKCU} - ``` - -2. Ensure that a database server name (DSN) exists for the database by accessing the **Data - Sources** portion of the **Administrative Tools** for the operating system. In the **User DSN** - table, double-click **MS Access Database** and add the drive path `C:\ps\northwind.mdb`. - -3. Create a new drive using the sample drive provider: - - ```powershell - New-PSDrive -Name mydb -Root C:\ps\northwind.mdb -PSProvider AccessDb` - ``` - - The following output appears: - - ```Output - Name Provider Root CurrentLocation - ---- -------- ---- --------------- - mydb AccessDB C:\ps\northwind.mdb - ``` - -4. Validate the connection. Because the connection is defined as a member of the drive, you can - check it using the Get-PDDrive cmdlet. - - > [!NOTE] - > The user cannot yet interact with the provider as a drive, as the provider needs container - > functionality for that interaction. For more information, see - > [Creating a Windows PowerShell Container Provider](./creating-a-windows-powershell-container-provider.md). - - **PS> (Get-PSDrive mydb).Connection** - - The following output appears: - - ```Output - ConnectionString : Driver={Microsoft Access Driver (*.mdb)};DBQ=C:\ps\northwind.mdb - ConnectionTimeout : 15 - Database : C:\ps\northwind - DataSource : ACCESS - ServerVersion : 04.00.0000 - Driver : odbcjt32.dll - State : Open - Site : - Container : - ``` - -5. Remove the drive and exit the shell: - - ```powershell - PS> Remove-PSDrive mydb - PS> exit - ``` - -## See Also - -[Creating Windows PowerShell Providers](./how-to-create-a-windows-powershell-provider.md) - -[Design Your Windows PowerShell Provider](./designing-your-windows-powershell-provider.md) - -[Creating a Basic Windows PowerShell Provider](./creating-a-basic-windows-powershell-provider.md) diff --git a/reference/docs-conceptual/developer/prog-guide/creating-a-windows-powershell-item-provider.md b/reference/docs-conceptual/developer/prog-guide/creating-a-windows-powershell-item-provider.md deleted file mode 100644 index c50f9c84544b..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/creating-a-windows-powershell-item-provider.md +++ /dev/null @@ -1,491 +0,0 @@ ---- -description: Creating a Windows PowerShell item provider -ms.date: 09/13/2016 -title: Creating a Windows PowerShell item provider ---- -# Creating a Windows PowerShell item provider - -This topic describes how to create a Windows PowerShell provider that can manipulate the data in a -data store. In this topic, the elements of data in the store are referred to as the "items" of the -data store. As a consequence, a provider that can manipulate the data in the store is referred to as -a Windows PowerShell item provider. - -> [!NOTE] -> You can download the C# source file (`AccessDBSampleProvider03.cs`) for this provider using the -> Microsoft Windows Software Development Kit for Windows Vista and .NET Framework 3.0 Runtime -> Components. For download instructions, see -> [How to Install Windows PowerShell and Download the Windows PowerShell SDK](/powershell/scripting/developer/installing-the-windows-powershell-sdk). -> The downloaded source files are available in the `PowerShell Samples` directory. For more -> information about other Windows PowerShell provider implementations, see -> [Designing Your Windows PowerShell Provider](./designing-your-windows-powershell-provider.md). - -The Windows PowerShell item provider described in this topic gets items of data from an Access -database. In this case, an "item" is either a table in the Access database or a row in a table. - -## Defining the Windows PowerShell item provider class - -A Windows PowerShell item provider must define a .NET class that derives from the -[System.Management.Automation.Provider.ItemCmdletProvider](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider) -base class. The following is the class definition for the item provider described in this section. - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/AccessDBProviderSample03/AccessDBProviderSample03.cs" range="34-36"::: - -Note that in this class definition, the -[System.Management.Automation.Provider.CmdletProviderAttribute](/dotnet/api/System.Management.Automation.Provider.CmdletProviderAttribute) -attribute includes two parameters. The first parameter specifies a user-friendly name for the -provider that is used by Windows PowerShell. The second parameter specifies the Windows PowerShell -specific capabilities that the provider exposes to the Windows PowerShell runtime during command -processing. For this provider, there are no added Windows PowerShell specific capabilities. - -## Defining base functionality - -As described in -[Design Your Windows PowerShell Provider](./designing-your-windows-powershell-provider.md), the -[System.Management.Automation.Provider.DriveCmdletProvider](/dotnet/api/System.Management.Automation.Provider.DriveCmdletProvider) -class derives from several other classes that provided different provider functionality. A Windows -PowerShell item provider, therefore, must define all of the functionality provided by those classes. - -For more information about how to implement functionality for adding session-specific initialization -information and for releasing resources used by the provider, see -[Creating a Basic Windows PowerShell Provider](./creating-a-basic-windows-powershell-provider.md). -However, most providers, including the provider described here, can use the default implementation -of this functionality that is provided by Windows PowerShell. - -Before the Windows PowerShell item provider can manipulate the items in the store, it must implement -the methods of the -[System.Management.Automation.Provider.DriveCmdletProvider](/dotnet/api/System.Management.Automation.Provider.DriveCmdletProvider) -base class to access to the data store. For more information about implementing this class, see -[Creating a Windows PowerShell Drive Provider](./creating-a-windows-powershell-drive-provider.md). - -## Checking for path validity - -When looking for an item of data, the Windows PowerShell runtime furnishes a Windows PowerShell path -to the provider, as defined in the "PSPath Concepts" section of -[How Windows PowerShell Works](/previous-versions/ms714658(v=vs.85)). A Windows PowerShell item -provider must verify the syntactic and semantic validity of any path passed to it by implementing -the -[System.Management.Automation.Provider.ItemCmdletProvider.IsValidPath](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider.IsValidPath) -method. This method returns `true` if the path is valid, and `false` otherwise. Be aware that the -implementation of this method should not verify the existence of the item at the path, but only that -the path is syntactically and semantically correct. - -Here is the implementation of the -[System.Management.Automation.Provider.ItemCmdletProvider.IsValidPath](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider.IsValidPath) -method for this provider. Note that this implementation calls a **NormalizePath** helper method to -convert all separators in the path to a uniform one. - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/AccessDBProviderSample03/AccessDBProviderSample03.cs" range="274-298"::: - -## Determining if an item exists - -After verifying the path, the Windows PowerShell runtime must determine if an item of data exists at -that path. To support this type of query, the Windows PowerShell item provider implements the -[System.Management.Automation.Provider.ItemCmdletProvider.ItemExists](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider.ItemExists) -method. This method returns `true` an item is found at the specified path and `false` (default) -otherwise. - -Here is the implementation of the -[System.Management.Automation.Provider.ItemCmdletProvider.ItemExists](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider.ItemExists) -method for this provider. Note that this method calls the **PathIsDrive**, **ChunkPath**, and -**GetTable** helper methods, and uses a provider defined **DatabaseTableInfo** object. - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/AccessDBProviderSample03/AccessDBProviderSample03.cs" range="229-267"::: - -#### Things to remember about implementing ItemExists - -The following conditions may apply to your implementation of -[System.Management.Automation.Provider.ItemCmdletProvider.ItemExists](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider.ItemExists): - -- When defining the provider class, a Windows PowerShell item provider might declare provider - capabilities of `ExpandWildcards`, `Filter`, `Include`, or `Exclude`, from the - [System.Management.Automation.Provider.ProviderCapabilities](/dotnet/api/System.Management.Automation.Provider.ProviderCapabilities) - enumeration. In these cases, the implementation of the - [System.Management.Automation.Provider.ItemCmdletProvider.ItemExists](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider.ItemExists) - method must ensure that the path passed to the method meets the requirements of the specified - capabilities. To do this, the method should access the appropriate property, for example, the - [System.Management.Automation.Provider.CmdletProvider.Exclude](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Exclude) - and - [System.Management.Automation.Provider.CmdletProvider.Include](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Include) - properties. -- The implementation of this method should handle any form of access to the item that might make the - item visible to the user. For example, if a user has write access to a file through the FileSystem - provider (supplied by Windows PowerShell), but not read access, the file still exists and - [System.Management.Automation.Provider.ItemCmdletProvider.ItemExists](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider.ItemExists) - returns `true`. Your implementation might require checking a parent item to see if the child item - can be enumerated. - -## Attaching dynamic parameters to the Test-Path cmdlet - -Sometimes the `Test-Path` cmdlet that calls -[System.Management.Automation.Provider.ItemCmdletProvider.ItemExists](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider.ItemExists) -requires additional parameters that are specified dynamically at runtime. To provide these dynamic -parameters the Windows PowerShell item provider must implement the -[System.Management.Automation.Provider.ItemCmdletProvider.ItemExistsDynamicParameters](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider.ItemExistsDynamicParameters) -method. This method retrieves the dynamic parameters for the item at the indicated path and returns -an object that has properties and fields with parsing attributes similar to a cmdlet class or a -[System.Management.Automation.RuntimeDefinedParameterDictionary](/dotnet/api/System.Management.Automation.RuntimeDefinedParameterDictionary) -object. The Windows PowerShell runtime uses the returned object to add the parameters to the -`Test-Path` cmdlet. - -This Windows PowerShell item provider does not implement this method. However, the following code is -the default implementation of this method. - - - -## Retrieving an item - -To retrieve an item, the Windows PowerShell item provider must override -[System.Management.Automation.Provider.ItemCmdletProvider.GetItem](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider.GetItem) -method to support calls from the `Get-Item` cmdlet. This method writes the item using the -[System.Management.Automation.Provider.CmdletProvider.WriteItemObject](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.WriteItemObject) -method. - -Here is the implementation of the -[System.Management.Automation.Provider.ItemCmdletProvider.GetItem](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider.GetItem) -method for this provider. Note that this method uses the **GetTable** and **GetRow** helper methods -to retrieve items that are either tables in the Access database or rows in a data table. - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/AccessDBProviderSample03/AccessDBProviderSample03.cs" range="132-163"::: - -#### Things to remember about implementing GetItem - -The following conditions may apply to an implementation of -[System.Management.Automation.Provider.ItemCmdletProvider.GetItem](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider.GetItem): - -- When defining the provider class, a Windows PowerShell item provider might declare provider - capabilities of `ExpandWildcards`, `Filter`, `Include`, or `Exclude`, from the - [System.Management.Automation.Provider.ProviderCapabilities](/dotnet/api/System.Management.Automation.Provider.ProviderCapabilities) - enumeration. In these cases, the implementation of - [System.Management.Automation.Provider.ItemCmdletProvider.GetItem](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider.GetItem) - must ensure that the path passed to the method meets those requirements. To do this, the method - should access the appropriate property, for example, the - [System.Management.Automation.Provider.CmdletProvider.Exclude](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Exclude) - and - [System.Management.Automation.Provider.CmdletProvider.Include](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Include) - properties. - -- By default, overrides of this method should not retrieve objects that are generally hidden from - the user unless the - [System.Management.Automation.Provider.CmdletProvider.Force](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Force) - property is set to `true`. For example, the - [System.Management.Automation.Provider.ItemCmdletProvider.GetItem](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider.GetItem) - method for the FileSystem provider checks the - [System.Management.Automation.Provider.CmdletProvider.Force](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Force) - property before it attempts to call - [System.Management.Automation.Provider.CmdletProvider.WriteItemObject](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.WriteItemObject) - for hidden or system files. - -## Attaching dynamic parameters to the Get-Item cmdlet - -Sometimes the `Get-Item` cmdlet requires additional parameters that are specified dynamically at -runtime. To provide these dynamic parameters the Windows PowerShell item provider must implement the -[System.Management.Automation.Provider.ItemCmdletProvider.GetItemDynamicParameters](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider.GetItemDynamicParameters) -method. This method retrieves the dynamic parameters for the item at the indicated path and returns -an object that has properties and fields with parsing attributes similar to a cmdlet class or a -[System.Management.Automation.RuntimeDefinedParameterDictionary](/dotnet/api/System.Management.Automation.RuntimeDefinedParameterDictionary) -object. The Windows PowerShell runtime uses the returned object to add the parameters to the -`Get-Item` cmdlet. - -This provider does not implement this method. However, the following code is the default -implementation of this method. - - - -## Setting an item - -To set an item, the Windows PowerShell item provider must override the -[System.Management.Automation.Provider.ItemCmdletProvider.SetItem](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider.SetItem) -method to support calls from the `Set-Item` cmdlet. This method sets the value of the item at the -specified path. - -This provider does not provide an override for the -[System.Management.Automation.Provider.ItemCmdletProvider.SetItem](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider.SetItem) -method. However, the following is the default implementation of this method. - - - -#### Things to remember about implementing SetItem - -The following conditions may apply to your implementation of -[System.Management.Automation.Provider.ItemCmdletProvider.SetItem](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider.SetItem): - -- When defining the provider class, a Windows PowerShell item provider might declare provider - capabilities of `ExpandWildcards`, `Filter`, `Include`, or `Exclude`, from the - [System.Management.Automation.Provider.ProviderCapabilities](/dotnet/api/System.Management.Automation.Provider.ProviderCapabilities) - enumeration. In these cases, the implementation of - [System.Management.Automation.Provider.ItemCmdletProvider.SetItem](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider.SetItem) - must ensure that the path passed to the method meets those requirements. To do this, the method - should access the appropriate property, for example, the - [System.Management.Automation.Provider.CmdletProvider.Exclude](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Exclude) - and - [System.Management.Automation.Provider.CmdletProvider.Include](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Include) - properties. - -- By default, overrides of this method should not set or write objects that are hidden from the user - unless the - [System.Management.Automation.Provider.CmdletProvider.Force](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Force) - property is set to `true`. An error should be sent to the - [System.Management.Automation.Provider.CmdletProvider.WriteError](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.WriteError) - method if the path represents a hidden item and - [System.Management.Automation.Provider.CmdletProvider.Force](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Force) - is set to `false`. - -- Your implementation of the - [System.Management.Automation.Provider.ItemCmdletProvider.SetItem](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider.SetItem) - method should call - [System.Management.Automation.Provider.CmdletProvider.ShouldProcess](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldProcess) - and verify its return value before making any changes to the data store. This method is used to - confirm execution of an operation when a change is made to the data store, for example, deleting - files. The - [System.Management.Automation.Provider.CmdletProvider.ShouldProcess](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldProcess) - method sends the name of the resource to be changed to the user, with the Windows PowerShell - runtime taking into account any command-line settings or preference variables in determining what - should be displayed. - - After the call to - [System.Management.Automation.Provider.CmdletProvider.ShouldProcess](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldProcess) - returns `true`, the - [System.Management.Automation.Provider.ItemCmdletProvider.SetItem](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider.SetItem) - method should call the - [System.Management.Automation.Provider.CmdletProvider.ShouldContinue](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldContinue) - method. This method sends a message to the user to allow feedback to verify if the operation - should be continued. The call to - [System.Management.Automation.Provider.CmdletProvider.ShouldContinue](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldContinue) - allows an additional check for potentially dangerous system modifications. - -## Retrieving dynamic parameters for SetItem - -Sometimes the `Set-Item` cmdlet requires additional parameters that are specified dynamically at -runtime. To provide these dynamic parameters the Windows PowerShell item provider must implement the -[System.Management.Automation.Provider.ItemCmdletProvider.SetItemDynamicParameters](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider.SetItemDynamicParameters) -method. This method retrieves the dynamic parameters for the item at the indicated path and returns -an object that has properties and fields with parsing attributes similar to a cmdlet class or a -[System.Management.Automation.RuntimeDefinedParameterDictionary](/dotnet/api/System.Management.Automation.RuntimeDefinedParameterDictionary) -object. The Windows PowerShell runtime uses the returned object to add the parameters to the -`Set-Item` cmdlet. - -This provider does not implement this method. However, the following code is the default -implementation of this method. - - - -## Clearing an item - -To clear an item, the Windows PowerShell item provider implements the -[System.Management.Automation.Provider.ItemCmdletProvider.ClearItem](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider.ClearItem) -method to support calls from the `Clear-Item` cmdlet. This method erases the data item at the -specified path. - -This provider does not implement this method. However, the following code is the default -implementation of this method. - - - -#### Things to remember about implementing ClearItem - -The following conditions may apply to an implementation of -[System.Management.Automation.Provider.ItemCmdletProvider.ClearItem](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider.ClearItem): - -- When defining the provider class, a Windows PowerShell item provider might declare provider - capabilities of `ExpandWildcards`, `Filter`, `Include`, or `Exclude`, from the - [System.Management.Automation.Provider.ProviderCapabilities](/dotnet/api/System.Management.Automation.Provider.ProviderCapabilities) - enumeration. In these cases, the implementation of - [System.Management.Automation.Provider.ItemCmdletProvider.ClearItem](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider.ClearItem) - must ensure that the path passed to the method meets those requirements. To do this, the method - should access the appropriate property, for example, the - [System.Management.Automation.Provider.CmdletProvider.Exclude](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Exclude) - and - [System.Management.Automation.Provider.CmdletProvider.Include](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Include) - properties. - -- By default, overrides of this method should not set or write objects that are hidden from the user - unless the - [System.Management.Automation.Provider.CmdletProvider.Force](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Force) - property is set to `true`. An error should be sent to the - [System.Management.Automation.Provider.CmdletProvider.WriteError](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.WriteError) - method if the path represents an item that is hidden from the user and - [System.Management.Automation.Provider.CmdletProvider.Force](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Force) - is set to `false`. - -- Your implementation of the - [System.Management.Automation.Provider.ItemCmdletProvider.SetItem](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider.SetItem) - method should call - [System.Management.Automation.Provider.CmdletProvider.ShouldProcess](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldProcess) - and verify its return value before making any changes to the data store. This method is used to - confirm execution of an operation when a change is made to the data store, for example, deleting - files. The - [System.Management.Automation.Provider.CmdletProvider.ShouldProcess](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldProcess) - method sends the name of the resource to be changed to the user, with the Windows PowerShell - runtime and handle any command-line settings or preference variables in determining what should be - displayed. - - After the call to - [System.Management.Automation.Provider.CmdletProvider.ShouldProcess](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldProcess) - returns `true`, the - [System.Management.Automation.Provider.ItemCmdletProvider.SetItem](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider.SetItem) - method should call the - [System.Management.Automation.Provider.CmdletProvider.ShouldContinue](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldContinue) - method. This method sends a message to the user to allow feedback to verify if the operation - should be continued. The call to - [System.Management.Automation.Provider.CmdletProvider.ShouldContinue](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldContinue) - allows an additional check for potentially dangerous system modifications. - -## Retrieve dynamic parameters for ClearItem - -Sometimes the `Clear-Item` cmdlet requires additional parameters that are specified dynamically at -runtime. To provide these dynamic parameters the Windows PowerShell item provider must implement the -[System.Management.Automation.Provider.ItemCmdletProvider.ClearItemDynamicParameters](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider.ClearItemDynamicParameters) -method. This method retrieves the dynamic parameters for the item at the indicated path and returns -an object that has properties and fields with parsing attributes similar to a cmdlet class or a -[System.Management.Automation.RuntimeDefinedParameterDictionary](/dotnet/api/System.Management.Automation.RuntimeDefinedParameterDictionary) -object. The Windows PowerShell runtime uses the returned object to add the parameters to the -`Clear-Item` cmdlet. - -This item provider does not implement this method. However, the following code is the default -implementation of this method. - - - -## Performing a default action for an item - -A Windows PowerShell item provider can implement the -[System.Management.Automation.Provider.ItemCmdletProvider.InvokeDefaultAction](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider.InvokeDefaultAction) -method to support calls from the `Invoke-Item` cmdlet, which allows the provider to perform a -default action for the item at the specified path. For example, the FileSystem provider might use -this method to call **ShellExecute** for a specific item. - -This provider does not implement this method. However, the following code is the default -implementation of this method. - - - -#### Things to remember about implementing InvokeDefaultAction - -The following conditions may apply to an implementation of -[System.Management.Automation.Provider.ItemCmdletProvider.InvokeDefaultAction](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider.InvokeDefaultAction): - -- When defining the provider class, a Windows PowerShell item provider might declare provider - capabilities of `ExpandWildcards`, `Filter`, `Include`, or `Exclude`, from the - [System.Management.Automation.Provider.ProviderCapabilities](/dotnet/api/System.Management.Automation.Provider.ProviderCapabilities) - enumeration. In these cases, the implementation of - [System.Management.Automation.Provider.ItemCmdletProvider.InvokeDefaultAction](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider.InvokeDefaultAction) - must ensure that the path passed to the method meets those requirements. To do this, the method - should access the appropriate property, for example, the - [System.Management.Automation.Provider.CmdletProvider.Exclude](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Exclude) - and - [System.Management.Automation.Provider.CmdletProvider.Include](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Include) - properties. - -- By default, overrides of this method should not set or write objects hidden from the user unless - the - [System.Management.Automation.Provider.CmdletProvider.Force](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Force) - property is set to `true`. An error should be sent to the - [System.Management.Automation.Provider.CmdletProvider.WriteError](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.WriteError) - method if the path represents an item that is hidden from the user and - [System.Management.Automation.Provider.CmdletProvider.Force](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Force) - is set to `false`. - -## Retrieve dynamic parameters for InvokeDefaultAction - -Sometimes the `Invoke-Item` cmdlet requires additional parameters that are specified dynamically at -runtime. To provide these dynamic parameters the Windows PowerShell item provider must implement the -[System.Management.Automation.Provider.ItemCmdletProvider.InvokeDefaultActionDynamicParameters](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider.InvokeDefaultActionDynamicParameters) -method. This method retrieves the dynamic parameters for the item at the indicated path and returns -an object that has properties and fields with parsing attributes similar to a cmdlet class or a -[System.Management.Automation.RuntimeDefinedParameterDictionary](/dotnet/api/System.Management.Automation.RuntimeDefinedParameterDictionary) -object. The Windows PowerShell runtime uses the returned object to add the dynamic parameters to the -`Invoke-Item` cmdlet. - -This item provider does not implement this method. However, the following code is the default -implementation of this method. - - - -## Implementing helper methods and classes - -This item provider implements several helper methods and classes that are used by the public -override methods defined by Windows PowerShell. The code for these helper methods and classes are -shown in the [Code Sample](#code-sample) section. - -### NormalizePath method - -This item provider implements a **NormalizePath** helper method to ensure that the path has a -consistent format. The format specified uses a backslash (`\`) as a separator. - -### PathIsDrive method - -This item provider implements a **PathIsDrive** helper method to determine if the specified path is -actually the drive name. - -### ChunkPath method - -This item provider implements a **ChunkPath** helper method that breaks up the specified path so -that the provider can identify its individual elements. It returns an array composed of the path -elements. - -### GetTable method - -This item provider implements the **GetTables** helper method that returns a **DatabaseTableInfo** -object that represents information about the table specified in the call. - -### GetRow method - -The -[System.Management.Automation.Provider.ItemCmdletProvider.GetItem](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider.GetItem) -method of this item provider calls the **GetRows** helper method. This helper method retrieves a -**DatabaseRowInfo** object that represents information about the specified row in the table. - -### DatabaseTableInfo class - -This item provider defines a **DatabaseTableInfo** class that represents a collection of information -in a data table in the database. This class is similar to the -[System.IO.Directoryinfo](/dotnet/api/System.IO.DirectoryInfo) class. - -The sample item provider defines a **DatabaseTableInfo.GetTables** method that returns a collection -of table information objects defining the tables in the database. This method includes a -try/catch block to ensure that any database error shows up as a row with zero entries. - -### DatabaseRowInfo class - -This item provider defines the **DatabaseRowInfo** helper class that represents a row in a table of -the database. This class is similar to the [System.IO.FileInfo](/dotnet/api/System.IO.FileInfo) -class. - -The sample provider defines a **DatabaseRowInfo.GetRows** method to return a collection of row -information objects for the specified table. This method includes a try/catch block to trap -exceptions. Any errors will result in no row information. - -## Code sample - -For complete sample code, see [AccessDbProviderSample03 Code Sample](./accessdbprovidersample03-code-sample.md). - -## Defining object types and formatting - -When writing a provider, it may be necessary to add members to existing objects or define new -objects. When finished, create a Types file that Windows PowerShell can use to identify the members -of the object and a Format file that defines how the object is displayed. For more information, see -[Extending Object Types and Formatting](/previous-versions/ms714665(v=vs.85)). - -## Building the Windows PowerShell provider - -See -[How to Register Cmdlets, Providers, and Host Applications](/previous-versions/ms714644(v=vs.85)). - -## Testing the Windows PowerShell provider - -When this Windows PowerShell item provider is registered with Windows PowerShell, you can only test -the basic and drive functionality of the provider. To test the manipulation of items, you must also -implement container functionality described in -[Implementing a Container Windows PowerShell Provider](./creating-a-windows-powershell-container-provider.md). - -## See also - -- [Windows PowerShell SDK](../windows-powershell-reference.md) -- [Windows PowerShell Programmer's Guide](./windows-powershell-programmer-s-guide.md) -- [Creating Windows PowerShell Providers](./how-to-create-a-windows-powershell-provider.md) -- [Designing Your Windows PowerShell provider](./designing-your-windows-powershell-provider.md) -- [Extending Object Types and Formatting](/previous-versions/ms714665(v=vs.85)) -- [How Windows PowerShell Works](/previous-versions/ms714658(v=vs.85)) -- [Creating a Container Windows PowerShell provider](./creating-a-windows-powershell-container-provider.md) -- [Creating a Drive Windows PowerShell provider](./creating-a-windows-powershell-drive-provider.md) -- [How to Register Cmdlets, Providers, and Host Applications](/previous-versions/ms714644(v=vs.85)) diff --git a/reference/docs-conceptual/developer/prog-guide/creating-a-windows-powershell-navigation-provider.md b/reference/docs-conceptual/developer/prog-guide/creating-a-windows-powershell-navigation-provider.md deleted file mode 100644 index 81be59f885ad..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/creating-a-windows-powershell-navigation-provider.md +++ /dev/null @@ -1,447 +0,0 @@ ---- -description: Creating a Windows PowerShell Navigation Provider -ms.date: 09/13/2016 -title: Creating a Windows PowerShell Navigation Provider ---- -# Creating a Windows PowerShell Navigation Provider - -This topic describes how to create a Windows PowerShell navigation provider that can navigate the -data store. This type of provider supports recursive commands, nested containers, and relative -paths. - -> [!NOTE] -> You can download the C# source file (AccessDBSampleProvider05.cs) for this provider using the -> Microsoft Windows Software Development Kit for Windows Vista and .NET Framework 3.0 Runtime -> Components. For download instructions, see -> [How to Install Windows PowerShell and Download the Windows PowerShell SDK](/powershell/scripting/developer/installing-the-windows-powershell-sdk). -> The downloaded source files are available in the **\** directory. For more -> information about other Windows PowerShell provider implementations, see -> [Designing Your Windows PowerShell Provider](./designing-your-windows-powershell-provider.md). - -The provider described here enables the user handle an Access database as a drive so that the user -can navigate to the data tables in the database. When creating your own navigation provider, you can -implement methods that can make drive-qualified paths required for navigation, normalize relative -paths, move items of the data store, as well as methods that get child names, get the parent path of -an item, and test to identify if an item is a container. - -> [!CAUTION] -> Be aware that this design assumes a database that has a field with the name ID, and that the type -> of the field is LongInteger. - -## Define the Windows PowerShell provider - -A Windows PowerShell navigation provider must create a .NET class that derives from the -[System.Management.Automation.Provider.NavigationCmdletProvider](/dotnet/api/System.Management.Automation.Provider.NavigationCmdletProvider) -base class. Here is the class definition for the navigation provider described in this section. - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/AccessDBProviderSample05/AccessDBProviderSample05.cs" range="31-32"::: - -Note that in this provider, the -[System.Management.Automation.Provider.CmdletProviderAttribute](/dotnet/api/System.Management.Automation.Provider.CmdletProviderAttribute) -attribute includes two parameters. The first parameter specifies a user-friendly name for the -provider that is used by Windows PowerShell. The second parameter specifies the Windows PowerShell -specific capabilities that the provider exposes to the Windows PowerShell runtime during command -processing. For this provider, there are no Windows PowerShell specific capabilities that are added. - -## Defining Base Functionality - -As described in [Design Your PS Provider](./designing-your-windows-powershell-provider.md), the -[System.Management.Automation.Provider.NavigationCmdletProvider](/dotnet/api/System.Management.Automation.Provider.NavigationCmdletProvider) -base class derives from several other classes that provided different provider functionality. A -Windows PowerShell navigation provider, therefore, must define all of the functionality provided by -those classes. - -To implement functionality for adding session-specific initialization information and for releasing -resources that are used by the provider, see -[Creating a Basic PS Provider](./creating-a-basic-windows-powershell-provider.md). However, most -providers (including the provider described here) can use the default implementation of this -functionality provided by Windows PowerShell. - -To get access to the data store through a Windows PowerShell drive, you must implement the methods -of the -[System.Management.Automation.Provider.DriveCmdletProvider](/dotnet/api/System.Management.Automation.Provider.DriveCmdletProvider) -base class. For more information about implementing these methods, see -[Creating a Windows PowerShell Drive Provider](./creating-a-windows-powershell-drive-provider.md). - -To manipulate the items of a data store, such as getting, setting, and clearing items, the provider -must implement the methods provided by the -[System.Management.Automation.Provider.ItemCmdletProvider](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider) -base class. For more information about implementing these methods, see -[Creating a Windows PowerShell Item Provider](./creating-a-windows-powershell-item-provider.md). - -To get to the child items, or their names, of the data store, as well as methods that create, copy, -rename, and remove items, you must implement the methods provided by the -[System.Management.Automation.Provider.ContainerCmdletProvider](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider) -base class. For more information about implementing these methods, see -[Creating a Windows PowerShell Container Provider](./creating-a-windows-powershell-container-provider.md). - -## Creating a Windows PowerShell Path - -Windows PowerShell navigation provider use a provider-internal Windows PowerShell path to navigate -the items of the data store. To create a provider-internal path the provider must implement the -[System.Management.Automation.Provider.NavigationCmdletProvider.MakePath*](/dotnet/api/System.Management.Automation.Provider.NavigationCmdletProvider.MakePath) -method to supports calls from the Combine-Path cmdlet. This method combines a parent and child path -into a provider-internal path, using a provider-specific path separator between the parent and child -paths. - -The default implementation takes paths with "/" or "\\" as the path separator, normalizes the path -separator to "\\", combines the parent and child path parts with the separator between them, and -then returns a string that contains the combined paths. - -This navigation provider does not implement this method. However, the following code is the default -implementation of the -[System.Management.Automation.Provider.NavigationCmdletProvider.MakePath*](/dotnet/api/System.Management.Automation.Provider.NavigationCmdletProvider.MakePath) -method. - - - -#### Things to Remember About Implementing MakePath - -The following conditions may apply to your implementation of -[System.Management.Automation.Provider.NavigationCmdletProvider.MakePath*](/dotnet/api/System.Management.Automation.Provider.NavigationCmdletProvider.MakePath): - -- Your implementation of the - [System.Management.Automation.Provider.NavigationCmdletProvider.MakePath*](/dotnet/api/System.Management.Automation.Provider.NavigationCmdletProvider.MakePath) - method should not validate the path as a legal fully-qualified path in the provider namespace. Be - aware that each parameter can only represent a part of a path, and the combined parts might not - generate a fully-qualified path. For example, the - [System.Management.Automation.Provider.NavigationCmdletProvider.MakePath*](/dotnet/api/System.Management.Automation.Provider.NavigationCmdletProvider.MakePath) - method for the FileSystem provider might receive "windows\system32" in the `parent` parameter and - "abc.dll" in the `child` parameter. The method joins these values with the "\\" separator and - returns "windows\system32\abc.dll", which is not a fully-qualified file system path. - - > [!IMPORTANT] - > The path parts provided in the call to - > [System.Management.Automation.Provider.NavigationCmdletProvider.MakePath*](/dotnet/api/System.Management.Automation.Provider.NavigationCmdletProvider.MakePath) - > might contain characters not allowed in the provider namespace. These characters are most likely - > used for wildcard expansion and the implementation of this method should not remove them. - -## Retrieving the Parent Path - -Windows PowerShell navigation providers implement the -[System.Management.Automation.Provider.NavigationCmdletProvider.GetParentPath*](/dotnet/api/System.Management.Automation.Provider.NavigationCmdletProvider.GetParentPath) -method to retrieve the parent part of the indicated full or partial provider-specific path. The -method removes the child part of the path and returns the parent path part. The `root` parameter -specifies the fully-qualified path to the root of a drive. This parameter can be null or empty if a -mounted drive is not in use for the retrieval operation. If a root is specified, the method must -return a path to a container in the same tree as the root. - -The sample navigation provider does not override this method, but uses the default implementation. -It accepts paths that use both "/" and "\\" as path separators. It first normalizes the path to have -only "\\" separators, then splits the parent path off at the last "\\" and returns the parent path. - - - -#### To Remember About Implementing GetParentPath - -Your implementation of the -[System.Management.Automation.Provider.NavigationCmdletProvider.GetParentPath*](/dotnet/api/System.Management.Automation.Provider.NavigationCmdletProvider.GetParentPath) -method should split the path lexically on the path separator for the provider namespace. For -example, the FileSystem provider uses this method to look for the last "\\" and returns everything -to the left of the separator. - -## Retrieve the Child Path Name - -Your navigation provider implements the -[System.Management.Automation.Provider.NavigationCmdletProvider.GetChildName*](/dotnet/api/System.Management.Automation.Provider.NavigationCmdletProvider.GetChildName) -method to retrieve the name (leaf element) of the child of the item located at the indicated full or -partial provider-specific path. - -The sample navigation provider does not override this method. The default implementation is shown -below. It accepts paths that use both "/" and "\\" as path separators. It first normalizes the path -to have only "\\" separators, then splits the parent path off at the last "\\" and returns the name -of the child path part. - - - -#### Things to Remember About Implementing GetChildName - -Your implementation of the -[System.Management.Automation.Provider.NavigationCmdletProvider.GetChildName*](/dotnet/api/System.Management.Automation.Provider.NavigationCmdletProvider.GetChildName) -method should split the path lexically on the path separator. If the supplied path contains no path -separators, the method should return the path unmodified. - -> [!IMPORTANT] -> The path provided in the call to this method might contain characters that are illegal in the -> provider namespace. These characters are most likely used for wildcard expansion or regular -> expression matching, and the implementation of this method should not remove them. - -## Determining if an Item is a Container - -The navigation provider can implement the -[System.Management.Automation.Provider.NavigationCmdletProvider.IsItemContainer*](/dotnet/api/System.Management.Automation.Provider.NavigationCmdletProvider.IsItemContainer) -method to determine if the specified path indicates a container. It returns true if the path -represents a container, and false otherwise. The user needs this method to be able to use the -`Test-Path` cmdlet for the supplied path. - -The following code shows the -[System.Management.Automation.Provider.NavigationCmdletProvider.IsItemContainer*](/dotnet/api/System.Management.Automation.Provider.NavigationCmdletProvider.IsItemContainer) -implementation in our sample navigation provider. The method verifies that the specified path is -correct and if the table exists, and returns true if the path indicates a container. - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/AccessDBProviderSample05/AccessDBProviderSample05.cs" range="847-872"::: - -#### Things to Remember About Implementing IsItemContainer - -Your navigation provider .NET class might declare provider capabilities of ExpandWildcards, Filter, -Include, or Exclude, from the -[System.Management.Automation.Provider.ProviderCapabilities](/dotnet/api/System.Management.Automation.Provider.ProviderCapabilities) -enumeration. In this case, the implementation of -[System.Management.Automation.Provider.NavigationCmdletProvider.IsItemContainer*](/dotnet/api/System.Management.Automation.Provider.NavigationCmdletProvider.IsItemContainer) -needs to ensure that the path passed meets requirements. To do this, the method should access the -appropriate property, for example, the -[System.Management.Automation.Provider.CmdletProvider.Exclude*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Exclude) -property. - -## Moving an Item - -In support of the `Move-Item` cmdlet, your navigation provider implements the -[System.Management.Automation.Provider.NavigationCmdletProvider.MoveItem*](/dotnet/api/System.Management.Automation.Provider.NavigationCmdletProvider.MoveItem) -method. This method moves the item specified by the `path` parameter to the container at the path -supplied in the `destination` parameter. - -The sample navigation provider does not override the [System.Management.Automation.Provider.NavigationCmdletProvider.MoveItem*](/dotnet/api/System.Management.Automation.Provider.NavigationCmdletProvider.MoveItem) method. The following is the default implementation. - - - -#### Things to Remember About Implementing MoveItem - -Your navigation provider .NET class might declare provider capabilities of ExpandWildcards, Filter, -Include, or Exclude, from the -[System.Management.Automation.Provider.ProviderCapabilities](/dotnet/api/System.Management.Automation.Provider.ProviderCapabilities) -enumeration. In this case, the implementation of -[System.Management.Automation.Provider.NavigationCmdletProvider.MoveItem*](/dotnet/api/System.Management.Automation.Provider.NavigationCmdletProvider.MoveItem) -must ensure that the path passed meets requirements. To do this, the method should access the -appropriate property, for example, the **CmdletProvider.Exclude** property. - -By default, overrides of this method should not move objects over existing objects unless the -[System.Management.Automation.Provider.CmdletProvider.Force*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Force) -property is set to `true`. For example, the FileSystem provider will not copy C:\temp\abc.txt over -an existing C:\bar.txt file unless the -[System.Management.Automation.Provider.CmdletProvider.Force*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Force) -property is set to `true`. If the path specified in the `destination` parameter exists and is a -container, the -[System.Management.Automation.Provider.CmdletProvider.Force*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Force) -property is not required. In this case, -[System.Management.Automation.Provider.NavigationCmdletProvider.MoveItem*](/dotnet/api/System.Management.Automation.Provider.NavigationCmdletProvider.MoveItem) -should move the item indicated by the `path` parameter to the container indicated by the -`destination` parameter as a child. - -Your implementation of the -[System.Management.Automation.Provider.NavigationCmdletProvider.MoveItem*](/dotnet/api/System.Management.Automation.Provider.NavigationCmdletProvider.MoveItem) -method should call -[System.Management.Automation.Provider.CmdletProvider.ShouldProcess](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldProcess) -and check its return value before making any changes to the data store. This method is used to -confirm execution of an operation when a change is made to system state, for example, deleting -files. -[System.Management.Automation.Provider.CmdletProvider.ShouldProcess](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldProcess) -sends the name of the resource to be changed to the user, with the Windows PowerShell runtime taking -into account any command line settings or preference variables in determining what should be -displayed to the user. - -After the call to -[System.Management.Automation.Provider.CmdletProvider.ShouldProcess](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldProcess) -returns `true`, the -[System.Management.Automation.Provider.NavigationCmdletProvider.MoveItem*](/dotnet/api/System.Management.Automation.Provider.NavigationCmdletProvider.MoveItem) -method should call the -[System.Management.Automation.Provider.CmdletProvider.ShouldContinue](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldContinue) -method. This method sends a message to the user to allow feedback to say if the operation should be -continued. Your provider should call -[System.Management.Automation.Provider.CmdletProvider.ShouldContinue](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldContinue) -as an additional check for potentially dangerous system modifications. - -## Attaching Dynamic Parameters to the Move-Item Cmdlet - -Sometimes the `Move-Item` cmdlet requires additional parameters that are provided dynamically at -runtime. To provide these dynamic parameters, the navigation provider must implement the -[System.Management.Automation.Provider.NavigationCmdletProvider.MoveItemDynamicParameters*](/dotnet/api/System.Management.Automation.Provider.NavigationCmdletProvider.MoveItemDynamicParameters) -method to get the required parameter values from the item at the indicated path, and return an -object that has properties and fields with parsing attributes similar to a cmdlet class or a -[System.Management.Automation.RuntimeDefinedParameterDictionary](/dotnet/api/System.Management.Automation.RuntimeDefinedParameterDictionary) -object. - -This navigation provider does not implement this method. However, the following code is the default -implementation of -[System.Management.Automation.Provider.NavigationCmdletProvider.MoveItemDynamicParameters*](/dotnet/api/System.Management.Automation.Provider.NavigationCmdletProvider.MoveItemDynamicParameters). - - - -## Normalizing a Relative Path - -Your navigation provider implements the -[System.Management.Automation.Provider.NavigationCmdletProvider.NormalizeRelativePath*](/dotnet/api/System.Management.Automation.Provider.NavigationCmdletProvider.NormalizeRelativePath) -method to normalize the fully-qualified path indicated in the `path` parameter as being relative to -the path specified by the `basePath` parameter. The method returns a string representation of the -normalized path. It writes an error if the `path` parameter specifies a nonexistent path. - -The sample navigation provider does not override this method. The following is the default implementation. - - - -#### Things to Remember About Implementing NormalizeRelativePath - -Your implementation of -[System.Management.Automation.Provider.NavigationCmdletProvider.NormalizeRelativePath*](/dotnet/api/System.Management.Automation.Provider.NavigationCmdletProvider.NormalizeRelativePath) -should parse the `path` parameter, but it does not have to use purely syntactical parsing. You are -encouraged to design this method to use the path to look up the path information in the data store -and create a path that matches the casing and standardized path syntax. - -## Code Sample - -For complete sample code, see [AccessDbProviderSample05 Code Sample](./accessdbprovidersample05-code-sample.md). - -## Defining Object Types and Formatting - -It is possible for a provider to add members to existing objects or define new objects. For more -information, -see[Extending Object Types and Formatting](/previous-versions/ms714665(v=vs.85)). - -## Building the Windows PowerShell provider - -For more information, see -[How to Register Cmdlets, Providers, and Host Applications](/previous-versions/ms714644(v=vs.85)). - -## Testing the Windows PowerShell provider - -When your Windows PowerShell provider has been registered with Windows PowerShell, you can test it -by running the supported cmdlets on the command line, including cmdlets made available by -derivation. This example will test the sample navigation provider. - -1. Run your new shell and use the `Set-Location` cmdlet to set the path to indicate the Access - database. - - ```powershell - Set-Location mydb: - ``` - -2. Now run the `Get-ChildItem` cmdlet to retrieve a list of the database items, which are the - available database tables. For each table, this cmdlet also retrieves the number of table rows. - - ```powershell - Get-ChildItem | Format-Table RowCount, Name -AutoSize - ``` - - ```Output - RowCount Name - -------- ---- - 180 MSysAccessObjects - 0 MSysACEs - 1 MSysCmdbars - 0 MSysIMEXColumns - 0 MSysIMEXSpecs - 0 MSysObjects - 0 MSysQueries - 7 MSysRelationships - 8 Categories - 91 Customers - 9 Employees - 2155 Order Details - 830 Orders - 77 Products - 3 Shippers - 29 Suppliers - ``` - -3. Use the `Set-Location` cmdlet again to set the location of the Employees data table. - - ```powershell - Set-Location Employees - ``` - -4. Let's now use the `Get-Location` cmdlet to retrieve the path to the Employees table. - - ```powershell - Get-Location - ``` - - ```Output - Path - ---- - mydb:\Employees - ``` - -5. Now use the `Get-ChildItem` cmdlet piped to the `Format-Table` cmdlet. This set of cmdlets - retrieves the items for the Employees data table, which are the table rows. They are formatted as - specified by the `Format-Table` cmdlet. - - ```powershell - Get-ChildItem | Format-Table RowNumber, PSIsContainer, Data -AutoSize - ``` - - ```Output - RowNumber PSIsContainer Data - --------- -------------- ---- - 0 False System.Data.DataRow - 1 False System.Data.DataRow - 2 False System.Data.DataRow - 3 False System.Data.DataRow - 4 False System.Data.DataRow - 5 False System.Data.DataRow - 6 False System.Data.DataRow - 7 False System.Data.DataRow - 8 False System.Data.DataRow - ``` - -6. You can now run the `Get-Item` cmdlet to retrieve the items for row 0 of the Employees data - table. - - ```powershell - Get-Item 0 - ``` - - ```Output - PSPath : AccessDB::C:\PS\Northwind.mdb\Employees\0 - PSParentPath : AccessDB::C:\PS\Northwind.mdb\Employees - PSChildName : 0 - PSDrive : mydb - PSProvider : System.Management.Automation.ProviderInfo - PSIsContainer : False - Data : System.Data.DataRow - RowNumber : 0 - ``` - -7. Use the `Get-Item` cmdlet again to retrieve the employee data for the items in row 0. - - ```powershell - (Get-Item 0).Data - ``` - - ```Output - EmployeeID : 1 - LastName : Davis - FirstName : Sara - Title : Sales Representative - TitleOfCourtesy : Ms. - BirthDate : 12/8/1968 12:00:00 AM - HireDate : 5/1/1992 12:00:00 AM - Address : 4567 Main Street - Apt. 2A - City : Buffalo - Region : NY - PostalCode : 98052 - Country : USA - HomePhone : (206) 555-9857 - Extension : 5467 - Photo : EmpID1.bmp - Notes : Education includes a BA in psychology from - Colorado State University. She also completed "The - Art of the Cold Call." Nancy is a member of - Toastmasters International. - ReportsTo : 2 - ``` - -## See Also - -[Creating Windows PowerShell providers](./how-to-create-a-windows-powershell-provider.md) - -[Design Your Windows PowerShell provider](./designing-your-windows-powershell-provider.md) - -[Extending Object Types and Formatting](/previous-versions/ms714665(v=vs.85)) - -[Implement a Container Windows PowerShell provider](./creating-a-windows-powershell-container-provider.md) - -[How to Register Cmdlets, Providers, and Host Applications](/previous-versions/ms714644(v=vs.85)) - -[Windows PowerShell Programmer's Guide](./windows-powershell-programmer-s-guide.md) - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/creating-a-windows-powershell-property-provider.md b/reference/docs-conceptual/developer/prog-guide/creating-a-windows-powershell-property-provider.md deleted file mode 100644 index 52a96233f541..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/creating-a-windows-powershell-property-provider.md +++ /dev/null @@ -1,289 +0,0 @@ ---- -description: Creating a Windows PowerShell Property Provider -ms.date: 09/13/2016 -title: Creating a Windows PowerShell Property Provider ---- -# Creating a Windows PowerShell Property Provider - -This topic describes how to create a provider that enables the user to manipulate the properties of -items in a data store. As a consequence, this type of provider is referred to as a Windows -PowerShell property provider. For example, the Registry provider provided by Windows PowerShell -handles registry key values as properties of the registry key item. This type of provider must add -the -[System.Management.Automation.Provider.IPropertyCmdletProvider](/dotnet/api/System.Management.Automation.Provider.IPropertyCmdletProvider) -interface to the implementation of the .NET class. - -> [!NOTE] -> Windows PowerShell provides a template file that you can use to develop a Windows PowerShell -> provider. The TemplateProvider.cs file is available on the Microsoft Windows Software Development -> Kit for Windows Vista and .NET Framework 3.0 Runtime Components. For download instructions, see -> [How to Install Windows PowerShell and Download the Windows PowerShell SDK](/powershell/scripting/developer/installing-the-windows-powershell-sdk). -> The downloaded template is available in the **\** directory. You should make a -> copy of this file and use the copy for creating a new Windows PowerShell provider, removing any -> functionality that you do not need. For more information about other Windows PowerShell provider -> implementations, see -> [Designing Your Windows PowerShell Provider](./designing-your-windows-powershell-provider.md). - -> [!CAUTION] -> The methods of your property provider should write any objects using the -> [System.Management.Automation.Provider.CmdletProvider.Writepropertyobject*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.WritePropertyObject) -> method. - -## Defining the Windows PowerShell provider - -A property provider must create a .NET class that supports the -[System.Management.Automation.Provider.IPropertyCmdletProvider](/dotnet/api/System.Management.Automation.Provider.IPropertyCmdletProvider) -interface. Here is the default class declaration from the TemplateProvider.cs file provided by -Windows PowerShell. - - - -## Defining Base Functionality - -The -[System.Management.Automation.Provider.IPropertyCmdletProvider](/dotnet/api/System.Management.Automation.Provider.IPropertyCmdletProvider) -interface can be attached to any of the provider base classes, with the exception of the -[System.Management.Automation.Provider.DriveCmdletProvider](/dotnet/api/System.Management.Automation.Provider.DriveCmdletProvider) -class. Add the base functionality that is required by the base class you are using. For more -information about base classes, see -[Designing Your Windows PowerShell Provider](./designing-your-windows-powershell-provider.md). - -## Retrieving Properties - -To retrieve properties, the provider must implement the -[System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty*](/dotnet/api/System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty) -method to support calls from the `Get-ItemProperty` cmdlet. This method retrieves the properties of -the item located at the specified provider-internal path (fully-qualified). - -The `providerSpecificPickList` parameter indicates which properties to retrieve. If this parameter -is `null` or empty, the method should retrieve all properties. In addition, -[System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty*](/dotnet/api/System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty) -writes an instance of a -[System.Management.Automation.PSObject](/dotnet/api/System.Management.Automation.PSObject) object -that represents a property bag of the retrieved properties. The method should return nothing. - -It is recommended that the implementation of -[System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty*](/dotnet/api/System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty) -supports the wildcard expansion of property names for each element in the pick list. To do this, use -the -[System.Management.Automation.WildcardPattern](/dotnet/api/System.Management.Automation.WildcardPattern) -class to perform the wildcard pattern matching. - -Here is the default implementation of -[System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty*](/dotnet/api/System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty) -from the TemplateProvider.cs file provided by Windows PowerShell. - - - -#### Things to Remember About Implementing GetProperty - -The following conditions may apply to your implementation of -[System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty*](/dotnet/api/System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty): - -- When defining the provider class, a Windows PowerShell property provider might declare provider - capabilities of ExpandWildcards, Filter, Include, or Exclude, from the - [System.Management.Automation.Provider.ProviderCapabilities](/dotnet/api/System.Management.Automation.Provider.ProviderCapabilities) - enumeration. In these cases, the implementation of the - [System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty*](/dotnet/api/System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty) - method needs to ensure that the path passed to the method meets the requirements of the specified - capabilities. To do this, the method should access the appropriate property, for example, the - [System.Management.Automation.Provider.CmdletProvider.Exclude*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Exclude) - and - [System.Management.Automation.Provider.CmdletProvider.Include*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Include) - properties. - -- By default, overrides of this method should not retrieve a reader for objects that are hidden from - the user unless the - [System.Management.Automation.Provider.CmdletProvider.Force*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Force) - property is set to `true`. An error should be written if the path represents an item that is - hidden from the user and - [System.Management.Automation.Provider.CmdletProvider.Force*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Force) - is set to `false`. - -## Attaching Dynamic Parameters to the Get-ItemProperty Cmdlet - -The `Get-ItemProperty` cmdlet might require additional parameters that are specified dynamically at -runtime. To provide these dynamic parameters, the Windows PowerShell property provider must -implement the -[System.Management.Automation.Provider.IPropertyCmdletProvider.GetPropertyDynamicParameters*](/dotnet/api/System.Management.Automation.Provider.IPropertyCmdletProvider.GetPropertyDynamicParameters) -method. The `path` parameter indicates a fully-qualified provider-internal path, while the -`providerSpecificPickList` parameter specifies the provider-specific properties entered on the -command line. This parameter might be `null` or empty if the properties are piped to the cmdlet. In -this case, this method returns an object that has properties and fields with parsing attributes -similar to a cmdlet class or a -[System.Management.Automation.RuntimeDefinedParameterDictionary](/dotnet/api/System.Management.Automation.RuntimeDefinedParameterDictionary) -object. The Windows PowerShell runtime uses the returned object to add the parameters to the cmdlet. - -Here is the default implementation of -[System.Management.Automation.Provider.IPropertyCmdletProvider.GetPropertyDynamicParameters*](/dotnet/api/System.Management.Automation.Provider.IPropertyCmdletProvider.GetPropertyDynamicParameters) -from the TemplateProvider.cs file provided by Windows PowerShell. - - - -## Setting Properties - -To set properties, the Windows PowerShell property provider must implement the -[System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty*](/dotnet/api/System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty) -method to support calls from the `Set-ItemProperty` cmdlet. This method sets one or more properties -of the item at the specified path, and overwrites the supplied properties as required. -[System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty*](/dotnet/api/System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty) -also writes an instance of a -[System.Management.Automation.PSObject](/dotnet/api/System.Management.Automation.PSObject) object -that represents a property bag of the updated properties. - -Here is the default implementation of -[System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty*](/dotnet/api/System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty) -from the TemplateProvider.cs file provided by Windows PowerShell. - - - -#### Things to Remember About Implementing Set-ItemProperty - -The following conditions may apply to an implementation of -[System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty*](/dotnet/api/System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty): - -- When defining the provider class, a Windows PowerShell property provider might declare provider - capabilities of ExpandWildcards, Filter, Include, or Exclude, from the - [System.Management.Automation.Provider.ProviderCapabilities](/dotnet/api/System.Management.Automation.Provider.ProviderCapabilities) - enumeration. In these cases, the implementation of the - [System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty*](/dotnet/api/System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty) - method must ensure that the path passed to the method meets the requirements of the specified - capabilities. To do this, the method should access the appropriate property, for example, the - [System.Management.Automation.Provider.CmdletProvider.Exclude*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Exclude) - and - [System.Management.Automation.Provider.CmdletProvider.Include*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Include) - properties. - -- By default, overrides of this method should not retrieve a reader for objects that are hidden from - the user unless the - [System.Management.Automation.Provider.CmdletProvider.Force*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Force) - property is set to `true`. An error should be written if the path represents an item that is - hidden from the user and - [System.Management.Automation.Provider.CmdletProvider.Force*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Force) - is set to `false`. - -- Your implementation of the - [System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty*](/dotnet/api/System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty) - method should call - [System.Management.Automation.Provider.CmdletProvider.ShouldProcess](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldProcess) - and verify its return value before making any changes to the data store. This method is used to - confirm execution of an operation when a change is made to system state, for example, renaming - files. - [System.Management.Automation.Provider.CmdletProvider.ShouldProcess](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldProcess) - sends the name of the resource to be changed to the user, with the Windows PowerShell runtime and - handling any command-line settings or preference variables in determining what should be - displayed. - - After the call to - [System.Management.Automation.Provider.CmdletProvider.ShouldProcess](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldProcess) - returns `true`, if potentially dangerous system modifications can be made, the - [System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty*](/dotnet/api/System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty) - method should call the - [System.Management.Automation.Provider.CmdletProvider.ShouldContinue](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldContinue) - method. This method sends a confirmation message to the user to allow additional feedback to - indicate that the operation should be continued. - -## Attaching Dynamic Parameters for the Set-ItemProperty Cmdlet - -The `Set-ItemProperty` cmdlet might require additional parameters that are specified dynamically at -runtime. To provide these dynamic parameters, the Windows PowerShell property provider must -implement the -[System.Management.Automation.Provider.IPropertyCmdletProvider.SetPropertyDynamicParameters*](/dotnet/api/System.Management.Automation.Provider.IPropertyCmdletProvider.SetPropertyDynamicParameters) -method. This method returns an object that has properties and fields with parsing attributes similar -to a cmdlet class or a -[System.Management.Automation.RuntimeDefinedParameterDictionary](/dotnet/api/System.Management.Automation.RuntimeDefinedParameterDictionary) -object. The `null` value can be returned if no dynamic parameters are to be added. - -Here is the default implementation of [System.Management.Automation.Provider.IPropertyCmdletProvider.GetPropertyDynamicParameters*](/dotnet/api/System.Management.Automation.Provider.IPropertyCmdletProvider.GetPropertyDynamicParameters) from the TemplateProvider.cs file provided by Windows PowerShell. - - - -## Clearing Properties - -To clear properties, the Windows PowerShell property provider must implement the -[System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty*](/dotnet/api/System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty) -method to support calls from the `Clear-ItemProperty` cmdlet. This method sets one or more -properties for the item located at the specified path. - -Here is the default implementation of -[System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty*](/dotnet/api/System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty) -from the TemplateProvider.cs file provided by Windows PowerShell. - - - -#### Thing to Remember About Implementing ClearProperty - -The following conditions may apply to your implementation of -[System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty*](/dotnet/api/System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty): - -- When defining the provider class, a Windows PowerShell property provider might declare provider - capabilities of ExpandWildcards, Filter, Include, or Exclude, from the - [System.Management.Automation.Provider.ProviderCapabilities](/dotnet/api/System.Management.Automation.Provider.ProviderCapabilities) - enumeration. In these cases, the implementation of the - [System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty*](/dotnet/api/System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty) - method needs to ensure that the path passed to the method meets the requirements of the specified - capabilities. To do this, the method should access the appropriate property, for example, the - [System.Management.Automation.Provider.CmdletProvider.Exclude*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Exclude) - and - [System.Management.Automation.Provider.CmdletProvider.Include*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Include) - properties. - -- By default, overrides of this method should not retrieve a reader for objects that are hidden from - the user unless the - [System.Management.Automation.Provider.CmdletProvider.Force*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Force) - property is set to `true`. An error should be written if the path represents an item that is - hidden from the user and - [System.Management.Automation.Provider.CmdletProvider.Force*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.Force) - is set to `false`. - -- Your implementation of the - [System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty*](/dotnet/api/System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty) - method should call - [System.Management.Automation.Provider.CmdletProvider.ShouldProcess](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldProcess) - and verify its return value before making any changes to the data store. This method is used to - confirm execution of an operation before a change is made to system state, such as clearing - content. - [System.Management.Automation.Provider.CmdletProvider.ShouldProcess](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldProcess) - sends the name of the resource to be changed to the user, with the Windows PowerShell runtime - taking into account any command line settings or preference variables in determining what should - be displayed. - - After the call to - [System.Management.Automation.Provider.CmdletProvider.ShouldProcess](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldProcess) - returns `true`, if potentially dangerous system modifications can be made, the - [System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty*](/dotnet/api/System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty) - method should call the - [System.Management.Automation.Provider.CmdletProvider.ShouldContinue](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.ShouldContinue) - method. This method sends a confirmation message to the user to allow additional feedback to - indicate that the potentially dangerous operation should be continued. - -## Attaching Dynamic Parameters to the Clear-ItemProperty Cmdlet - -The `Clear-ItemProperty` cmdlet might require additional parameters that are specified dynamically -at runtime. To provide these dynamic parameters, the Windows PowerShell property provider must -implement the -[System.Management.Automation.Provider.IPropertyCmdletProvider.ClearPropertyDynamicParameters*](/dotnet/api/System.Management.Automation.Provider.IPropertyCmdletProvider.ClearPropertyDynamicParameters) -method. This method returns an object that has properties and fields with parsing attributes similar -to a cmdlet class or a -[System.Management.Automation.RuntimeDefinedParameterDictionary](/dotnet/api/System.Management.Automation.RuntimeDefinedParameterDictionary) -object. The `null` value can be returned if no dynamic parameters are to be added. - -Here is the default implementation of -[System.Management.Automation.Provider.IPropertyCmdletProvider.ClearPropertyDynamicParameters*](/dotnet/api/System.Management.Automation.Provider.IPropertyCmdletProvider.ClearPropertyDynamicParameters) -from the TemplateProvider.cs file provided by Windows PowerShell. - - - -## Building the Windows PowerShell provider - -See [How to Register Cmdlets, Providers, and Host Applications](/previous-versions//ms714644(v=vs.85)). - -## See Also - -[Windows PowerShell provider](./designing-your-windows-powershell-provider.md) - -[Design Your Windows PowerShell provider](./designing-your-windows-powershell-provider.md) - -[Extending Object Types and Formatting](/previous-versions//ms714665(v=vs.85)) - -[How to Register Cmdlets, Providers, and Host Applications](/previous-versions//ms714644(v=vs.85)) diff --git a/reference/docs-conceptual/developer/prog-guide/designing-your-windows-powershell-provider.md b/reference/docs-conceptual/developer/prog-guide/designing-your-windows-powershell-provider.md deleted file mode 100644 index aea0a61d3310..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/designing-your-windows-powershell-provider.md +++ /dev/null @@ -1,242 +0,0 @@ ---- -description: Designing Your Windows PowerShell Provider -ms.date: 09/13/2016 -title: Designing Your Windows PowerShell Provider ---- -# Designing Your Windows PowerShell Provider - -You should implement a Windows PowerShell provider if your product or configuration exposes a set of -stored data, such as a database that the user will want to navigate or browse. Additionally, if your -product provides a container, even if it is not a multilevel container, it makes sense to implement -a Windows PowerShell provider. For example, you might want to implement a Windows PowerShell -container provider if the cmdlet verb Copy, Move, Rename, New, or Remove makes sense as an operation -on your product or configuration data. - -## Windows PowerShell Paths Identify Your Provider - -The Windows PowerShell runtime uses Windows PowerShell paths to access the appropriate Windows -PowerShell provider. When a cmdlet specifies one of these paths, the runtime knows which provider to -use to access the associated data store. These paths include drive-qualified paths, -provider-qualified paths, provider-direct paths, and provider-internal paths. Each Windows -PowerShell provider must support one or more of these paths. - -For more information about Windows PowerShell paths, see How Windows PowerShell Works. - -### Defining a Drive-Qualified Path - -To allow the user to access data located at a physical drive, your Windows PowerShell provider must -support a drive-qualified path. This path starts with the drive name followed by a colon (:), for -example, mydrive:\abc\bar. - -### Defining a Provider-Qualified Path - -To allow the Windows PowerShell runtime to initialize and uninitialize the provider, your Windows -PowerShell provider must support a provider-qualified path. For example, -FileSystem::\\\uncshare\abc\bar is the provider-qualified path for the FileSystem provider furnished -by Windows PowerShell. - -### Defining a Provider-Direct Path - -To allow remote access to your Windows PowerShell provider, it should support a provider-direct path -to pass directly to the Windows PowerShell provider for the current location. For example, the -registry Windows PowerShell provider can use \\\server\regkeypath as a provider-direct path. - -### Defining a Provider-Internal Path - -To allow the provider cmdlet to access data using non-Windows PowerShell application programming -interfaces (APIs), your Windows PowerShell provider should support a provider-internal path. This -path is indicated after the "::" in the provider-qualified path. For example, the provider-internal -path for the FileSystem Windows PowerShell provider is \\\uncshare\abc\bar. - -## Changing Stored Data - -When overriding methods that modify the underlying data store, always call the -[System.Management.Automation.Provider.CmdletProvider.WriteItemObject*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.WriteItemObject) -method with the most up-to-date version of the item changed by that method. The provider -infrastructure determines if the item object needs to be passed to the pipeline, such as when the -user specifies the -PassThru parameter. If retrieving the most up-to-date item is a costly operation -(performance-wise,) you can test the Context.PassThru property to determine if you actually need to -write the resulting item. - -## Choose a Base Class for Your Provider - -Windows PowerShell provides a number of base classes that you can use to implement your own Windows -PowerShell provider. When designing a provider, choose the base class, described in this section, -that is most suited to your requirements. - -Each Windows PowerShell provider base class makes available a set of cmdlets. This section describes -the cmdlets, but it does not describe their parameters. - -Using the session state, the Windows PowerShell runtime makes several location cmdlets available to -certain Windows PowerShell providers, such as the `Get-Location`, `Set-Location`, `Pop-Location`, -and `Push-Location` cmdlets. You can use the `Get-Help` cmdlet to obtain information about these -location cmdlets. - -### CmdletProvider Base Class - -The -[System.Management.Automation.Provider.CmdletProvider](/dotnet/api/System.Management.Automation.Provider.CmdletProvider) -class defines a basic Windows PowerShell provider. This class supports the provider declaration and -supplies a number of properties and methods that are available to all Windows PowerShell providers. -The class is invoked by the `Get-PSProvider` cmdlet to list all available providers for a session. -The implementation of this cmdlet is furnished by the session state. - -> [!NOTE] -> Windows PowerShell providers are available to all Windows PowerShell language scopes. - -### DriveCmdletProvider Base Class - -The -[System.Management.Automation.Provider.DriveCmdletProvider](/dotnet/api/System.Management.Automation.Provider.DriveCmdletProvider) -class defines a Windows PowerShell drive provider that supports operations for adding new drives, -removing existing drives, and initializing default drives. For example, the FileSystem provider -provided by Windows PowerShell initializes drives for all volumes that are mounted, such as hard -drives and CD/DVD device drives. - -This class derives from the -[System.Management.Automation.Provider.CmdletProvider](/dotnet/api/System.Management.Automation.Provider.CmdletProvider) -base class. The following table lists the cmdlets exposed by this class. In addition to those -listed, the `Get-PSDrive` cmdlet (exposed by session state) is a related cmdlet that is used to -retrieve available drives. - -| Cmdlet | Definition | -| ---------------- | ------------------------------------------------------------------- | -| `New-PSDrive` | Creates a new drive for the session, and streams drive information. | -| `Remove-PSDrive` | Removes a drive from the session. | - -### ItemCmdletProvider Base Class - -The -[System.Management.Automation.Provider.ItemCmdletProvider](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider) -class defines a Windows PowerShell item provider that performs operations on the individual items of -the data store, and it does not assume any container or navigation capabilities. This class derives -from the -[System.Management.Automation.Provider.DriveCmdletProvider](/dotnet/api/System.Management.Automation.Provider.DriveCmdletProvider) -base class. The following table lists the cmdlets exposed by this class. - -| Cmdlet | Definition | -| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `Clear-Item` | Clears the current content of items at the specified location, and replaces it with the "clear" value specified by the provider. This cmdlet does not pass an output object through the pipeline unless its `PassThru` parameter is specified. | -| `Get-Item` | Retrieves items from the specified location, and streams the resultant objects. | -| `Invoke-Item` | Invokes the default action for the item at the specified path. | -| `Set-Item` | Sets an item at the specified location with the indicated value. This cmdlet does not pass an output object through the pipeline unless its `PassThru` parameter is specified. | -| `Resolve-Path` | Resolves the wildcards for a Windows PowerShell path, and streams path information. | -| `Test-Path` | Tests for the specified path, and returns `true` if it exists and `false` otherwise. This cmdlet is implemented to support the `IsContainer` parameter for the [System.Management.Automation.Provider.CmdletProvider.WriteItemObject*](/dotnet/api/System.Management.Automation.Provider.CmdletProvider.WriteItemObject) method. | - -### ContainerCmdletProvider Base Class - -The -[System.Management.Automation.Provider.ContainerCmdletProvider](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider) -class defines a Windows PowerShell container provider that exposes a container, for data store -items, to the user. Be aware that a Windows PowerShell container provider can be used only when -there is one container (no nested containers) with items in it. If there are nested containers, then -you must implement a Windows PowerShell navigation provider . - -This class derives from the -[System.Management.Automation.Provider.ItemCmdletProvider](/dotnet/api/System.Management.Automation.Provider.ItemCmdletProvider) -base class. The following table defines the cmdlets implemented by this class. - -| Cmdlet | Definition | -| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `Copy-Item` | Copies items from one location to another. This cmdlet does not pass an output object through the pipeline unless its `PassThru` parameter is specified. | -| `Get-ChildItem` | Retrieves the child items at the specified location, and streams them as objects. | -| `New-Item` | Creates new items at the specified location, and streams the resultant object. | -| `Remove-Item` | Removes items from the specified location. | -| `Rename-Item` | Renames an item at the specified location. This cmdlet does not pass an output object through the pipeline unless its `PassThru` parameter is specified. | - -### NavigationCmdletProvider Base Class - -The -[System.Management.Automation.Provider.NavigationCmdletProvider](/dotnet/api/System.Management.Automation.Provider.NavigationCmdletProvider) -class defines a Windows PowerShell navigation provider that performs operations for items that use -more than one container. This class derives from the -[System.Management.Automation.Provider.ContainerCmdletProvider](/dotnet/api/System.Management.Automation.Provider.ContainerCmdletProvider) -base class. The following table list the cmdlets exposed by this class. - -| Cmdlet | Definition | -| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -| `Combine-Path` | Combines two paths into a single path, using a provider-specific delimiter between paths. This cmdlet streams strings. | -| `Move-Item` | Moves items to the specified location. This cmdlet does not pass an output object through the pipeline unless its `PassThru` parameter is specified. | - -A related cmdlet is the basic Parse-Path cmdlet furnished by Windows PowerShell. This cmdlet can be -used to parse a Windows PowerShell path to support the `Parent` parameter. It streams the parent -path string. - -## Select Provider Interfaces to Support - -In addition to deriving from one of the Windows PowerShell base classes, your Windows PowerShell -provider can support other functionality by deriving from one or more of the following provider -interfaces. This section defines those interfaces and the cmdlets supported by each. It does not -describe the parameters for the interface-supported cmdlets. Cmdlet parameter information is -available online using the `Get-Command` and `Get-Help` cmdlets. - -### IContentCmdletProvider - -The -[System.Management.Automation.Provider.IContentCmdletProvider](/dotnet/api/System.Management.Automation.Provider.IContentCmdletProvider) -interface defines a content provider that performs operations on the content of a data item. The -following table lists the cmdlets exposed by this interface. - -| Cmdlet | Definition | -| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `Add-Content` | Appends the indicated value lengths to the contents of the specified item. This cmdlet does not pass an output object through the pipeline unless its `PassThru` parameter is specified. | -| `Clear-Content` | Sets the content of the specified item to the "clear" value. This cmdlet does not pass an output object through the pipeline unless its `PassThru` parameter is specified. | -| `Get-Content` | Retrieves the contents of the specified items and streams the resultant objects. | -| `Set-Content` | Replaces the existing content for the specified items. This cmdlet does not pass an output object through the pipeline unless its `PassThru` parameter is specified. | - -### IPropertyCmdletProvider - -The -[System.Management.Automation.Provider.IPropertyCmdletProvider](/dotnet/api/System.Management.Automation.Provider.IPropertyCmdletProvider) -interface defines a property Windows PowerShell provider that performs operations on the properties -of items in the data store. The following table lists the cmdlets exposed by this interface. - -> [!NOTE] -> The `Path` parameter on these cmdlets indicates a path to an item instead of identifying a -> property. - -| Cmdlet | Definition | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `Clear-ItemProperty` | Sets properties of the specified items to the "clear" value. This cmdlet does not pass an output object through the pipeline unless its `PassThru` parameter is specified. | -| `Get-ItemProperty` | Retrieves properties from the specified items and streams the resultant objects. | -| `Set-ItemProperty` | Sets properties of the specified items with the indicated values. This cmdlet does not pass an output object through the pipeline unless its `PassThru` parameter is specified. | - -### IDynamicPropertyCmdletProvider - -The -[System.Management.Automation.Provider.IDynamicPropertyCmdletProvider](/dotnet/api/System.Management.Automation.Provider.IDynamicPropertyCmdletProvider) -interface, derived from -[System.Management.Automation.Provider.IPropertyCmdletProvider](/dotnet/api/System.Management.Automation.Provider.IPropertyCmdletProvider), -defines a provider that specifies dynamic parameters for its supported cmdlets. This type of -provider handles operations for which properties can be defined at run time, for example, a new -property operation. Such operations are not possible on items having statically defined properties. -The following table lists the cmdlets exposed by this interface. - -| Cmdlet | Definition | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `Copy-ItemProperty` | Copies a property from the specified item to another item. This cmdlet does not pass an output object through the pipeline unless its `PassThru` parameter is specified. | -| `Move-ItemProperty` | Moves a property from the specified item to another item. This cmdlet does not pass an output object through the pipeline unless its `PassThru` parameter is specified. | -| `New-ItemProperty` | Creates a property on the specified items and streams the resultant objects. | -| `Remove-ItemProperty` | Removes a property for the specified items. | -| `Rename-ItemProperty` | Renames a property of the specified items. This cmdlet does not pass an output object through the pipeline unless its `PassThru` parameter is specified. | - -### ISecurityDescriptorCmdletProvider - -The -[System.Management.Automation.Provider.ISecurityDescriptorCmdletProvider](/dotnet/api/System.Management.Automation.Provider.ISecurityDescriptorCmdletProvider) -interface adds security descriptor functionality to a provider. This interface allows the user to -get and set security descriptor information for an item in the data store. The following table lists -the cmdlets exposed by this interface. - -| Cmdlet | Definition | -| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `Get-Acl` | Retrieves the information contained in an access control list (ACL), which is part of a security descriptor used to guard operating system resources, for example, a file or an object. | -| `Set-Acl` | Sets the information for an ACL. It is in the form of an instance of [System.Security.AccessControl.ObjectSecurity](/dotnet/api/System.Security.AccessControl.ObjectSecurity) on the item(s) designated for the specified path. This cmdlet can set information about files, keys, and subkeys in the registry, or any other provider item, if the Windows PowerShell provider supports the setting of security information. | - -## See Also - -[Creating Windows PowerShell Providers](./how-to-create-a-windows-powershell-provider.md) - -[How Windows PowerShell Works](/previous-versions/ms714658(v=vs.85)) - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/getproc01-code-samples.md b/reference/docs-conceptual/developer/prog-guide/getproc01-code-samples.md deleted file mode 100644 index 74fed11898bc..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/getproc01-code-samples.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -description: GetProc01 Code Samples -ms.date: 09/13/2016 -title: GetProc01 Code Samples ---- -# GetProc01 Code Samples - -Here are the code samples for the GetProc01 sample cmdlet. This is the basic `Get-Process` cmdlet sample described in [Creating Your First Cmdlet](../cmdlet/creating-a-cmdlet-without-parameters.md). A `Get-Process` cmdlet is designed to retrieve information about all the processes running on the local computer. - -For complete sample code, see the following topics. - -|Language|Topic| -|--------------|-----------| -|C#|[GetProc01 (C#) Sample Code](./getproc01-csharp-sample-code.md)| -|VB.NET|[GetProc01 (VB.NET) Sample Code](./getproc01-vb-net-sample-code.md)| - -## See Also - -[Windows PowerShell Programmer's Guide](./windows-powershell-programmer-s-guide.md) - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/getproc01-csharp-sample-code.md b/reference/docs-conceptual/developer/prog-guide/getproc01-csharp-sample-code.md deleted file mode 100644 index 051cec702cde..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/getproc01-csharp-sample-code.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -description: GetProc01 (C#) Sample Code -ms.date: 09/13/2016 -title: GetProc01 (C#) Sample Code ---- -# GetProc01 (C#) Sample Code - -The following code shows the implementation of the GetProc01 sample cmdlet. Notice that the cmdlet -is simplified by leaving the actual work of process retrieval to the -[System.Diagnostics.Process.Getprocesses*](/dotnet/api/System.Diagnostics.Process.GetProcesses) -method. - -> [!NOTE] -> You can download the C# source file (getproc01.cs) for this Get-Proc cmdlet using the Microsoft -> Windows Software Development Kit for Windows Vista and .NET Framework 3.0 Runtime Components. For -> download instructions, see -> [How to Install Windows PowerShell and Download the Windows PowerShell SDK](/powershell/scripting/developer/installing-the-windows-powershell-sdk). -> The downloaded source files are available in the **\** directory. - -## Code Sample - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/GetProcessSample01/GetProcessSample01.cs" range="11-126"::: - -## See Also - -[Windows PowerShell Programmer's Guide](./windows-powershell-programmer-s-guide.md) - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/getproc01-vb-net-sample-code.md b/reference/docs-conceptual/developer/prog-guide/getproc01-vb-net-sample-code.md deleted file mode 100644 index f85ae8b733a8..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/getproc01-vb-net-sample-code.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -description: GetProc01 (VB.NET) Sample Code -ms.date: 09/13/2016 -title: GetProc01 (VB.NET) Sample Code ---- -# GetProc01 (VB.NET) Sample Code - -The following code shows the implementation of the GetProc01 sample cmdlet. Notice that the cmdlet is simplified by leaving the actual work of process retrieval to the [System.Diagnostics.Process.Getprocesses*](/dotnet/api/System.Diagnostics.Process.GetProcesses) method. - -> [!NOTE] -> You can download the C# source file (getproc01.cs) for this Get-Proc cmdlet using the Microsoft Windows Software Development Kit for Windows Vista and .NET Framework 3.0 Runtime Components. For download instructions, see [How to Install Windows PowerShell and Download the Windows PowerShell SDK](/powershell/scripting/developer/installing-the-windows-powershell-sdk). -> -> The downloaded source files are available in the **\** directory. - -## Code Sample - - - -## See Also - -[Windows PowerShell Programmer's Guide](./windows-powershell-programmer-s-guide.md) - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/getproc02-code-samples.md b/reference/docs-conceptual/developer/prog-guide/getproc02-code-samples.md deleted file mode 100644 index 7d86748f0177..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/getproc02-code-samples.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -description: GetProc02 Code Samples -ms.date: 09/13/2016 -title: GetProc02 Code Samples ---- -# GetProc02 Code Samples - -Here are the code samples for the GetProc02 sample cmdlet. This is the `Get-Process` cmdlet sample described in [Adding Parameters that Process Command-Line Input](../cmdlet/adding-parameters-that-process-command-line-input.md). This `Get-Process` cmdlet retrieves processes based on their name, and then displays information about the processes at the command line. - -> [!NOTE] -> You can download the C# source file (getproc02.cs) for this Get-Proc cmdlet using the Microsoft Windows Software Development Kit for Windows Vista and .NET Framework 3.0 Runtime Components. For download instructions, see [How to Install Windows PowerShell and Download the Windows PowerShell SDK](/powershell/scripting/developer/installing-the-windows-powershell-sdk). -> -> The downloaded source files are available in the **\** directory. - -For complete sample code, see the following topics. - -|Language|Topic| -|--------------|-----------| -|C#|[GetProc02 (C#) Sample Code](./getproc02-csharp-sample-code.md)| -|VB.NET|[GetProc02 (VB.NET) Sample Code](./getproc02-vb-net-sample-code.md)| - -## See Also - -[Windows PowerShell Programmer's Guide](./windows-powershell-programmer-s-guide.md) - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/getproc02-csharp-sample-code.md b/reference/docs-conceptual/developer/prog-guide/getproc02-csharp-sample-code.md deleted file mode 100644 index 5d5009531ba1..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/getproc02-csharp-sample-code.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -description: GetProc02 (C#) Sample Code -ms.date: 09/13/2016 -title: GetProc02 (C#) Sample Code ---- -# GetProc02 (C#) Sample Code - -The following code shows the implementation of a `Get-Process` cmdlet that accepts command-line -input. Notice that this implementation defines a `Name` parameter to allow command-line input, and -it uses the -[WriteObject(System.Object,System.Boolean)](/dotnet/api/system.management.automation.cmdlet.writeobject#System_Management_Automation_Cmdlet_WriteObject_System_Object_System_Boolean_) -method as the output mechanism for sending output objects to the pipeline. - -## Code Sample - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/GetProcessSample02/GetProcessSample02.cs" range="11-76"::: - -## See Also - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/getproc02-vb-net-sample-code.md b/reference/docs-conceptual/developer/prog-guide/getproc02-vb-net-sample-code.md deleted file mode 100644 index 7728cc2ca50e..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/getproc02-vb-net-sample-code.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -description: GetProc02 (VB.NET) Sample Code -ms.date: 09/13/2016 -title: GetProc02 (VB.NET) Sample Code ---- -# GetProc02 (VB.NET) Sample Code - -The following code shows the implementation of a `Get-Process` cmdlet that accepts command-line -input. Notice that this implementation defines a `Name` parameter to allow command-line input, and -it uses the -[WriteObject(System.Object,System.Boolean)](/dotnet/api/system.management.automation.cmdlet.writeobject#System_Management_Automation_Cmdlet_WriteObject_System_Object_System_Boolean_) -method as the output mechanism for sending output objects to the pipeline. - -## Code Sample - - - -## See Also - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/getproc03-code-samples.md b/reference/docs-conceptual/developer/prog-guide/getproc03-code-samples.md deleted file mode 100644 index f7cea04c4e5f..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/getproc03-code-samples.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -description: GetProc03 Code Samples -ms.date: 09/13/2016 -title: GetProc03 Code Samples ---- -# GetProc03 Code Samples - -Here are the code samples for the GetProc03 sample cmdlet. This is the `Get-Process` cmdlet sample described in [Adding Parameters that Process Pipeline Input](../cmdlet/adding-parameters-that-process-pipeline-input.md). This `Get-Process` cmdlet uses a `Name` parameter that accepts input from a pipeline object, retrieves process information from the local computer based on the supplied names, and then displays information about the processes at the command line. - -> [!NOTE] -> You can download the C# source file (getprov03.cs) for this Get-Proc cmdlet using the Microsoft Windows Software Development Kit for Windows Vista and .NET Framework 3.0 Runtime Components. For download instructions, see [How to Install Windows PowerShell and Download the Windows PowerShell SDK](/powershell/scripting/developer/installing-the-windows-powershell-sdk). -> -> The downloaded source files are available in the **\** directory. - -For complete sample code, see the following topics. - -|Language|Topic| -|--------------|-----------| -|C#|[GetProc03 (C#) Sample Code](./getproc03-csharp-sample-code.md)| -|VB.NET|[GetProc03 (VB.NET) Sample Code](./getproc03-vb-net-sample-code.md)| - -## See Also - -[Windows PowerShell Programmer's Guide](./windows-powershell-programmer-s-guide.md) - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/getproc03-csharp-sample-code.md b/reference/docs-conceptual/developer/prog-guide/getproc03-csharp-sample-code.md deleted file mode 100644 index dda0ece8af7e..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/getproc03-csharp-sample-code.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -description: GetProc03 (C#) Sample Code -ms.date: 09/13/2016 -title: GetProc03 (C#) Sample Code ---- -# GetProc03 (C#) Sample Code - -The following code shows the implementation of a `Get-Process` cmdlet that can accept pipelined -input. This implementation defines a `Name` parameter that accepts pipeline input, retrieves process -information from the local computer based on the supplied names, and then uses the -[WriteObject(System.Object,System.Boolean)](/dotnet/api/system.management.automation.cmdlet.writeobject#System_Management_Automation_Cmdlet_WriteObject_System_Object_System_Boolean_) -method as the output mechanism for sending objects to the pipeline. - -> [!NOTE] -> You can download the C# source file (getprov03.cs) for this Get-Proc cmdlet using the Microsoft -> Windows Software Development Kit for Windows Vista and .NET Framework 3.0 Runtime Components. For -> download instructions, see -> [How to Install Windows PowerShell and Download the Windows PowerShell SDK](/powershell/scripting/developer/installing-the-windows-powershell-sdk). -> The downloaded source files are available in the **\** directory. - -## Code Sample - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/GetProcessSample03/GetProcessSample03.cs" range="11-78"::: - -## See Also - -[Windows PowerShell Programmer's Guide](./windows-powershell-programmer-s-guide.md) - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/getproc03-vb-net-sample-code.md b/reference/docs-conceptual/developer/prog-guide/getproc03-vb-net-sample-code.md deleted file mode 100644 index dda49355ce07..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/getproc03-vb-net-sample-code.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -description: GetProc03 (VB.NET) Sample Code -ms.date: 09/12/2016 -title: GetProc03 (VB.NET) Sample Code ---- -# GetProc03 (VB.NET) Sample Code - -The following code shows the implementation of a `Get-Process` cmdlet that can accept pipelined -input. This implementation defines a `Name` parameter that accepts pipeline input, retrieves process -information from the local computer based on the supplied names, and then uses the -[WriteObject(System.Object,System.Boolean)](/dotnet/api/system.management.automation.cmdlet.writeobject#System_Management_Automation_Cmdlet_WriteObject_System_Object_System_Boolean_) -method as the output mechanism for sending objects to the pipeline. - -## Code Sample - - diff --git a/reference/docs-conceptual/developer/prog-guide/getproc04-code-samples.md b/reference/docs-conceptual/developer/prog-guide/getproc04-code-samples.md deleted file mode 100644 index 2c32dab89e56..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/getproc04-code-samples.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -description: GetProc04 Code Samples -ms.date: 09/13/2016 -title: GetProc04 Code Samples ---- -# GetProc04 Code Samples - -Here are the code samples for the GetProc04 sample cmdlet. This is the `Get-Process` cmdlet sample described in [Adding Non-terminating Error Reporting to Your Cmdlet](../cmdlet/adding-non-terminating-error-reporting-to-your-cmdlet.md). This `Get-Process` cmdlet calls the [System.Management.Automation.Cmdlet.WriteError](/dotnet/api/System.Management.Automation.Cmdlet.WriteError) method whenever an invalid operation exception is thrown while retrieving process information. - -> [!NOTE] -> You can download the C# source file (getprov04.cs) for this Get-Proc cmdlet using the Microsoft Windows Software Development Kit for Windows Vista and .NET Framework 3.0 Runtime Components. For download instructions, see [How to Install Windows PowerShell and Download the Windows PowerShell SDK](/powershell/scripting/developer/installing-the-windows-powershell-sdk). -> -> The downloaded source files are available in the **<PowerShell Samples>** directory. - -For complete sample code, see the following topics. - -|Language|Topic| -|--------------|-----------| -|C#|[GetProc04 (C#) Sample Code](./getproc04-csharp-sample-code.md)| -|VB.NET|[GetProc04 (VB.NET) Sample Code](./getproc04-vb-net-sample-code.md)| - -## See Also - -- [Windows PowerShell Programmer's Guide](./windows-powershell-programmer-s-guide.md) - -- [Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/getproc04-csharp-sample-code.md b/reference/docs-conceptual/developer/prog-guide/getproc04-csharp-sample-code.md deleted file mode 100644 index 7ed2a9462330..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/getproc04-csharp-sample-code.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -description: GetProc04 (C#) Sample Code -ms.date: 09/13/2016 -title: GetProc04 (C#) Sample Code ---- -# GetProc04 (C#) Sample Code - -The following code shows the implementation of a `Get-Process` cmdlet that reports non-terminating -errors. This implementation calls the -[System.Management.Automation.Cmdlet.WriteError](/dotnet/api/System.Management.Automation.Cmdlet.WriteError) -method to report non-terminating errors. - -> [!NOTE] -> You can download the C# source file (getprov04.cs) for this Get-Proc cmdlet using the Microsoft -> Windows Software Development Kit for Windows Vista and .NET Framework 3.0 Runtime Components. For -> download instructions, see -> [How to Install Windows PowerShell and Download the Windows PowerShell SDK](/powershell/scripting/developer/installing-the-windows-powershell-sdk). -> The downloaded source files are available in the **<PowerShell Samples>** directory. - -## Code Sample - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/GetProcessSample04/GetProcessSample04.cs" range="11-98"::: - -## See Also - -- [Windows PowerShell Programmer's Guide](./windows-powershell-programmer-s-guide.md) - -- [Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/getproc04-vb-net-sample-code.md b/reference/docs-conceptual/developer/prog-guide/getproc04-vb-net-sample-code.md deleted file mode 100644 index 45515fd23451..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/getproc04-vb-net-sample-code.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -description: GetProc04 (VB.NET) Sample Code -ms.date: 09/13/2016 -title: GetProc04 (VB.NET) Sample Code ---- -# GetProc04 (VB.NET) Sample Code - -The following code shows the implementation of a `Get-Process` cmdlet that reports non-terminating errors. This implementation calls the [System.Management.Automation.Cmdlet.WriteError](/dotnet/api/System.Management.Automation.Cmdlet.WriteError) method to report non-terminating errors. - -> [!NOTE] -> You can download the C# source file (getprov04.cs) for this Get-Proc cmdlet using the Microsoft Windows Software Development Kit for Windows Vista and .NET Framework 3.0 Runtime Components. For download instructions, see [How to Install Windows PowerShell and Download the Windows PowerShell SDK](/powershell/scripting/developer/installing-the-windows-powershell-sdk). -> -> The downloaded source files are available in the **<PowerShell Samples>** directory. - -## Code Sample - - - -## See Also - -- [Windows PowerShell Programmer's Guide](./windows-powershell-programmer-s-guide.md) - -- [Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/getproc05-code-samples.md b/reference/docs-conceptual/developer/prog-guide/getproc05-code-samples.md deleted file mode 100644 index 0238e7b1dcd6..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/getproc05-code-samples.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -description: GetProc05 Code Samples -ms.date: 09/13/2016 -title: GetProc05 Code Samples ---- -# GetProc05 Code Samples - -Here are the code samples for the GetProc05 sample cmdlet. This `Get-Process` cmdlet is similar to -the cmdlet described in [Adding Non-terminating Error Reporting to Your Cmdlet][1]. - -|Language|Topic| -|--------------|-----------| -|C#|[GetProc05 (C#) Sample Code](./getproc05-csharp-sample-code.md)| -|VB.NET|[GetProc05 (VB.NET) Sample Code](./getproc05-vb-net-sample-code.md)| - -## See Also - -- [Windows PowerShell SDK](../windows-powershell-reference.md) - -[1]: ../cmdlet/adding-non-terminating-error-reporting-to-your-cmdlet.md diff --git a/reference/docs-conceptual/developer/prog-guide/getproc05-csharp-sample-code.md b/reference/docs-conceptual/developer/prog-guide/getproc05-csharp-sample-code.md deleted file mode 100644 index c428f3ee5bec..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/getproc05-csharp-sample-code.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -description: GetProc05 (C#) Sample Code -ms.date: 09/13/2016 -title: GetProc05 (C#) Sample Code ---- -# GetProc05 (C#) Sample Code - -Here is the complete C# code for the GetProc05 sample cmdlet. - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/GetProcessSample05/GetProcessSample05.cs" range="11-411"::: - -## See Also - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/getproc05-vb-net-sample-code.md b/reference/docs-conceptual/developer/prog-guide/getproc05-vb-net-sample-code.md deleted file mode 100644 index e0162ff6706a..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/getproc05-vb-net-sample-code.md +++ /dev/null @@ -1,427 +0,0 @@ ---- -description: GetProc05 (VB.NET) Sample Code -ms.date: 09/13/2016 -title: GetProc05 (VB.NET) Sample Code ---- -# GetProc05 (VB.NET) Sample Code - -Here is the complete VB.NET code for the GetProc05 sample cmdlet. - -```vb -Imports System -Imports System.Collections.Generic -Imports Win32Exception = System.ComponentModel.Win32Exception -Imports System.Diagnostics -Imports System.Security.Permissions - -'Windows PowerShell namespace -Imports System.Management.Automation -Imports System.ComponentModel - -Namespace Microsoft.Samples.PowerShell.Commands - - ' This sample is a complete implementation of the Get-Proc Cmdlet. -#Region "GetProcCommand" - - ''' - ''' This class implements the Get-Proc cmdlet - ''' - _ - Public Class GetProcCommand - Inherits PSCmdlet -#Region "Parameters" - - ''' - ''' The list of process names on which this cmdlet will work - ''' - _ - Public Property Name() As String() - Get - Return processNames - End Get - - Set(ByVal value As String()) - processNames = value - End Set - - End Property - - ''' - ''' gets/sets an array of process IDs - ''' - _ - Public Property Id() As Integer() - Get - Return processIds - End Get - Set(ByVal value As Integer()) - processIds = value - End Set - End Property - - ''' - ''' If the input is a stream of [collections of] Process - ''' objects, we bypass the ProcessName and Id parameters and - ''' read the Process objects directly. This allows us to deal - ''' with processes which have wildcard characters in their name. - ''' Process objects - ''' - _ - Public Property Input() As Process() - Get - Return inputObjects - End Get - Set(ByVal value As Process()) - inputObjects = value - End Set - End Property - -#End Region - -#Region "Cmdlet Overrides" - - ''' - ''' For each of the requested processnames, retrieve and write - ''' the associated processes. - ''' - Protected Overrides Sub ProcessRecord() - Dim matchingProcesses As List(Of Process) - - WriteDebug("Obtaining list of matching process objects.") - - Select Case ParameterSetName - Case "Id" - matchingProcesses = GetMatchingProcessesById() - Case "ProcessName" - matchingProcesses = GetMatchingProcessesByName() - Case "InputObject" - matchingProcesses = GetProcessesByInput() - Case Else - ThrowTerminatingError(New ErrorRecord( _ - New ArgumentException("Bad ParameterSetName"), _ - "UnableToAccessProcessList", _ - ErrorCategory.InvalidOperation, Nothing)) - Return - End Select - - WriteDebug("Outputting matching process objects.") - - matchingProcesses.Sort(AddressOf ProcessComparison) - - Dim process As Process - For Each process In matchingProcesses - WriteObject(process) - Next process - - End Sub 'ProcessRecord - -#End Region - -#Region "protected Methods and Data" - ''' - ''' Retrieves the list of all processes matching the ProcessName - ''' parameter. - ''' Generates a non-terminating error for each specified - ''' process name which is not found even though it contains - ''' no wildcards. - ''' - ''' - - Private Function GetMatchingProcessesByName() As List(Of Process) - - Dim allProcesses As List(Of Process) = _ - New List(Of Process)(Process.GetProcesses()) - - ' The keys dictionary will be used for rapid lookup of - ' processes already in the matchingProcesses list. - Dim keys As Dictionary(Of Integer, Byte) = _ - New Dictionary(Of Integer, Byte)() - - Dim matchingProcesses As List(Of Process) = New List(Of Process)() - - If Nothing Is processNames Then - matchingProcesses.AddRange(allProcesses) - Else - Dim pattern As String - For Each pattern In processNames - WriteVerbose(("Finding matches for process name """ & _ - pattern & """.")) - - ' WildCard search on the available processes - Dim wildcard As New WildcardPattern(pattern, _ - WildcardOptions.IgnoreCase) - - Dim found As Boolean = False - - Dim process As Process - For Each process In allProcesses - If Not keys.ContainsKey(process.Id) Then - Dim processName As String = _ - SafeGetProcessName(process) - - ' Remove the process from the allProcesses list - ' so that it's not tested again. - If processName.Length = 0 Then - allProcesses.Remove(process) - End If - - ' Perform a wildcard search on this particular - ' process and check whether this matches the - ' pattern specified. - If Not wildcard.IsMatch(processName) Then - GoTo ContinueForEach2 - End If - - WriteDebug(String.Format( _ - "Found matching process id ""{0}"".", process.Id)) - - ' We have found a match. - found = True - - ' Store the process ID so that we don't add the - ' same one twice. - keys.Add(process.Id, 0) - - ' Add the process to the processes list. - matchingProcesses.Add(process) - End If -ContinueForEach2: - Next process ' foreach (Process... - If Not found AndAlso Not _ - WildcardPattern.ContainsWildcardCharacters(pattern) _ - Then - WriteError(New ErrorRecord( _ - New ArgumentException("Cannot find process name " & _ - " " & pattern & "."), "ProcessNameNotFound", _ - ErrorCategory.ObjectNotFound, pattern)) - End If - Next pattern - End If - Return matchingProcesses - - End Function 'GetMatchingProcessesByName - - ''' - ''' Returns the name of a process. If an error occurs, a blank - ''' string will be returned. - ''' - ''' The process whose name will be - ''' returned. - ''' The name of the process. - Protected Shared Function SafeGetProcessName(ByVal process As Process) _ - As String - - Dim name As String = "" - - If Not (process Is Nothing) Then - Try - Return process.ProcessName - Catch e1 As Win32Exception - Catch e2 As InvalidOperationException - End Try - End If - Return name - - - End Function 'SafeGetProcessName - -#End Region - - -#Region "Private Methods" - - ''' - ''' Function to sort by ProcessName first, then by Id - ''' - ''' first Process object - ''' second Process object - ''' - ''' returns less than zero if x less than y, - ''' greater than 0 if x greater than y, 0 if x == y - ''' - Private Shared Function ProcessComparison(ByVal x As Process, _ - ByVal y As Process) As Integer - Dim diff As Integer = String.Compare(SafeGetProcessName(x), _ - SafeGetProcessName(y), StringComparison.CurrentCultureIgnoreCase) - - If 0 <> diff Then - Return diff - End If - Return x.Id - y.Id - - End Function 'ProcessComparison - - ''' - ''' Retrieves the list of all processes matching the Id - ''' parameter. - ''' Generates a non-terminating error for each specified - ''' process ID which is not found. - ''' - ''' An array of processes that match the given id. - ''' - Protected Function GetMatchingProcessesById() As List(Of Process) - - Dim matchingProcesses As List(Of Process) = New List(Of Process) - - If Not (processIds Is Nothing) Then - - ' The keys dictionary will be used for rapid lookup of - ' processes already in the matchingProcesses list. - Dim keys As Dictionary(Of Integer, Byte) = _ - New Dictionary(Of Integer, Byte)() - - Dim processId As Integer - For Each processId In processIds - WriteVerbose("Finding match for process id " & _ - processId & ".") - - If Not keys.ContainsKey(processId) Then - Dim process As Process - Try - process = _ - System.Diagnostics.Process.GetProcessById( _ - processId) - Catch ex As ArgumentException - WriteError(New ErrorRecord(ex, _ - "ProcessIdNotFound", _ - ErrorCategory.ObjectNotFound, processId)) - GoTo ContinueForEach1 - End Try - - WriteDebug("Found matching process.") - - matchingProcesses.Add(process) - keys.Add(processId, 0) - End If -ContinueForEach1: - Next processId - End If - - Return matchingProcesses - - End Function 'GetMatchingProcessesById - - ''' - ''' Retrieves the list of all processes matching the Input - ''' parameter. - ''' - Private Function GetProcessesByInput() As List(Of Process) - - Dim matchingProcesses As List(Of Process) = New List(Of Process)() - - If Not (Nothing Is Input) Then - ' The keys dictionary will be used for rapid lookup of - ' processes already in the matchingProcesses list. - Dim keys As Dictionary(Of Integer, Byte) = _ - New Dictionary(Of Integer, Byte)() - - Dim process As Process - For Each process In Input - WriteVerbose("Refreshing process object.") - - If Not keys.ContainsKey(process.Id) Then - Try - process.Refresh() - Catch e1 As Win32Exception - Catch e2 As InvalidOperationException - End Try - matchingProcesses.Add(process) - End If - Next process - End If - Return matchingProcesses - - End Function 'GetProcessesByInput - -#End Region - -#Region "Private Data" - - Private processNames() As String - Private processIds() As Integer - Private inputObjects() As Process - -#End Region - - End Class 'GetProcCommand - -#End Region - -#Region "PowerShell snap-in" ' - ''' - ''' Create this sample as a PowerShell snap-in - ''' - _ - Public Class GetProcPSSnapIn05 - Inherits PSSnapIn - - ''' - ''' Create an instance of the GetProcPSSnapIn05 - ''' - Public Sub New() - - End Sub 'New - - ''' - ''' Get a name for this PowerShell snap-in. This name will - ''' be used in registering - ''' this PowerShell snap-in. - ''' - - Public Overrides ReadOnly Property Name() As String - Get - Return "GetProcPSSnapIn05" - End Get - End Property - - ''' - ''' Vendor information for this PowerShell snap-in. - ''' - - Public Overrides ReadOnly Property Vendor() As String - Get - Return "Microsoft" - End Get - End Property - - ''' - ''' Gets resource information for vendor. This is a string of format: - ''' resourceBaseName,resourceName. - ''' - - Public Overrides ReadOnly Property VendorResource() As String - Get - Return "GetProcPSSnapIn05,Microsoft" - End Get - End Property - - ''' - ''' Description of this PowerShell snap-in. - ''' - - Public Overrides ReadOnly Property Description() As String - Get - Return "This is a PowerShell snap-in that includes " & _ - "the Get-Proc sample." - End Get - End Property - End Class 'GetProcPSSnapIn05 - -#End Region - -End Namespace -``` - - - -## See Also - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/how-to-create-a-windows-powershell-provider.md b/reference/docs-conceptual/developer/prog-guide/how-to-create-a-windows-powershell-provider.md deleted file mode 100644 index da920f75de24..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/how-to-create-a-windows-powershell-provider.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -description: How to Create a Windows PowerShell Provider -ms.date: 09/13/2016 -title: How to Create a Windows PowerShell Provider ---- -# How to Create a Windows PowerShell Provider - -This section describes how to build a Windows PowerShell provider. A Windows PowerShell provider can -be considered in two ways. To the user, the provider represents a set of stored data. For example, -the stored data can be the Internet Information Services (IIS) Metabase, the Microsoft Windows -Registry, the Windows file system, Active Directory, and the variable and alias data stored by -Windows PowerShell. - -To the developer, the Windows PowerShell provider is the interface between the user and the data -that the user needs to access. From this perspective, each type of provider described in this -section supports a set of specific base classes and interfaces that allow the Windows PowerShell -runtime to expose certain cmdlets to the user in a common way. - -## Providers Provided by Windows PowerShell - -Windows PowerShell provides several providers (such as the FileSystem provider, Registry provider, -and Alias provider) that are used to access known data stores. For more information about the -providers supplied by Windows PowerShell, use the following command to access online Help: - -**PS>Get-Help about_Providers** - -## Accessing the Stored Data Using Windows PowerShell Paths - -Windows PowerShell providers are accessible to the Windows PowerShell runtime and to commands -programmatically through the use of Windows PowerShell paths. Most of the time, these paths are used -to directly access the data through the provider. However, some paths can be resolved to -provider-internal paths that allow a cmdlet to use non-Windows PowerShell application programming -interfaces (APIs) to access the data. For more information about how Windows PowerShell providers -operate within Windows PowerShell, see -[How Windows PowerShell Works](/previous-versions/ms714658(v=vs.85)). - -## Exposing Provider Cmdlets Using Windows PowerShell Drives - -A Windows PowerShell provider exposes its supported cmdlets using virtual Windows PowerShell drives. -Windows PowerShell applies the following rules for a Windows PowerShell drive: - -- The name of a drive can be any alphanumeric sequence. -- A drive can be specified at any valid point on a path, called a "root". -- A drive can be implemented for any stored data, not just the file system. -- Each drive keeps its own current working location, allowing the user to retain context when - shifting between drives. - -## In This Section - -The following table lists topics that include code examples that build on each other. Starting with -the second topic, the basic Windows PowerShell provider can be initialized and uninitialized by the -Windows PowerShell runtime, the next topic adds functionality for accessing the data, the next topic -adds functionality for manipulating the data (the items in the stored data), and so on. - -| Topic | Definition | -| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [Designing Your Windows PowerShell Provider](./designing-your-windows-powershell-provider.md) | This topic discusses things you should consider before implementing a Windows PowerShell provider. It summarizes the Windows PowerShell provider base classes and interfaces that are used. | -| [Creating a Basic Windows PowerShell Provider](./creating-a-basic-windows-powershell-provider.md) | This topic shows how to create a Windows PowerShell provider that allows the Windows PowerShell runtime to initialize and uninitialize the provider. | -| [Creating a Windows PowerShell Drive Provider](./creating-a-windows-powershell-drive-provider.md) | This topic shows how to create a Windows PowerShell provider that allows the user to access a data store through a Windows PowerShell drive. | -| [Creating a Windows PowerShell Item Provider](./creating-a-windows-powershell-item-provider.md) | This topic shows how to create a Windows PowerShell provider that allows the user to manipulate the items in a data store. | -| [Creating a Windows PowerShell Container Provider](./creating-a-windows-powershell-container-provider.md) | This topic shows how to create a Windows PowerShell provider that allows the user to work on multilayer data stores. | -| [Creating a Windows PowerShell Navigation Provider](./creating-a-windows-powershell-navigation-provider.md) | This topic shows how to create a Windows PowerShell provider that allows the user to navigate the items of a data store in a hierarchical manner. | -| [Creating a Windows PowerShell Content Provider](./creating-a-windows-powershell-content-provider.md) | This topic shows how to create a Windows PowerShell provider that allows the user to manipulate the content of items in a data store. | -| [Creating a Windows PowerShell Property Provider](./creating-a-windows-powershell-property-provider.md) | This topic shows how to create a Windows PowerShell provider that allows the user to manipulate the properties of items in a data store. | - -## See Also - -[How Windows PowerShell Works](/previous-versions/ms714658(v=vs.85)) - -[Windows PowerShell SDK](../windows-powershell-reference.md) - -[Windows PowerShell Programmer's Guide](./windows-powershell-programmer-s-guide.md) diff --git a/reference/docs-conceptual/developer/prog-guide/runspace01-code-samples.md b/reference/docs-conceptual/developer/prog-guide/runspace01-code-samples.md deleted file mode 100644 index ed71d0982836..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/runspace01-code-samples.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -description: Runspace01 Code Samples -ms.date: 09/13/2016 -title: Runspace01 Code Samples ---- -# Runspace01 Code Samples - -Here are the code samples for the runspace described in [Creating a Console Application That Runs a Specified Command](/dotnet/csharp/programming-guide/inside-a-program/hello-world-your-first-program). The command that is invoked in the runspace is the `Get-Process` cmdlet. - -For complete sample code, see the following topics. - -|Language|Topic| -|--------------|-----------| -|C#|[Runspace01 (C#) Code Sample](./runspace01-csharp-code-sample.md)| -|VB.NET|[Runspace01 (VB.NET) Code Sample](./runspace01-vb-net-code-sample.md)| - -## See Also - -[Windows PowerShell Programmer's Guide](./windows-powershell-programmer-s-guide.md) - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/runspace01-csharp-code-sample.md b/reference/docs-conceptual/developer/prog-guide/runspace01-csharp-code-sample.md deleted file mode 100644 index 02039d731613..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/runspace01-csharp-code-sample.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -description: Runspace01 (C#) Code Sample -ms.date: 09/13/2016 -title: Runspace01 (C#) Code Sample ---- -# Runspace01 (C#) Code Sample - -Here are the code samples for the runspace described in -[Creating a Console Application That Runs a Specified Command](/dotnet/csharp/programming-guide/inside-a-program/hello-world-your-first-program). -To do this, the application invokes a runspace, and then invokes a command. (Note that this -application does not specify runspace configuration information, nor does it explicitly create a -pipeline). The command that is invoked is the `Get-Process` cmdlet. - -> [!NOTE] -> You can download the C# source file (runspace01.cs) for this runspace using the Microsoft Windows -> Software Development Kit for Windows Vista and Microsoft .NET Framework 3.0 Runtime Components. -> For download instructions, see -> [How to Install Windows PowerShell and Download the Windows PowerShell SDK](/powershell/scripting/developer/installing-the-windows-powershell-sdk). -> The downloaded source files are available in the **\** directory. - -## Code Sample - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/Runspace01/Runspace01.cs" range="11-62"::: - -## See Also - -[Windows PowerShell Programmer's Guide](./windows-powershell-programmer-s-guide.md) - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/runspace01-vb-net-code-sample.md b/reference/docs-conceptual/developer/prog-guide/runspace01-vb-net-code-sample.md deleted file mode 100644 index 64b0c69bd368..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/runspace01-vb-net-code-sample.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -description: Runspace01 (VB.NET) Code Sample -ms.date: 09/13/2016 -title: Runspace01 (VB.NET) Code Sample ---- -# Runspace01 (VB.NET) Code Sample - -Here are the code samples for the runspace described in [Creating a Console Application That Runs a Specified Command](/dotnet/csharp/programming-guide/inside-a-program/hello-world-your-first-program). To do this, the application invokes a runspace, and then invokes a command. (Note that this application does not specify runspace configuration information, nor does it explicitly create a pipeline.) The command that is invoked is the `Get-Process` cmdlet. - -## Code Sample - -```vb -Imports System -Imports System.Collections.Generic -Imports System.Text -Imports System.Management.Automation -Imports System.Management.Automation.Host -Imports System.Management.Automation.Runspaces - -Namespace Microsoft.Samples.PowerShell.Runspaces - - Module Runspace01 - ' - ' This sample uses the RunspaceInvoke class to execute - ' the Get-Process cmdlet synchronously. The name and - ' handlecount are then extracted from the PSObjects - ' returned and displayed. - ' - ' Unused - ' - ' This sample demonstrates the following: - ' 1. Creating an instance of the RunspaceInvoke class. - ' 2. Using this instance to invoke a PowerShell command. - ' 3. Using PSObject to extract properties from the objects - ' returned by this command. - ' - Sub Main() - ' Create an instance of the RunspaceInvoke class. - ' This takes care of all building all of the other - ' data structures needed... - Dim invoker As RunspaceInvoke = New RunspaceInvoke() - - Console.WriteLine("Process HandleCount") - Console.WriteLine("--------------------------------") - - ' Now invoke the runspace and display the objects that are - ' returned... - For Each result As PSObject In invoker.Invoke("Get-Process") - Console.WriteLine("{0,-20} {1}", _ - result.Members("ProcessName").Value, _ - result.Members("HandleCount").Value) - Next - System.Console.WriteLine("Hit any key to exit...") - System.Console.ReadKey() - End Sub - End Module -End Namespace -``` - - - -## See Also - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/runspace02-code-samples.md b/reference/docs-conceptual/developer/prog-guide/runspace02-code-samples.md deleted file mode 100644 index 4586ff99fae2..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/runspace02-code-samples.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -description: Runspace02 Code Samples -ms.date: 09/13/2016 -title: Runspace02 Code Samples ---- -# Runspace02 Code Samples - -Here is the source code for the Runspace02 sample. This sample uses the [System.Management.Automation.RunspaceInvoke](/dotnet/api/System.Management.Automation.RunspaceInvoke) class to execute the `Get-Process` cmdlet synchronously. Windows Forms and data binding are then used to display the results in a DataGridView control. - -For complete sample code, see the following topics. - -|Language|Topic| -|--------------|-----------| -|C#|[Runspace02 (C#) Code Sample](./runspace02-csharp-code-sample.md)| -|VB.NET|[Runspace02 (VB.NET) Code Sample](./runspace02-vb-net-code-sample.md)| - -## See Also - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/runspace02-csharp-code-sample.md b/reference/docs-conceptual/developer/prog-guide/runspace02-csharp-code-sample.md deleted file mode 100644 index 235969dcd570..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/runspace02-csharp-code-sample.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -description: Runspace02 (C#) Code Sample -ms.date: 09/13/2016 -title: Runspace02 (C#) Code Sample ---- -# Runspace02 (C#) Code Sample - -Here is the C# source code for the Runspace02 sample. This sample uses the -[System.Management.Automation.RunspaceInvoke](/dotnet/api/System.Management.Automation.RunspaceInvoke) -class to execute the `Get-Process` cmdlet synchronously. Windows Forms and data binding are then -used to display the results in a DataGridView control - -## Code Sample - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/Runspace02/Runspace02.cs" range="11-82"::: - -## See Also - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/runspace02-vb-net-code-sample.md b/reference/docs-conceptual/developer/prog-guide/runspace02-vb-net-code-sample.md deleted file mode 100644 index 3ec3a9039c8d..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/runspace02-vb-net-code-sample.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -description: Runspace02 (VB.NET) Code Sample -ms.date: 09/13/2016 -title: Runspace02 (VB.NET) Code Sample ---- -# Runspace02 (VB.NET) Code Sample - -Here is the VB.NET source code for the Runspace02 sample. This sample uses the [System.Management.Automation.RunspaceInvoke](/dotnet/api/System.Management.Automation.RunspaceInvoke) class to execute the `Get-Process` cmdlet synchronously. Windows Forms and data binding are then used to display the results in a DataGridView control. - -## Code Sample - -```vb -Imports System -Imports System.Collections -Imports System.Collections.ObjectModel -Imports System.Windows.Forms -Imports System.Management.Automation.Runspaces -Imports System.Management.Automation - -Namespace Microsoft.Samples.PowerShell.Runspaces - - Class Runspace02 - - Shared Sub CreateForm() - Dim form As New Form() - Dim grid As New DataGridView() - form.Controls.Add(grid) - grid.Dock = DockStyle.Fill - - ' Create an instance of the RunspaceInvoke class. - ' This takes care of all building all of the other - ' data structures needed... - Dim invoker As New RunspaceInvoke() - - Dim results As Collection(Of PSObject) = _ - invoker.Invoke("Get-Process | Sort-Object ID") - - ' The generic collection needs to be re-wrapped in an ArrayList - ' for data-binding to work... - Dim objects As New ArrayList() - objects.AddRange(results) - - ' The DataGridView will use the PSObjectTypeDescriptor type - ' to retrieve the properties. - grid.DataSource = objects - - form.ShowDialog() - - End Sub 'CreateForm - - - ''' - ''' This sample uses the RunspaceInvoke class to execute - ''' the Get-Process cmdlet synchronously. Windows Forms and data - ''' binding are then used to display the results in a - ''' DataGridView control. - ''' - ''' Unused - ''' - ''' This sample demonstrates the following: - ''' 1. Creating an instance of the RunspaceInvoke class. - ''' 2. Using this instance to invoke a PowerShell command. - ''' 3. Using the output of RunspaceInvoke in a DataGridView - ''' in a Windows Forms application - ''' - -## See Also - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/runspace03-code-samples.md b/reference/docs-conceptual/developer/prog-guide/runspace03-code-samples.md deleted file mode 100644 index 61f47c9780fd..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/runspace03-code-samples.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -description: RunSpace03 Code Samples -ms.date: 09/13/2016 -title: RunSpace03 Code Samples ---- -# RunSpace03 Code Samples - -Here are the code samples for the runspace described in "Creating a Console Application That Runs a Specified Script". - -> [!NOTE] -> You can download the C# source file (runspace03.cs) and the VB.NET source -> file (runspace03.vb) for this sample using the Microsoft Windows Software -> Development Kit for Windows Vista and Microsoft .NET Framework 3.0 Runtime -> Components. For download instructions, see -> [How to Install Windows PowerShell and Download the Windows PowerShell SDK](/powershell/scripting/developer/installing-the-windows-powershell-sdk). -> The downloaded source files are available in the **\** -> directory. - -For complete sample code, see the following topics. - -| Language | Topic | -| -------- | --------------------------------------------------------------------- | -| C# | [RunSpace03 (C#) Code Sample](./runspace03-csharp-code-sample.md) | -| VB.NET | [RunSpace03 (VB.NET) Code Sample](./runspace03-vb-net-code-sample.md) | - -## See Also - -[Windows PowerShell Programmer's Guide](./windows-powershell-programmer-s-guide.md) - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/runspace03-csharp-code-sample.md b/reference/docs-conceptual/developer/prog-guide/runspace03-csharp-code-sample.md deleted file mode 100644 index 850c76a885d9..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/runspace03-csharp-code-sample.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -description: RunSpace03 (C#) Code Sample -ms.date: 09/13/2016 -title: RunSpace03 (C#) Code Sample ---- -# RunSpace03 (C#) Code Sample - -Here is the C# source code for the console application described in "Creating a -Console Application That Runs a Specified Script". This sample uses the -[System.Management.Automation.RunspaceInvoke](/dotnet/api/System.Management.Automation.RunspaceInvoke) -class to execute a script that retrieves process information by using the list -of process names passed into the script. It shows how to pass input objects to -a script and how to retrieve error objects as well as the output objects. - -> [!NOTE] -> You can download the C# source file (runspace03.cs) for this sample using the -> Microsoft Windows Software Development Kit for Windows Vista and Microsoft -> .NET Framework 3.0 Runtime Components. For download instructions, see -> [How to Install Windows PowerShell and Download the Windows PowerShell SDK](/powershell/scripting/developer/installing-the-windows-powershell-sdk). -> The downloaded source files are available in the **\** -> directory. - -## Code Sample - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/Runspace03/Runspace03.cs" range="11-88"::: - -## See Also - -[Windows PowerShell Programmer's Guide](./windows-powershell-programmer-s-guide.md) - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/runspace03-vb-net-code-sample.md b/reference/docs-conceptual/developer/prog-guide/runspace03-vb-net-code-sample.md deleted file mode 100644 index 90caaed6e4c3..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/runspace03-vb-net-code-sample.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -description: RunSpace03 (VB.NET) Code Sample -ms.date: 09/13/2016 -title: RunSpace03 (VB.NET) Code Sample ---- -# RunSpace03 (VB.NET) Code Sample - -Here is the VB.NET source code for the console application described in -"Creating a Console Application That Runs a Specified Script". This sample uses -the [System.Management.Automation.RunspaceInvoke](/dotnet/api/System.Management.Automation.RunspaceInvoke) -class to execute a script that retrieves process information for the list of -process names passed into the script. It shows how to pass input objects to a -script and how to retrieve error objects as well as the output objects. - -> [!NOTE] -> You can download the VB.NET source file (runspace03.vb) for this sample by -> using the Windows Software Development Kit for Windows Vista and Microsoft -> .NET Framework 3.0 Runtime Components. For download instructions, see -> [How to Install Windows PowerShell and Download the Windows PowerShell SDK](/powershell/scripting/developer/installing-the-windows-powershell-sdk). -> The downloaded source files are available in the **\** -> directory. - -## Code Sample - -```vb -Imports System -Imports System.Collections -Imports System.Collections.Generic -Imports System.Collections.ObjectModel -Imports System.Text -Imports Microsoft.VisualBasic -Imports System.Management.Automation -Imports System.Management.Automation.Host -Imports System.Management.Automation.Runspaces - -Namespace Microsoft.Samples.PowerShell.Runspaces - - Class Runspace03 - - ''' - ''' This sample uses the RunspaceInvoke class to execute - ''' a script that retrieves process information for the - ''' list of process names passed into the script. - ''' It shows how to pass input objects to a script and - ''' how to retrieve error objects as well as the output objects. - ''' - ''' Unused - ''' - ''' This sample demonstrates the following: - ''' 1. Creating an instance of the RunspaceInvoke class. - ''' 2. Using this instance to execute a string as a PowerShell script. - ''' 3. Passing input objects to the script from the calling program. - ''' 4. Using PSObject to extract and display properties from the objects - ''' returned by this command. - ''' 5. Retrieving and displaying error records that were generated - ''' during the execution of that script. - ''' - Shared Sub Main(ByVal args() As String) - ' Define a list of processes to look for - Dim processNames() As String = {"lsass", "nosuchprocess", _ - "services", "nosuchprocess2"} - - ' The script to run to get these processes. Input passed - ' to the script will be available in the $input variable. - Dim script As String = "$input | Get-Process -Name {$_}" - - ' Create an instance of the RunspaceInvoke class. - Dim invoker As New RunspaceInvoke() - - Console.WriteLine("Process HandleCount") - Console.WriteLine("--------------------------------") - - ' Now invoke the runspace and display the objects that are - ' returned... - Dim errors As System.Collections.IList = Nothing - Dim result As PSObject - For Each result In invoker.Invoke(script, processNames, errors) - Console.WriteLine("{0,-20} {1}", _ - result.Members("ProcessName").Value, _ - result.Members("HandleCount").Value) - Next result - - ' Now process any error records that were generated while - ' running the script. - Console.WriteLine(vbCrLf & _ - "The following non-terminating errors occurred:" & vbCrLf) - If Not (errors Is Nothing) AndAlso errors.Count > 0 Then - Dim err As PSObject - For Each err In errors - System.Console.WriteLine(" error: {0}", err.ToString()) - Next err - End If - System.Console.WriteLine(vbCRLF & "Hit any key to exit...") - System.Console.ReadKey() - - End Sub 'Main - - End Class 'Runspace03 - -End Namespace -``` - - - -## See Also - -[Windows PowerShell Programmer's Guide](./windows-powershell-programmer-s-guide.md) - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/runspace04-code-samples.md b/reference/docs-conceptual/developer/prog-guide/runspace04-code-samples.md deleted file mode 100644 index 7f270e9a2eb5..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/runspace04-code-samples.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -description: RunSpace04 Code Samples -ms.date: 01/04/2021 -title: RunSpace04 Code Samples ---- -# RunSpace04 Code Samples - -Here is a code sample for a runspace that uses the [System.Management.Automation.RunspaceInvoke](/dotnet/api/System.Management.Automation.RunspaceInvoke) -class to execute a script that generates a terminating error. The host application is responsible -for catching the error and interpreting the error record. - -> [!NOTE] -> You can download the VB.NET source file (Runspace04.vb) for this runspace using the Windows -> Software Development Kit for Windows Vista and Microsoft .NET Framework 3.0 Runtime Components. -> For download instructions, see [How to Install Windows PowerShell and Download the Windows PowerShell SDK](/powershell/scripting/developer/installing-the-windows-powershell-sdk). -> The downloaded source files are available in the **\** directory. - -For complete sample code, see the following topics. - -|Language|Topic| -|--------------|-----------| -|VB.NET|[Runspace04 (VB.NET) Code Sample](./runspace04-vb-net-code-sample.md)| - -## See Also - -[Windows PowerShell Programmer's Guide](./windows-powershell-programmer-s-guide.md) - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/runspace04-vb-net-code-sample.md b/reference/docs-conceptual/developer/prog-guide/runspace04-vb-net-code-sample.md deleted file mode 100644 index 5ca0b06b9522..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/runspace04-vb-net-code-sample.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -description: RunSpace04 (VB.NET) Code Sample -ms.date: 09/13/2016 -title: RunSpace04 (VB.NET) Code Sample ---- -# RunSpace04 (VB.NET) Code Sample - -Here is the VB.NET source code for the Runspace04 sample. This sample uses the [System.Management.Automation.RunspaceInvoke](/dotnet/api/System.Management.Automation.RunspaceInvoke) class to execute a script that generates a terminating error. The host application is responsible for catching the error and interpreting the error record. - -> [!NOTE] -> You can download the VB.NET source file (runspace02.vb) for this sample by using the Windows Software Development Kit for Windows Vista and Microsoft .NET Framework 3.0 Runtime Components. For download instructions, see [How to Install Windows PowerShell and Download the Windows PowerShell SDK](/powershell/scripting/developer/installing-the-windows-powershell-sdk). -> -> The downloaded source files are available in the **\** directory. - -## Code Sample - -```vb -Imports System -Imports System.Collections -Imports System.Collections.Generic -Imports System.Collections.ObjectModel -Imports System.Text -Imports Microsoft.VisualBasic -Imports System.Management.Automation -Imports System.Management.Automation.Host -Imports System.Management.Automation.Runspaces - -Namespace Microsoft.Samples.PowerShell.Runspaces - - Class Runspace04 - - ''' - ''' This sample uses the RunspaceInvoke class to execute - ''' a script. This script will generate a terminating - ''' exception that the caller should catch and process. - ''' - ''' Unused - ''' - ''' This sample demonstrates the following: - ''' 1. Creating an instance of the RunspaceInvoke class. - ''' 2. Using this instance to execute a string as a PowerShell script. - ''' 3. Passing input objects to the script from the calling program. - ''' 4. Using PSObject to extract and display properties from the objects - ''' returned by this command. - ''' 5. Retrieving and displaying error records that may be generated - ''' during the execution of that script. - ''' 6. Catching and displaying terminating exceptions generated - ''' by the script being run. - ''' - Shared Sub Main(ByVal args() As String) - ' Define a list of patterns to use in matching - ' Note that the fourth pattern is not a valid regular - ' expression so it will cause a terminating exception to - ' be thrown when used in Select-String. - Dim patterns() As String = {"aa", "bc", "ab*c", "*", "abc"} - - ' The script to run to use the patterns. Input passed - ' to the script will be available in the $input variable. - Dim script As String = "$input | where {" & _ - " Select-String $_ -InputObject 'abc' }" - - ' Create an instance of the RunspaceInvoke class. - Dim invoker As New RunspaceInvoke() - - ' Invoke the runspace. Because of the bad regular expression, - ' no objects will be returned. Instead, an exception will be - ' thrown. - Try - Dim errors As System.Collections.IList = Nothing - Dim result As PSObject - For Each result In invoker.Invoke(script, patterns, errors) - Console.WriteLine("'{0}'", result.ToString()) - Next result - - ' Now process any error records that were generated - ' while running the script. - Console.WriteLine(vbCrLf & _ - "The following non-terminating errors occurred:" & vbCrLf) - If Not (errors Is Nothing) AndAlso errors.Count > 0 Then - Dim err As PSObject - For Each err In errors - System.Console.WriteLine(" error: {0}", err.ToString()) - Next err - End If - Catch runtimeException As RuntimeException - ' Trap any exception generated by the script. These exceptions - ' will all be derived from RuntimeException. - System.Console.WriteLine("Runtime exception: {0}: {1}" & _ - vbCrLf + "{2}", _ - runtimeException.ErrorRecord.InvocationInfo.InvocationName, _ - runtimeException.Message, _ - runtimeException.ErrorRecord.InvocationInfo.PositionMessage) - End Try - - System.Console.WriteLine(vbCrLf + "Hit any key to exit...") - System.Console.ReadKey() - - End Sub 'Main - End Class 'Runspace04 - -End Namespace -``` - - - -## See Also - -[Windows PowerShell Programmer's Guide](./windows-powershell-programmer-s-guide.md) - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/runspace05-code-sample.md b/reference/docs-conceptual/developer/prog-guide/runspace05-code-sample.md deleted file mode 100644 index 6f547ed37b4f..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/runspace05-code-sample.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -description: RunSpace05 Code Sample -ms.date: 09/13/2016 -title: RunSpace05 Code Sample ---- -# RunSpace05 Code Sample - -Here is the source code for the Runspace05 sample that is described in -[Configuring a Runspace Using RunspaceConfiguration](https://msdn.microsoft.com/42681d19-2d05-4975-befd-afb1990e79b2). -This sample shows how to create the runspace configuration information, create a runspace, create a -pipeline with a single command, and then execute the pipeline. The command that is executed is the -`Get-Process` cmdlet. - -> [!NOTE] -> You can download the C# source file (runspace05.cs) by using the Microsoft Windows Software -> Development Kit for Windows Vista and Microsoft .NET Framework 3.0 Runtime Components. For -> download instructions, see -> [How to Install Windows PowerShell and Download the Windows PowerShell SDK](/powershell/scripting/developer/installing-the-windows-powershell-sdk). -> The downloaded source files are available in the **\** directory. - -## Code Sample - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/Runspace05/Runspace05.cs" range="11-86"::: - -## See Also - -[Windows PowerShell Programmer's Guide](./windows-powershell-programmer-s-guide.md) - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/runspace06-code-sample.md b/reference/docs-conceptual/developer/prog-guide/runspace06-code-sample.md deleted file mode 100644 index 746bf6796faa..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/runspace06-code-sample.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -description: RunSpace06 Code Sample -ms.date: 09/13/2016 -title: RunSpace06 Code Sample ---- -# RunSpace06 Code Sample - -Here is the source code for the Runspace06 sample described in -[Configuring a Runspace Using a Windows PowerShell Snap-in](https://msdn.microsoft.com/a7289ee8-9732-49ee-91c7-d533e9538b83). -This sample application creates a runspace based on a Windows PowerShell snap-in, which is then used -to run a pipeline with a single command. To do this, the application creates the runspace -configuration information, creates a runspace, creates a pipeline with a single command, and then -executes the pipeline. - -> [!NOTE] -> You can download the C# source file (runspace06.cs) by using the Windows Software Development Kit -> for Windows Vista and Microsoft .NET Framework 3.0 Runtime Components. For download instructions, -> see -> [How to Install Windows PowerShell and Download the Windows PowerShell SDK](/powershell/scripting/developer/installing-the-windows-powershell-sdk). -> The downloaded source files are available in the **\** directory. - -## Code Sample - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/Runspace06/Runspace06.cs" range="11-85"::: - -## See Also - -[Windows PowerShell Programmer's Guide](./windows-powershell-programmer-s-guide.md) - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/runspace07-code-sample.md b/reference/docs-conceptual/developer/prog-guide/runspace07-code-sample.md deleted file mode 100644 index a30ba2d79106..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/runspace07-code-sample.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -description: RunSpace07 Code Sample -ms.date: 09/13/2016 -title: RunSpace07 Code Sample ---- -# RunSpace07 Code Sample - -Here is the source code for the Runspace07 sample described in -[Creating a Console Application That Adds Commands to a Pipeline](https://msdn.microsoft.com/01eb7808-e97b-4905-80be-9e2fa38c262e). -This sample application creates a runspace, creates a pipeline, adds two commands to the pipeline, -and then executes the pipeline. The commands added to the pipeline are the `Get-Process` and -`Measure-Object` cmdlets. - -> [!NOTE] -> You can download the C# source file (runspace07.cs) using the Microsoft Windows Software -> Development Kit for Windows Vista and Microsoft .NET Framework 3.0 Runtime Components. For -> download instructions, see -> [How to Install Windows PowerShell and Download the Windows PowerShell SDK](/powershell/scripting/developer/installing-the-windows-powershell-sdk). -> The downloaded source files are available in the **\** directory. - -## Code Sample - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/Runspace07/Runspace07.cs" range="11-108"::: - -## See Also - -[Windows PowerShell Programmer's Guide](./windows-powershell-programmer-s-guide.md) - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/runspace08-code-sample.md b/reference/docs-conceptual/developer/prog-guide/runspace08-code-sample.md deleted file mode 100644 index 342502a7741f..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/runspace08-code-sample.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -description: RunSpace08 Code Sample -ms.date: 09/13/2016 -title: RunSpace08 Code Sample ---- -# RunSpace08 Code Sample - -Here is the source code for the Runspace08 sample described in -[Creating a Console Application That Adds Parameters to a Command](https://msdn.microsoft.com/848b2b46-60f1-4a86-b448-cfc7c0cccfba). -This sample application creates a runspace, creates a pipeline, adds two commands to the pipeline, -adds two parameters to the second command, and then executes the pipeline. The commands that are -added to the pipeline are the `Get-Process` and `Sort-Object` cmdlets. - -## Code Sample - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/Runspace08/Runspace08.cs" range="11-86"::: - -## See Also - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/runspace09-code-sample.md b/reference/docs-conceptual/developer/prog-guide/runspace09-code-sample.md deleted file mode 100644 index 483e941f55d5..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/runspace09-code-sample.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -description: RunSpace09 Code Sample -ms.date: 09/13/2016 -title: RunSpace09 Code Sample ---- -# RunSpace09 Code Sample - -This sample application creates and opens a runspace, creates and asynchronously invokes a pipeline, -and then uses pipeline events to process the script asynchronously. The script that is run by this -application creates the integers 1 through 10 in 0.5-second intervals (500 ms). - -## Code Sample - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/Runspace09/Runspace09.cs" range="11-113"::: - -## See Also - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/runspace10-code-sample.md b/reference/docs-conceptual/developer/prog-guide/runspace10-code-sample.md deleted file mode 100644 index 24c7eda0d781..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/runspace10-code-sample.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -description: RunSpace10 Code Sample -ms.date: 09/13/2016 -title: RunSpace10 Code Sample ---- -# RunSpace10 Code Sample - -Here is the source code for the Runspace10 sample. This sample application adds a cmdlet to -[System.Management.Automation.Runspaces.RunspaceConfiguration](/dotnet/api/System.Management.Automation.Runspaces.RunspaceConfiguration) -and then uses the modified configuration information to create the runspace. - -> [!NOTE] -> You can download the C# source file (runspace10.cs) by using the Windows Software Development Kit -> for Windows Vista and Microsoft .NET Framework 3.0 Runtime Components. For download instructions, -> see -> [How to Install Windows PowerShell and Download the Windows PowerShell SDK](/powershell/scripting/developer/installing-the-windows-powershell-sdk). -> The downloaded source files are available in the **\** directory. - -## Code Sample - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/Runspace10/Runspace10.cs" range="11-118"::: - -## See Also - -[Windows PowerShell Programmer's Guide](./windows-powershell-programmer-s-guide.md) - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/stopproc01-code-samples.md b/reference/docs-conceptual/developer/prog-guide/stopproc01-code-samples.md deleted file mode 100644 index d1571ea7125e..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/stopproc01-code-samples.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -description: StopProc01 Code Samples -ms.date: 09/13/2016 -title: StopProc01 Code Samples ---- -# StopProc01 Code Samples - -Here is the code sample for the StopProc01 sample cmdlet. This is the `Stop-Process` cmdlet sample described in [Creating a Cmdlet that Modifies the System](../cmdlet/creating-a-cmdlet-that-modifies-the-system.md). The `Stop-Process` cmdlet is designed to stop processes that are retrieved using the Get-Proc cmdlet (described in [Creating Your First Cmdlet](../cmdlet/creating-a-cmdlet-without-parameters.md)). - -> [!NOTE] -> You can download the C# (stopproc01.cs) source file for the Stop-Proc cmdlet using the Microsoft Windows Software Development Kit for Windows Vista and .NET Framework 3.0 Runtime Components. For download instructions, see [How to Install Windows PowerShell and Download the Windows PowerShell SDK](/powershell/scripting/developer/installing-the-windows-powershell-sdk). -> -> The downloaded source files are available in the **\** directory. - -|Language|Topic| -|--------------|-----------| -|C#|[StopProc01 (C#) Sample Code](./stopproc01-csharp-sample-code.md)| - -## See Also - -[Windows PowerShell Programmer's Guide](./windows-powershell-programmer-s-guide.md) - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/stopproc01-csharp-sample-code.md b/reference/docs-conceptual/developer/prog-guide/stopproc01-csharp-sample-code.md deleted file mode 100644 index 7e43c4499340..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/stopproc01-csharp-sample-code.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -description: StopProc01 (C#) Sample Code -ms.date: 09/13/2016 -title: StopProc01 (C#) Sample Code ---- -# StopProc01 (C#) Sample Code - -Here is the complete C# code for the StopProc01 sample cmdlet. - -> [!NOTE] -> You can download the C# (stopproc01.cs) source file for the Stop-Proc cmdlet using the Microsoft -> Windows Software Development Kit for Windows Vista and .NET Framework 3.0 Runtime Components. For -> download instructions, see -> [How to Install Windows PowerShell and Download the Windows PowerShell SDK](/powershell/scripting/developer/installing-the-windows-powershell-sdk). -> The downloaded source files are available in the **\** directory. - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/StopProcessSample01/StopProcessSample01.cs" range="11-212"::: - -## See Also - -[Windows PowerShell Programmer's Guide](./windows-powershell-programmer-s-guide.md) - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/stopprocesssample04-code-samples.md b/reference/docs-conceptual/developer/prog-guide/stopprocesssample04-code-samples.md deleted file mode 100644 index 8db41026e8e4..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/stopprocesssample04-code-samples.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -description: StopProcessSample04 Code Samples -ms.date: 09/13/2016 -title: StopProcessSample04 Code Samples ---- -# StopProcessSample04 Code Samples - -Here are the code samples for the StopProc00 sample cmdlet. This is the `Stop-Process` cmdlet sample described in [Adding Parameter Sets to a Cmdlet](../cmdlet/adding-parameter-sets-to-a-cmdlet.md). The `Stop-Process` cmdlet is designed to stop processes that are retrieved using the Get-Proc cmdlet (described in [Creating Your First Cmdlet](../cmdlet/creating-a-cmdlet-without-parameters.md)). - -> [!NOTE] -> You can download the C# (stopprocesssample04.cs) and VB.NET (stopprocesssample04.vb) for this Stop-Proc cmdlet using the Microsoft Windows Software Development Kit for Windows Vista and .NET Framework 3.0 Runtime Components. For download instructions, see [How to Install Windows PowerShell and Download the Windows PowerShell SDK](/powershell/scripting/developer/installing-the-windows-powershell-sdk). -> -> The downloaded source files are available in the **\** directory. - -For complete sample code, see the following topics. - -|Language|Topic| -|--------------|-----------| -|C#|[StopProc04 (C#) Sample Code](./stopprocesssample04-csharp-sample-code.md)| -|VB.NET|[StopProc04 (VB.NET) Sample Code](./stopprocesssample04-vb-net-sample-code.md)| - -## See Also - -[Windows PowerShell Programmer's Guide](./windows-powershell-programmer-s-guide.md) - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/stopprocesssample04-csharp-sample-code.md b/reference/docs-conceptual/developer/prog-guide/stopprocesssample04-csharp-sample-code.md deleted file mode 100644 index 13f31be73dd2..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/stopprocesssample04-csharp-sample-code.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -description: StopProcessSample04 (C#) Sample Code -ms.date: 09/13/2016 -title: StopProcessSample04 (C#) Sample Code ---- -# StopProcessSample04 (C#) Sample Code - -Here is the complete C# sample code for the StopProc04 sample cmdlet. This is the code for the -`Stop-Process` cmdlet described in -[Adding Parameter Sets to a Cmdlet](../cmdlet/adding-parameter-sets-to-a-cmdlet.md). The -`Stop-Process` cmdlet is designed to stop processes that are retrieved using the Get-Proc cmdlet -(described in [Creating Your First Cmdlet](../cmdlet/creating-a-cmdlet-without-parameters.md)). - -> [!NOTE] -> You can download the C# (stopprocesssample04.cs) source file for this Stop-Proc cmdlet using the -> Microsoft Windows Software Development Kit for Windows Vista and .NET Framework 3.0 Runtime -> Components. For download instructions, see -> [How to Install Windows PowerShell and Download the Windows PowerShell SDK](/powershell/scripting/developer/installing-the-windows-powershell-sdk). -> The downloaded source files are available in the **\** directory. - -:::code language="csharp" source="~/../powershell-sdk-samples/SDK-2.0/csharp/StopProcessSample04/StopProcessSample04.cs" range="11-435"::: - -## See Also - -[Windows PowerShell Programmer's Guide](./windows-powershell-programmer-s-guide.md) - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/stopprocesssample04-vb-net-sample-code.md b/reference/docs-conceptual/developer/prog-guide/stopprocesssample04-vb-net-sample-code.md deleted file mode 100644 index f1243befb92d..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/stopprocesssample04-vb-net-sample-code.md +++ /dev/null @@ -1,472 +0,0 @@ ---- -description: StopProcessSample04 (VB.NET) Sample Code -ms.date: 09/13/2016 -title: StopProcessSample04 (VB.NET) Sample Code ---- -# StopProcessSample04 (VB.NET) Sample Code - -Here is the complete VB.NET sample code for the StopProc04 sample cmdlet. This is the code for the `Stop-Process` cmdlet described in [Adding Parameter Sets to a Cmdlet](../cmdlet/adding-parameter-sets-to-a-cmdlet.md). The `Stop-Process` cmdlet is designed to stop processes that are retrieved using the Get-Proc cmdlet (described in [Creating Your First Cmdlet](../cmdlet/creating-a-cmdlet-without-parameters.md)). - -> [!NOTE] -> You can download the VB.NET (stopprocesssample04.vb) source file for this Stop-Proc cmdlet using the Microsoft Windows Software Development Kit for Windows Vista and .NET Framework 3.0 Runtime Components. For download instructions, see [How to Install Windows PowerShell and Download the Windows PowerShell SDK](/powershell/scripting/developer/installing-the-windows-powershell-sdk). -> -> The downloaded source files are available in the **\** directory. - -```vb -Imports System -Imports System.Diagnostics -Imports System.Collections -Imports Win32Exception = System.ComponentModel.Win32Exception -Imports System.Management.Automation 'Windows PowerShell namespace -Imports System.ComponentModel -Imports System.Globalization - -Namespace Microsoft.Samples.PowerShell.Commands - - ' This sample introduces parameter sets, the input object and - ' DefaultParameterSet. -#Region "StopProcCommand" - - ''' - ''' Class that implements the Stop-Proc cmdlet. - ''' - _ - Public Class StopProcCommand - Inherits PSCmdlet -#Region "Parameters" - - ''' - ''' The list of process names on which this cmdlet will work. - ''' - - _ - Public Property Name() As String() - Get - Return processNames - End Get - Set(ByVal value As String()) - processNames = value - End Set - End Property - Private processNames() As String - - ''' - ''' Overrides the ShouldContinue check to force stop operation. - ''' This option should always be used with caution. - ''' - - _ - Public Property Force() As SwitchParameter - Get - Return myForce - End Get - Set(ByVal value As SwitchParameter) - myForce = value - End Set - End Property - Private myForce As Boolean - - ''' - ''' Common parameter to determine if the process should pass the - ''' object down the pipeline after the process has been stopped. - ''' - - _ - Public Property PassThru() As SwitchParameter - Get - Return myPassThru - End Get - Set(ByVal value As SwitchParameter) - myPassThru = value - End Set - End Property - Private myPassThru As Boolean - - ''' - ''' The list of process IDs on which this cmdlet will work. - ''' - - _ - Public Property Id() As Integer() - Get - Return processIds - End Get - Set(ByVal value As Integer()) - processIds = value - End Set - End Property - Private processIds() As Integer - - ''' - ''' An array of Process objects from the stream to stop. - ''' - ''' Process objects - _ - Public Property InputObject() As Process() - Get - Return myInputObject - End Get - Set(ByVal value As Process()) - myInputObject = value - End Set - End Property - Private myInputObject() As Process - -#End Region - -#Region "CmdletOverrides" - ''' - ''' For each of the requested processnames: - ''' 1) check it's not a special process - ''' 2) attempt to stop that process. - ''' If no process requested, then nothing occurs. - ''' - Protected Overrides Sub ProcessRecord() - Select Case ParameterSetName - Case "ProcessName" - ProcessByName() - - Case "ProcessId" - ProcessById() - - Case "InputObject" - Dim process As Process - For Each process In myInputObject - SafeStopProcess(process) - Next process - - Case Else - Throw New ArgumentException("Bad ParameterSet Name") - End Select - - End Sub 'ProcessRecord ' ProcessRecord -#End Region - -#Region "Helper Methods" - ''' - ''' Returns all processes with matching names. - ''' - ''' - ''' The name of the process(es) to return - ''' - ''' An array of all - ''' machine processes. - ''' An array of matching processes. - Friend Function SafeGetProcessesByName(ByVal processName As String, _ - ByRef allProcesses As ArrayList) As ArrayList - - ' Create and array to store the matching processes. - Dim matchingProcesses As New ArrayList() - - ' Create the wildcard for pattern matching. - Dim options As WildcardOptions = WildcardOptions.IgnoreCase Or _ - WildcardOptions.Compiled - Dim wildcard As New WildcardPattern(processName, options) - - ' Walk all of the machine processes. - Dim process As Process - For Each process In allProcesses - Dim processNameToMatch As String = Nothing - Try - processNameToMatch = process.ProcessName - Catch e As Win32Exception - ' Remove the process from the list so that it is not - ' checked again. - allProcesses.Remove(process) - - Dim message As String = _ - String.Format(CultureInfo.CurrentCulture, _ - "The process ""{0}"" could not be found", processName) - WriteVerbose(message) - WriteError(New ErrorRecord(e, _ - "ProcessNotFound", ErrorCategory.ObjectNotFound, _ - processName)) - - GoTo ContinueForEach1 - End Try - - If Not wildcard.IsMatch(processNameToMatch) Then - GoTo ContinueForEach1 - End If - - matchingProcesses.Add(process) -ContinueForEach1: - Next process - Return matchingProcesses - - End Function 'SafeGetProcessesByName - - ''' - ''' Safely stops a named process. Used as standalone function - ''' to declutter ProcessRecord method. - ''' - ''' The process to stop. - Private Sub SafeStopProcess(ByVal process As Process) - Dim processName As String = Nothing - - Try - processName = process.ProcessName - Catch e As Win32Exception - WriteError(New ErrorRecord(e, "ProcessNotFound", _ - ErrorCategory.OpenError, processName)) - - Return - End Try - - ' Confirm the operation first. - ' This is always false if WhatIf is set. - If Not ShouldProcess(String.Format(CultureInfo.CurrentCulture, _ - "{0} ({1})", processName, process.Id)) Then - Return - End If - - ' Make sure the user really wants to stop a critical - ' process and possibly stop the machine. - Dim criticalProcess As Boolean = _ - criticalProcessNames.Contains( _ - processName.ToLower(CultureInfo.CurrentCulture)) - - Dim message As String = Nothing - If criticalProcess AndAlso Not myForce Then - message = String.Format(CultureInfo.CurrentCulture, _ - "The process ""{0}"" is a critical process and " & _ - "should not be stopped. " & _ - "Are you sure you wish to stop the process?", processName) - - ' It is possible that ProcessRecord is called multiple - ' when objects are received as inputs from a pipeline. - ' So, to retain YesToAll and NoToAll input that the - ' user may enter across multiple calls to this - ' function, they are stored as private members of the - ' Cmdlet. - If Not ShouldContinue(message, "Warning!", yesToAll, noToAll) Then - Return - End If - End If - - ' Display a warning information if stopping a critical - ' process - If criticalProcess Then - message = String.Format(CultureInfo.CurrentCulture, _ - "Stopping the critical process ""{0}"".", processName) - WriteWarning(message) - End If - - Try - ' Stop the process. - process.Kill() - Catch e As Exception - If TypeOf e Is Win32Exception OrElse TypeOf e Is SystemException _ - OrElse TypeOf e Is InvalidOperationException Then - ' This process could not be stopped so write - ' a non-terminating error. - WriteError(New ErrorRecord(e, _ - "CouldNotStopProcess", ErrorCategory.CloseError, process)) - Return - Else - Throw - End If - End Try - - ' Write a user-level message to the pipeline. These are - ' intended to give the user detailed information on the - ' operations performed by the Cmdlet. These messages will - ' appear with the -Verbose option. - message = String.Format(CultureInfo.CurrentCulture, _ - "Stopped process ""{0}"", pid {1}.", processName, process.Id) - - WriteVerbose(message) - - ' If the -PassThru command line argument is - ' specified, pass the terminated process on. - If myPassThru Then - ' Write a debug message to the host which will be helpful - ' in troubleshooting a problem. All debug messages - ' will appear with the -Debug option - message = String.Format(CultureInfo.CurrentCulture, _ - "Writing process ""{0}"" to pipeline", processName) - WriteDebug(message) - WriteObject(process) - End If - - End Sub 'SafeStopProcess - - - ''' - ''' Stop processes based on their names (using the - ''' ParameterSetName as ProcessName) - ''' - Private Sub ProcessByName() - Dim allProcesses As ArrayList = Nothing - - ' Get a list of all processes. - Try - allProcesses = New ArrayList(Process.GetProcesses()) - Catch ioe As InvalidOperationException - MyBase.ThrowTerminatingError(New ErrorRecord(ioe, _ - "UnableToAccessProcessList", _ - ErrorCategory.InvalidOperation, Nothing)) - End Try - - ' If a name parameter is passed to cmdlet, get - ' the associated process(es). - ' Write a non-terminating error for failure to - ' retrieve a process - Dim name As String - For Each name In processNames - ' The allProcesses array list is passed as a reference because - ' any process whose name cannot be obtained will be removed - ' from the list so that its not compared the next time. - Dim processes As ArrayList = SafeGetProcessesByName(name, _ - allProcesses) - - ' If no processes were found write a non-terminating error. - If processes.Count = 0 Then - WriteError(New ErrorRecord( _ - New Exception("Process not found."), _ - "ProcessNotFound", ErrorCategory.ObjectNotFound, name)) - Else - ' Otherwise terminate all processes in the list. - Dim process As Process - For Each process In processes - SafeStopProcess(process) - Next process - End If - - Next name - - End Sub 'ProcessByName - - ''' - ''' Stop processes based on their ids (using the - ''' ParameterSetName as ProcessIds) - ''' - Friend Sub ProcessById() - Dim processId As Integer - For Each processId In processIds - Dim process As Process = Nothing - Try - process = System.Diagnostics.Process.GetProcessById(processId) - - ' Write a debug message to the host which will be helpful - ' in troubleshooting a problem. All debug messages - ' will appear with the -Debug option - Dim message As String = String.Format( _ - CultureInfo.CurrentCulture, _ - "Acquired process for pid : {0}", process.Id) - WriteDebug(message) - Catch ae As ArgumentException - Dim message As String = String.Format( _ - CultureInfo.CurrentCulture, _ - "The process id {0} could not be found", processId) - WriteVerbose(message) - WriteError(New ErrorRecord(ae, _ - "ProcessIdNotFound", _ - ErrorCategory.ObjectNotFound, processId)) - GoTo ContinueForEach1 - End Try - - SafeStopProcess(process) -ContinueForEach1: - Next processId - - End Sub 'ProcessById ' ProcessById -#End Region - -#Region "Private Data" - - Private yesToAll, noToAll As Boolean - - ''' - ''' Partial list of critical processes that should not be - ''' stopped. Lower case is used for case insensitive matching. - ''' - Private criticalProcessNames As New ArrayList( _ - New String() {"system", "winlogon", "spoolsv", "calc"}) - -#End Region - - End Class 'StopProcCommand - -#End Region - -#Region "PowerShell snap-in" ' - ''' - ''' Create this sample as a PowerShell snap-in - ''' - _ - Public Class StopProcPSSnapIn04 - Inherits PSSnapIn - - ''' - ''' Create an instance of the StopProcPSSnapIn04 - ''' - Public Sub New() - - End Sub 'New - - ''' - ''' Get a name for this PowerShell snap-in. This name will - ''' be used in registering this PowerShell snap-in. - ''' - Public Overrides ReadOnly Property Name() As String - Get - Return "StopProcPSSnapIn04" - End Get - End Property - - ''' - ''' Vendor information for this PowerShell snap-in. - ''' - - Public Overrides ReadOnly Property Vendor() As String - Get - Return "Microsoft" - End Get - End Property - - ''' - ''' Gets resource information for vendor. This is a string of format: - ''' resourceBaseName,resourceName. - ''' - Public Overrides ReadOnly Property VendorResource() As String - Get - Return "StopProcPSSnapIn04,Microsoft" - End Get - End Property - - ''' - ''' Description of this PowerShell snap-in. - ''' - Public Overrides ReadOnly Property Description() As String - Get - Return "This is a PowerShell snap-in that includes " & _ - "the Stop-Proc cmdlet." - End Get - End Property - End Class 'StopProcPSSnapIn04 - -#End Region - -End Namespace -``` - - - -## See Also - -[Windows PowerShell Programmer's Guide](./windows-powershell-programmer-s-guide.md) - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/windows-powershell-concepts.md b/reference/docs-conceptual/developer/prog-guide/windows-powershell-concepts.md deleted file mode 100644 index 378cf88381c0..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/windows-powershell-concepts.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -description: Windows PowerShell Concepts -ms.date: 10/22/2021 -title: Windows PowerShell Concepts ---- -# Windows PowerShell Concepts - -This section contains conceptual information that will help you understand PowerShell from a -developer's viewpoint. - -|Topic Name|Description| -|----------------|-----------------| -|[about_Objects](/powershell/module/microsoft.powershell.core/about/about_objects)|Description of PowerShell objects. For more information, see [About Object Creation](/powershell/module/microsoft.powershell.core/about/about_object_creation)| -|[Creating Runspaces](../hosting/creating-runspaces.md)|The operating environments where commands are processed. For more information, see [Runspace Class](/dotnet/api/system.management.automation.runspaces.runspace).| -|[Extending Output Objects](../cmdlet/extending-output-objects.md)|How to extend PowerShell objects. For more information, see [About Types.ps1xml](/powershell/module/microsoft.powershell.core/about/about_types.ps1xml)| -|[Registering Cmdlets](../cmdlet/registering-cmdlets.md)|How to make modules and snap-ins available in PowerShell. For more information, see [Modules and Snap-ins](../cmdlet/modules-and-snap-ins.md).| -|[Requesting Confirmation from Cmdlets](../cmdlet/requesting-confirmation-from-cmdlets.md)|How cmdlets and providers request feedback from the user before an action is taken.| -|[RuntimeDefinedParameter Class](/dotnet/api/system.management.automation.runtimedefinedparameter)|Runtime parameter declarations.| -|[System.Management.Automation Namespace](/dotnet/api/System.Management.Automation)|Overview of PowerShell API namespaces.| -|[Windows PowerShell Provider Overview](../provider/windows-powershell-provider-overview.md)|Overview about PowerShell providers that are used to access data stores.| -|[Writing Help for PowerShell Cmdlets](../help/writing-help-for-windows-powershell-cmdlets.md)|How to write PowerShell cmdlet Help.| - -## See also - -[PowerShell Class](/dotnet/api/system.management.automation.powershell) - -[PowerShell API Reference](/dotnet/api/) - -[Windows PowerShell Programmer's Guide](windows-powershell-programmer-s-guide.md) - -[Writing Help for Windows PowerShell Modules](../module/writing-help-for-windows-powershell-modules.md) - -[Writing a Windows PowerShell Provider](../provider/writing-a-windows-powershell-provider.md) - -[Windows PowerShell API Reference](/dotnet/api/?view=powershellsdk-1.1.0&preserve-view=true) - -[Windows PowerShell Reference](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/windows-powershell-programmer-s-guide.md b/reference/docs-conceptual/developer/prog-guide/windows-powershell-programmer-s-guide.md deleted file mode 100644 index ee1f0b78cd91..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/windows-powershell-programmer-s-guide.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -description: Windows PowerShell Programmer's Guide -ms.date: 09/13/2016 -title: Windows PowerShell Programmer's Guide ---- -# Windows PowerShell Programmer's Guide - -This programmer's guide is targeted at developers who are interested in providing a command-line -management environment for system administrators. Windows PowerShell provides a simple way for you -to build management commands that expose .NET objects, while allowing Windows PowerShell to do most -of the work for you. - -In traditional command development, you are required to write a parameter parser, a parameter -binder, filters, and all other functionality exposed by each command. Windows PowerShell provides -the following to make it easy for you to write commands: - -- A powerful Windows PowerShell runtime (execution engine) with its own parser and a mechanism for - automatically binding command parameters. - -- Utilities for formatting and displaying command results using a command line interpreter (CLI). - -- Support for high levels of functionality (through Windows PowerShell providers) that make it easy - to access stored data. - - At little cost, you can represent a .NET object by a rich command or set of commands that will - offer a complete command-line experience to the administrator. - - The next section covers the key Windows PowerShell concepts and terms. Familiarize yourself with - these concepts and terms before starting development. - -## About Windows PowerShell - -Windows PowerShell defines several types of commands that you can use in development. These commands -include: functions, filters, scripts, aliases, and executables (applications). The main command type -discussed in this guide is a simple, small command called a "cmdlet". Windows PowerShell furnishes a -set of cmdlets and fully supports cmdlet customization to suit your environment. The Windows -PowerShell runtime processes all command types just as it does cmdlets, using pipelines. - -In addition to commands, Windows PowerShell supports various customizable Windows PowerShell -providers that make available specific sets of cmdlets. The shell operates within the Windows -PowerShell-provided host application (`powershell.exe`), but it is equally accessible from a -custom host application that you can develop to meet specific requirements. For more information, -see [How Windows PowerShell Works](/previous-versions//ms714658(v=vs.85)). - -### Windows PowerShell Cmdlets - -A cmdlet is a lightweight command that is used in the Windows PowerShell environment. The Windows -PowerShell runtime invokes these cmdlets within the context of automation scripts that are provided -at the command line, and the Windows PowerShell runtime also invokes them programmatically through -Windows PowerShell APIs. - -For more information about cmdlets, see [Writing a Windows PowerShell Cmdlet](../cmdlet/writing-a-windows-powershell-cmdlet.md). - -### Windows PowerShell Providers - -In performing administrative tasks, the user may need to examine data stored in a data store (for -example, the file system, the Windows Registry, or a certificate store). To make these operations -easier, Windows PowerShell defines a module called a Windows PowerShell provider that can be used to -access a specific data store, such as the Windows Registry. Each provider supports a set of related -cmdlets to give the user a symmetrical view of the data in the store. - -Windows PowerShell provides several default Windows PowerShell providers. For example, the Registry -provider supports navigation and manipulation of the Windows Registry. Registry keys are represented -as items, and registry values are treated as properties. - -If you expose a data store that the user will need to access, you might need to write your own -Windows PowerShell provider, as described in -[Creating Windows PowerShell Providers](./how-to-create-a-windows-powershell-provider.md). For more -information aboutWindows PowerShell providers, see -[How Windows PowerShell Works](/previous-versions//ms714658(v=vs.85)). - -### Host Application - -Windows PowerShell includes the default host application powershell.exe, which is a console -application that interacts with the user and hosts the Windows PowerShell runtime using a console -window. - -Only rarely will you need to write your own host application for Windows PowerShell, although -customization is supported. One case in which you might need your own application is when you have a -requirement for a GUI interface that is richer than the interface provided by the default host -application. You might also want a custom application when you are basing your GUI on the command -line. For more information, see -[How to Create a Windows PowerShell Host Application](/powershell/scripting/developer/hosting/writing-a-windows-powershell-host-application). - -### Windows PowerShell Runtime - -The Windows PowerShell runtime is the execution engine that implements command processing. It -includes the classes that provide the interface between the host application and Windows PowerShell -commands and providers. The Windows PowerShell runtime is implemented as a runspace object for the -current Windows PowerShell session, which is the operational environment in which the shell and the -commands execute. For operational details, see -[How Windows PowerShell Works](/previous-versions//ms714658(v=vs.85)). - -### Windows PowerShell Language - -The Windows PowerShell language provides scripting functions and mechanisms to invoke commands. For -complete scripting information, see the Windows PowerShell Language Reference shipped with Windows -PowerShell. - -### Extended Type System (ETS) - -Windows PowerShell provides access to a variety of different objects, such as .NET and XML objects. -As a consequence, to present a common abstraction for all object types the shell uses its extended -type system (ETS). Most ETS functionality is transparent to the user, but the script or .NET -developer uses it for the following purposes: - -- Viewing a subset of the members of specific objects. Windows PowerShell provides an "adapted" view - of several specific object types. - -- Adding members to existing objects. - -- Access to serialized objects. - -- Writing customized objects. - - Using ETS, you can create flexible new "types" that are compatible with the Windows PowerShell - language. If you are a .NET developer, you are able to work with objects using the same semantics - as the Windows PowerShell language applies to scripting, for example, to determine if an object - evaluates to `true`. - - For more information about ETS and how Windows PowerShell uses objects, see - [Windows PowerShell Object Concepts](/powershell/scripting/learn/understanding-important-powershell-concepts). - -## Programming for Windows PowerShell - -Windows PowerShell defines its code for commands, providers, and other program modules using the -.NET Framework. You are not confined to the use of Microsoft Visual Studio in creating customized -modules for Windows PowerShell, although the samples provided in this guide are known to run in this -tool. You can use any .NET language that supports class inheritance and the use of attributes. In -some cases, Windows PowerShell APIs require the programming language to be able to access generic -types. - -## Programmer's Reference - -For reference when developing for Windows PowerShell, see the -[Windows PowerShell SDK](../windows-powershell-reference.md). - -## Getting Started Using Windows PowerShell - -For more information about starting to use the Windows PowerShell shell, see the -[Getting Started with Windows PowerShell](/powershell/scripting/getting-started/getting-started-with-windows-powershell) -shipped with Windows PowerShell. A Quick Reference tri-fold document is also supplied as a primer -for cmdlet use. - -## Contents of This Guide - -|Topic|Definition| -|-----------|----------------| -|[How to Create a Windows PowerShell Provider](./how-to-create-a-windows-powershell-provider.md)|This section describes how to build a Windows PowerShell provider for Windows PowerShell.| -|[How to Create a Windows PowerShell Host Application](/powershell/scripting/developer/hosting/writing-a-windows-powershell-host-application)|This section describes how to write a host application that manipulates a runspace and how to write a host application that implements its own custom host.| -|[How to Create a Windows PowerShell Snap-in](../cmdlet/how-to-create-a-windows-powershell-snap-in.md)|This section describes how to create a snap-in that is used to register all cmdlets and providers in an assembly and how to create a custom snap-in.| -|[How to Create a Console Shell](./how-to-create-a-console-shell.md)|This section describes how to create a console shell that is not extensible.| -|[Windows PowerShell Concepts](./windows-powershell-concepts.md)|This section contains conceptual information that will help you understand Windows PowerShell from the viewpoint of a developer.| - -## See Also - -[Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/prog-guide/windows-powershell-sample-code.md b/reference/docs-conceptual/developer/prog-guide/windows-powershell-sample-code.md deleted file mode 100644 index 131a66987cf6..000000000000 --- a/reference/docs-conceptual/developer/prog-guide/windows-powershell-sample-code.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -description: Windows PowerShell Sample Code -ms.date: 09/13/2016 -title: Windows PowerShell Sample Code ---- -# Windows PowerShell Sample Code - -Windows PowerShell samples are available through the Windows SDK. This section contains the sample -code that is contained in the Windows SDK samples. - -> [!NOTE] -> When the Windows SDK is installed, a **Samples** directory is created in which all the Windows -> PowerShell samples are made available. A typical installation directory is **C:\Program -> Files\Microsoft SDKs\Windows\v6.0**. Start Windows PowerShell and type **"cd -> Samples\SysMgmt\PowerShell"** to locate the samples' directory. In this document, the Windows -> PowerShell Samples directory is referred to as **<PowerShell Samples>**. - -## Sample Code Listing - -| Sample Code | Description | -| --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [AccessDbProviderSample01 Code Sample](./accessdbprovidersample01-code-sample.md) | This is the provider described in [Creating a Basic Windows PowerShell Provider](./creating-a-basic-windows-powershell-provider.md). | -| [AccessDbProviderSample02 Code Sample](./accessdbprovidersample02-code-sample.md) | This is the provider described in [Creating a Windows PowerShell Drive Provider](./creating-a-windows-powershell-drive-provider.md). | -| [AccessDbProviderSample03 Code Sample](./accessdbprovidersample03-code-sample.md) | This is the provider described in [Creating a Windows PowerShell Item Provider](./creating-a-windows-powershell-item-provider.md). | -| [AccessDbProviderSample04 Code Sample](./accessdbprovidersample04-code-sample.md) | This is the provider described in [Creating a Windows PowerShell Container Provider](./creating-a-windows-powershell-container-provider.md). | -| [AccessDbProviderSample05 Code Sample](./accessdbprovidersample05-code-sample.md) | This is the provider described in [Creating a Windows PowerShell Navigation Provider](./creating-a-windows-powershell-navigation-provider.md). | -| [AccessDbProviderSample06 Code Sample](./accessdbprovidersample06-code-sample.md) | This is the provider described in [Creating a Windows PowerShell Content Provider](./creating-a-windows-powershell-content-provider.md). | -| [GetProc01 Code Samples](./getproc01-code-samples.md) | This is the basic `Get-Process` cmdlet sample described in [Creating Your First Cmdlet](../cmdlet/creating-a-cmdlet-without-parameters.md). | -| [GetProc02 Code Samples](./getproc02-code-samples.md) | This is the `Get-Process` cmdlet sample described in [Adding Parameters that Process Command-Line Input](../cmdlet/adding-parameters-that-process-command-line-input.md). | -| [GetProc03 Code Samples](./getproc03-code-samples.md) | This is the `Get-Process` cmdlet sample described in [Adding Parameters that Process Pipeline Input](../cmdlet/adding-parameters-that-process-pipeline-input.md). | -| [GetProc04 Code Samples](./getproc04-code-samples.md) | This is the `Get-Process` cmdlet sample described in [Adding Non-terminating Error Reporting to Your Cmdlet](../cmdlet/adding-non-terminating-error-reporting-to-your-cmdlet.md). | -| [GetProc05 Code Samples](./getproc05-code-samples.md) | This `Get-Process` cmdlet is similar to the cmdlet described in [Adding Non-terminating Error Reporting to Your Cmdlet](../cmdlet/adding-non-terminating-error-reporting-to-your-cmdlet.md). | -| [StopProc01 Code Samples](./stopproc01-code-samples.md) | This is the `Stop-Process` cmdlet sample described in [Creating a Cmdlet That Modifies the System](../cmdlet/creating-a-cmdlet-that-modifies-the-system.md). | -| [StopProcessSample04 Code Samples](./stopprocesssample04-code-samples.md) | This is the `Stop-Process` cmdlet sample described in [Adding Parameter Sets to a Cmdlet](../cmdlet/adding-parameter-sets-to-a-cmdlet.md). | -| [Runspace01 Code Samples](./runspace01-code-samples.md) | These are the code samples for the runspace described in [Creating a Console Application That Runs a Specified Command](/dotnet/csharp/programming-guide/inside-a-program/hello-world-your-first-program). | -| [Runspace02 Code Samples](./runspace02-code-samples.md) | This sample uses the [System.Management.Automation.RunspaceInvoke](/dotnet/api/System.Management.Automation.RunspaceInvoke) class to execute the `Get-Process` cmdlet synchronously. | -| [RunSpace03 Code Samples](./runspace03-code-samples.md) | These are the code samples for the runspace described in "Creating a Console Application That Runs a Specified Script". | -| [RunSpace04 Code Samples](./runspace04-code-samples.md) | This is a code sample for a runspace that uses the [System.Management.Automation.RunspaceInvoke](/dotnet/api/System.Management.Automation.RunspaceInvoke) class to execute a script that generates a terminating error. | -| [RunSpace05 Code Sample](./runspace05-code-sample.md) | | -| [RunSpace06 Code Sample](./runspace06-code-sample.md) | | -| [RunSpace07 Code Sample](./runspace07-code-sample.md) | | -| [RunSpace08 Code Sample](./runspace08-code-sample.md) | | -| [RunSpace09 Code Sample](./runspace09-code-sample.md) | | -| [RunSpace10 Code Sample](./runspace10-code-sample.md) | This is the source code for the Runspace10 sample, which adds a cmdlet to [System.Management.Automation.Runspaces.RunspaceConfiguration](/dotnet/api/System.Management.Automation.Runspaces.RunspaceConfiguration) and then uses the modified configuration information to create the runspace. | - -## See Also - -- [Windows PowerShell Programmer's Guide](./windows-powershell-programmer-s-guide.md) - -- [Windows PowerShell SDK](../windows-powershell-reference.md) diff --git a/reference/docs-conceptual/developer/toc.yml b/reference/docs-conceptual/developer/toc.yml index effd51f1f21d..63cf1f47a99b 100644 --- a/reference/docs-conceptual/developer/toc.yml +++ b/reference/docs-conceptual/developer/toc.yml @@ -1020,129 +1020,3 @@ items: href: ets/typeconverters.md - name: Errors and exceptions in ETS href: ets/errors-exceptions.md - - name: Windows PowerShell Programmer's Guide - href: prog-guide/windows-powershell-programmer-s-guide.md - items: - - name: How to Create a PowerShell Provider - href: prog-guide/how-to-create-a-windows-powershell-provider.md - items: - - name: Designing Your PowerShell Provider - href: prog-guide/designing-your-windows-powershell-provider.md - - name: Creating a Basic PowerShell Provider - href: prog-guide/creating-a-basic-windows-powershell-provider.md - - name: Creating a PowerShell Drive Provider - href: prog-guide/creating-a-windows-powershell-drive-provider.md - - name: Creating a PowerShell Item Provider - href: prog-guide/creating-a-windows-powershell-item-provider.md - - name: Creating a PowerShell Container Provider - href: prog-guide/creating-a-windows-powershell-container-provider.md - - name: Creating a PowerShell Navigation Provider - href: prog-guide/creating-a-windows-powershell-navigation-provider.md - - name: Creating a PowerShell Content Provider - href: prog-guide/creating-a-windows-powershell-content-provider.md - - name: Creating a PowerShell Property Provider - href: prog-guide/creating-a-windows-powershell-property-provider.md - - name: How to Create a Console Shell - href: prog-guide/how-to-create-a-console-shell.md - - name: PowerShell Concepts - href: prog-guide/windows-powershell-concepts.md - - name: PowerShell Sample Code - href: prog-guide/windows-powershell-sample-code.md - items: - - name: AccessDbProviderSample01 Code Sample - href: prog-guide/accessdbprovidersample01-code-sample.md - - name: AccessDbProviderSample02 Code Sample - href: prog-guide/accessdbprovidersample02-code-sample.md - - name: AccessDbProviderSample03 Code Sample - href: prog-guide/accessdbprovidersample03-code-sample.md - - name: AccessDbProviderSample04 Code Sample - href: prog-guide/accessdbprovidersample04-code-sample.md - - name: AccessDbProviderSample05 Code Sample - href: prog-guide/accessdbprovidersample05-code-sample.md - - name: AccessDbProviderSample06 Code Sample - href: prog-guide/accessdbprovidersample06-code-sample.md - - name: GetProc01 Code Samples - href: prog-guide/getproc01-code-samples.md - items: - - name: GetProc01 (C#) Sample Code - href: prog-guide/getproc01-csharp-sample-code.md - - name: GetProc01 (VB.NET) Sample Code - href: prog-guide/getproc01-vb-net-sample-code.md - - name: GetProc02 Code Samples - href: prog-guide/getproc02-code-samples.md - items: - - name: GetProc02 (C#) Sample Code - href: prog-guide/getproc02-csharp-sample-code.md - - name: GetProc02 (VB.NET) Sample Code - href: prog-guide/getproc02-vb-net-sample-code.md - - name: GetProc03 Code Samples - href: prog-guide/getproc03-code-samples.md - items: - - name: GetProc03 (C#) Sample Code - href: prog-guide/getproc03-csharp-sample-code.md - - name: GetProc03 (VB.NET) Sample Code - href: prog-guide/getproc03-vb-net-sample-code.md - - name: GetProc04 Code Samples - href: prog-guide/getproc04-code-samples.md - items: - - name: GetProc04 (C#) Sample Code - href: prog-guide/getproc04-csharp-sample-code.md - - name: GetProc04 (VB.NET) Sample Code - href: prog-guide/getproc04-vb-net-sample-code.md - - name: GetProc05 Code Samples - href: prog-guide/getproc05-code-samples.md - items: - - name: GetProc05 (C#) Sample Code - href: prog-guide/getproc05-csharp-sample-code.md - - name: GetProc05 (VB.NET) Sample Code - href: prog-guide/getproc05-vb-net-sample-code.md - - name: StopProc01 Code Samples - href: prog-guide/stopproc01-code-samples.md - items: - - name: StopProc01 (C#) Sample Code - href: prog-guide/stopproc01-csharp-sample-code.md - - name: StopProcessSample04 Code Samples - href: prog-guide/stopprocesssample04-code-samples.md - items: - - name: StopProcessSample04 (C#) Sample Code - href: prog-guide/stopprocesssample04-csharp-sample-code.md - - name: StopProcessSample04 (VB.NET) Sample Code - href: prog-guide/stopprocesssample04-vb-net-sample-code.md - - name: Runspace01 Code Samples - href: prog-guide/runspace01-code-samples.md - items: - - name: Runspace01 (C#) Code Sample - href: prog-guide/runspace01-csharp-code-sample.md - - name: Runspace01 (VB.NET) Code Sample - href: prog-guide/runspace01-vb-net-code-sample.md - - name: Runspace02 Code Samples - href: prog-guide/runspace02-code-samples.md - items: - - name: Runspace02 (C#) Code Sample - href: prog-guide/runspace02-csharp-code-sample.md - - name: Runspace02 (VB.NET) Code Sample - href: prog-guide/runspace02-vb-net-code-sample.md - - name: RunSpace03 Code Samples - href: prog-guide/runspace03-code-samples.md - items: - - name: RunSpace03 (C#) Code Sample - href: prog-guide/runspace03-csharp-code-sample.md - - name: RunSpace03 (VB.NET) Code Sample - href: prog-guide/runspace03-vb-net-code-sample.md - - name: RunSpace04 Code Samples - href: prog-guide/runspace04-code-samples.md - items: - - name: RunSpace04 (VB.NET) Code Sample - href: prog-guide/runspace04-vb-net-code-sample.md - - name: RunSpace05 Code Sample - href: prog-guide/runspace05-code-sample.md - - name: RunSpace06 Code Sample - href: prog-guide/runspace06-code-sample.md - - name: RunSpace07 Code Sample - href: prog-guide/runspace07-code-sample.md - - name: RunSpace08 Code Sample - href: prog-guide/runspace08-code-sample.md - - name: RunSpace09 Code Sample - href: prog-guide/runspace09-code-sample.md - - name: RunSpace10 Code Sample - href: prog-guide/runspace10-code-sample.md From a04cc6468ef5b9467704d5e919fd03ce1a969102 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 20 Nov 2025 15:54:48 -0600 Subject: [PATCH 2/2] readd dependent repo --- .openpublishing.publish.config.json | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.openpublishing.publish.config.json b/.openpublishing.publish.config.json index fd2ea38c768e..e9106bf0781e 100644 --- a/.openpublishing.publish.config.json +++ b/.openpublishing.publish.config.json @@ -18,6 +18,12 @@ "path_to_root": "_themes", "url": "https://github.com/Microsoft/templates.docs.msft" }, + { + "branch": "main", + "branch_mapping": {}, + "path_to_root": "powershell-sdk-samples", + "url": "https://github.com/MicrosoftDocs/powershell-sdk-samples" + }, { "branch": "master", "path_to_root": "_themes.pdf",