Skip to content

Migrate user docs to Docs repo #19871

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
daxian-dbw merged 6 commits into from
Jul 10, 2023
Merged

Migrate user docs to Docs repo #19871

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
b0da2a2
Migrate user docs to Docs repo
sdwheeler Jun 29, 2023
35eac05
Fix spelling warnings and commit suggestion
sdwheeler Jul 10, 2023
9795452
update spelling file again
sdwheeler Jul 10, 2023
1428365
update spelling file
sdwheeler Jul 10, 2023
462b5ce
Fixed spelling errors
sdwheeler Jul 10, 2023
95878d5
fix markdownlist error
sdwheeler Jul 10, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions .spelling
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1316,6 +1316,13 @@ microsoft.extensions.objectpool
microsoft.codeanalysis.analyzers
benchmarkdotnet
winforms
MicrosoftDocs
about_Scripts
debugging-from-commandline
about_Object_Creation
about_Functions_Advanced
Microsoft.PowerShell.SDK
NuGet.org.
- CHANGELOG.md
aavdberg
asrosent
Expand Down Expand Up @@ -1718,3 +1725,9 @@ preview.3.23178.7
PoolNames
techguy16
sdwheeler
MicrosoftDocs
about_Scripts
about_Object_Creation
about_Functions_Advanced
Microsoft.PowerShell.SDK
NuGet.org.
46 changes: 32 additions & 14 deletions docs/DOCSMIGRATION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,20 +1,38 @@
# Documentation Migration

The docs folder in this repo contains a lot of documentation about the PowerShell source code and build environment.
It also has contained documentation about installing and using PowerShell.
That documentation belongs in the [PowerShell/PowerShell-Docs](https://github.com/PowerShell/PowerShell-Docs) repo.
The docs folder in this repository contains documentation about the PowerShell source code and build
environment.

We are in the process of migrating the user-focused articles to the docs repo.
This file records which files have been migrated.
User-focused documentation has been moved to the [MicrosoftDocs/PowerShell-Docs][01] repository.

## 2018-05-18
The files from the `learning-powershell` folder have been removed from this repository. This list
provides links to suitable replacements.

The following files have been moved to the PowerShell/PowerShell-Docs repo.
- **create-powershell-scripts.md**
- [about_Scripts][06]
- **debugging-from-commandline.md**
- [about_Debuggers][04]
- **powershell-beginners-guide.md**
- [PowerShell 101][09]
- **README.md**
- [Install PowerShell on Windows, Linux, and macOS][07]
- [Using Visual Studio Code (VS Code)][11]
- [Pester Guides][02]
- [Writing Pester Tests Guidelines][03]
- [PowerShell learning resources][08]
- **working-with-powershell-objects.md**
- [about_Object_Creation][05]
- [Crescendo overview][10]

| Original file location | New location in PowerShell/PowerShell-Docs |
|--------------------------------|----------------------------------------------------------------------------|
| `docs/installation/linux.md` | `reference/docs-conceptual/setup/Installing-PowerShell-Core-on-Linux.md` |
| `docs/installation/macos.md` | `reference/docs-conceptual/setup/Installing-PowerShell-Core-on-macOS.md` |
| `docs/installation/windows.md` | `reference/docs-conceptual/setup/Installing-PowerShell-Core-on-Windows.md` |
| `docs/BREAKINGCHANGES.md` | `reference/docs-conceptual/whats-new/breaking-changes-ps6.md` |
| `docs/KNOWNISSUES.md` | `reference/docs-conceptual/whats-new/known-issues-ps6.md` |
<!-- link references -->
[01]: https://github.com/MicrosoftDocs/PowerShell-Docs
[02]: https://github.com/pester/Pester
[03]: https://github.com/PowerShell/PowerShell/blob/master/docs/testing-guidelines/WritingPesterTests.md
[04]: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_debuggers
[05]: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_object_creation
[06]: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_scripts
[07]: https://learn.microsoft.com/powershell/scripting/install/installing-powershell
[08]: https://learn.microsoft.com/powershell/scripting/learn/more-powershell-learning
[09]: https://learn.microsoft.com/powershell/scripting/learn/ps101/00-introduction
[10]: https://learn.microsoft.com/powershell/utility-modules/crescendo/overview?view=ps-modules
[11]: https://learn.microsoft.com/powershell/scripting/dev-cross-plat/vscode/using-vscode
96 changes: 54 additions & 42 deletions docs/FAQ.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,89 +2,86 @@

## Where can I learn PowerShell's syntax?

[SS64.com](https://ss64.com/ps/syntax.html) is a good resource.
[Microsoft Docs](https://docs.microsoft.com/powershell/scripting/overview) is another excellent resource.
- [What is PowerShell?][12]
- [Discover PowerShell][09]
- [PowerShell 101][11]
- [PowerShell learning resources][10]

## What are the best practices and style?

The [PoshCode][] unofficial guide is our reference.

[PoshCode]: https://github.com/PoshCode/PowerShellPracticeAndStyle
The [PoshCode][03] unofficial guide is our reference.

## What are PowerShell's scoping rules?

- Variables are created in your current scope unless explicitly indicated.
- Variables are visible in a child scope unless explicitly indicated.
- Variables created in a child scope are not visible to a parent unless
explicitly indicated.
- Variables created in a child scope are not visible to a parent unless explicitly indicated.
- Variables may be placed explicitly in a scope.

### Things that create a scope

- [functions](https://ss64.com/ps/syntax-functions.html)
- [call operator](https://ss64.com/ps/call.html) (`& { }`)
- [script invocations](https://ss64.com/ps/syntax-run.html)
- [about_Functions_Advanced][04]
- [about Operators - Call operator][06] (`& { }`)
- [about Scopes][08]

### Things that operate in the current scope

- [source operator](https://ss64.com/ps/source.html) (`. { }`)
- [statements](https://ss64.com/ps/statements.html) (`if .. else`, `for`, `switch`, etc.)
- [about Operators - Dot source operator][07] (`. { }`)
- [about Language Keywords][05] (`if .. else`, `for`, `switch`, etc.)

## Why didn't an error throw an exception?

Error handling in PowerShell is a bit weird, as not all errors result in catchable exceptions by default.
Setting `$ErrorActionPreference = 'Stop'` will likely do what you want;
that is, cause non-terminating errors instead to terminate.
Read [An Introduction To Error Handling in PowerShell][error] for more information.

[error]: https://gist.github.com/TravisEz13/9bb811c63b88501f3beec803040a9996
Error handling in PowerShell is unique, as not all errors result in catchable exceptions by default.
Setting `$ErrorActionPreference = 'Stop'` will likely do what you want; that is, cause
non-terminating errors instead to terminate. Read the [GitHub issue][02] for more information.

## Where do I get the PowerShell Core SDK package?

The SDK NuGet package `Microsoft.PowerShell.SDK` is provided for developers to write .NET Core C# code targeting PowerShell Core.
PowerShell NuGet packages for releases starting from v6.0.0-alpha.9 will be published to the [powershell-core][] myget feed.
The SDK NuGet package **Microsoft.PowerShell.SDK** is provided for developers to write C# code
targeting PowerShell. PowerShell NuGet packages are published to [Microsoft.PowerShell.SDK][13] on
NuGet.org.

To use the `Microsoft.PowerShell.SDK` NuGet package, declare `PackageReference` tags in your `.csproj` file as follows:
To use the `Microsoft.PowerShell.SDK` NuGet package, declare `PackageReference` tags in your
`.csproj` file as follows:

```xml
<ItemGroup>
<PackageReference Include="Microsoft.PowerShell.SDK" Version="6.0.0-beta.9" />
<PackageReference Include="Microsoft.PowerShell.Commands.Diagnostics" Version="6.0.0-beta.9" />
<PackageReference Include="Microsoft.WSMan.Management" Version="6.0.0-beta.9"/>
<PackageReference Include="Microsoft.PowerShell.SDK" Version="7.3.5" />
<PackageReference Include="Microsoft.PowerShell.Commands.Diagnostics" Version="7.3.5" />
<PackageReference Include="Microsoft.WSMan.Management" Version="7.3.5"/>
</ItemGroup>
```

[powershell-core]: https://powershell.myget.org/gallery/powershell-core

## Why did my build fail?

There are few common issues with the build.
The easiest way to resolve most issues with the build is to run `Start-PSBuild -Clean`.
There are few common issues with the build. The easiest way to resolve most issues with the build is
to run `Start-PSBuild -Clean`.

### Dependency changed

If package dependencies were changed in any `project.json`, you need to manually
run `dotnet restore` to update your local dependency graphs.
`Start-PSBuild -Restore` can automatically do this.
If package dependencies were changed in any `project.json`, you need to manually run
`dotnet restore` to update your local dependency graphs. `Start-PSBuild -Restore` can automatically
do this.

### Resource changed

`Start-PSBuild` automatically calls `Start-ResGen` on the very first run.
On subsequent runs, you may need to explicitly use `Start-PSBuild -ResGen` command.
`Start-PSBuild` automatically calls `Start-ResGen` on the very first run. On subsequent runs, you
may need to explicitly use `Start-PSBuild -ResGen` command.

Try it, when you see compilation error about *strings.

[More details](dev-process/resx-files.md) about resource.
[More details][01] about resource.

### TypeGen

Similar to `-ResGen` parameter, there is `-TypeGen` parameter that triggers regeneration of type catalog.
Similar to `-ResGen` parameter, there is `-TypeGen` parameter that triggers regeneration of type
catalog.

## Why did `Start-PSBuild` tell me to update `dotnet`?

We depend on the latest version of the .NET CLI, as we use the output of `dotnet
--info` to determine the current runtime identifier.
Without this information, our build function can't know where `dotnet` is going to place the build artifacts.
We depend on the latest version of the .NET CLI, as we use the output of `dotnet --info` to
determine the current runtime identifier. Without this information, our build function can't know
where `dotnet` is going to place the build artifacts.

You can automatically install this using `Start-PSBootstrap`.
**However, you must first manually uninstall other versions of the CLI.**
Expand All @@ -98,7 +95,22 @@ If you have installed by using any of the following means:

You *must* manually uninstall it.

Additionally, if you've just unzipped their binary drops (or used their obtain
scripts, which do essentially the same thing), you must manually delete the
folder, as the .NET CLI team re-engineered how their binaries are setup, such
that new packages' binaries get stomped on by old packages' binaries.
Additionally, if you've just unzipped their binary drops (or used their obtain scripts, which do
essentially the same thing), you must manually delete the folder, as the .NET CLI team re-engineered
how their binaries are setup, such that new packages' binaries get stomped on by old packages'
binaries.

<!-- updated link references -->
[01]: dev-process/resx-files.md
[02]: https://github.com/MicrosoftDocs/PowerShell-Docs/issues/1583
[03]: https://github.com/PoshCode/PowerShellPracticeAndStyle
[04]: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_advanced
[05]: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_language_keywords
[06]: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_operators#call-operator-
[07]: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_operators#dot-sourcing-operator-
[08]: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_scopes
[09]: https://learn.microsoft.com/powershell/scripting/discover-powershell
[10]: https://learn.microsoft.com/powershell/scripting/learn/more-powershell-learning
[11]: https://learn.microsoft.com/powershell/scripting/learn/ps101/00-introduction
[12]: https://learn.microsoft.com/powershell/scripting/overview
[13]: https://www.nuget.org/packages/Microsoft.PowerShell.SDK
127 changes: 0 additions & 127 deletions docs/learning-powershell/README.md
View file
Open in desktop

This file was deleted.

Loading