diff --git a/.config/tsaoptions.json b/.config/tsaoptions.json new file mode 100644 index 000000000..28761179f --- /dev/null +++ b/.config/tsaoptions.json @@ -0,0 +1,8 @@ +{ + "instanceUrl": "https://msazure.visualstudio.com", + "projectName": "One", + "areaPath": "One\\MGMT\\Compute\\Powershell\\Powershell", + "notificationAliases": [ "andschwa@microsoft.com", "slee@microsoft.com" ], + "codebaseName": "PowerShell_PowerShellEditorServices_20240313", + "tools": [ "CredScan", "PoliCheck", "BinSkim" ] +} diff --git a/.github/release.yml b/.github/release.yml new file mode 100644 index 000000000..bb7a942a4 --- /dev/null +++ b/.github/release.yml @@ -0,0 +1,16 @@ +changelog: + exclude: + labels: + - Ignore + authors: + - dependabot[bot] + categories: + - title: Enhancements & Features ✨ + labels: + - Issue-Enhancement + - title: Squashed Bugs 🐛 + labels: + - Issue-Bug + - title: Other Changes 🙏 + labels: + - "*" diff --git a/.github/workflows/ci-test.yml b/.github/workflows/ci-test.yml index 934962034..fd93eb384 100644 --- a/.github/workflows/ci-test.yml +++ b/.github/workflows/ci-test.yml @@ -37,6 +37,9 @@ jobs: 6.0.x 7.0.x 8.0.x + source-url: https://pkgs.dev.azure.com/mscodehub/PowerShellCore/_packaging/PowerShellCore_PublicPackages/nuget/v3/index.json + env: + NUGET_AUTH_TOKEN: ${{ secrets.AZURE_NUGET_TOKEN }} - name: Install PSResources shell: pwsh diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml index 152ff2df8..018eaaa77 100644 --- a/.github/workflows/codeql-analysis.yml +++ b/.github/workflows/codeql-analysis.yml @@ -33,6 +33,9 @@ jobs: with: cache: true cache-dependency-path: '**/packages.lock.json' + source-url: https://pkgs.dev.azure.com/mscodehub/PowerShellCore/_packaging/PowerShellCore_PublicPackages/nuget/v3/index.json + env: + NUGET_AUTH_TOKEN: ${{ secrets.AZURE_NUGET_TOKEN }} - name: Initialize CodeQL uses: github/codeql-action/init@v3 diff --git a/.github/workflows/emacs-test.yml b/.github/workflows/emacs-test.yml index d5c51de0e..31f840581 100644 --- a/.github/workflows/emacs-test.yml +++ b/.github/workflows/emacs-test.yml @@ -27,6 +27,9 @@ jobs: with: cache: true cache-dependency-path: '**/packages.lock.json' + source-url: https://pkgs.dev.azure.com/mscodehub/PowerShellCore/_packaging/PowerShellCore_PublicPackages/nuget/v3/index.json + env: + NUGET_AUTH_TOKEN: ${{ secrets.AZURE_NUGET_TOKEN }} - name: Install PSResources shell: pwsh diff --git a/.github/workflows/vim-test.yml b/.github/workflows/vim-test.yml index 76e5c5095..b434fcb45 100644 --- a/.github/workflows/vim-test.yml +++ b/.github/workflows/vim-test.yml @@ -27,6 +27,9 @@ jobs: with: cache: true cache-dependency-path: '**/packages.lock.json' + source-url: https://pkgs.dev.azure.com/mscodehub/PowerShellCore/_packaging/PowerShellCore_PublicPackages/nuget/v3/index.json + env: + NUGET_AUTH_TOKEN: ${{ secrets.AZURE_NUGET_TOKEN }} - name: Install PSResources shell: pwsh diff --git a/.pipelines/PowerShellEditorServices-Official.yml b/.pipelines/PowerShellEditorServices-Official.yml new file mode 100644 index 000000000..f1d47c08c --- /dev/null +++ b/.pipelines/PowerShellEditorServices-Official.yml @@ -0,0 +1,182 @@ +################################################################################# +# OneBranch Pipelines # +# This pipeline was created by EasyStart from a sample located at: # +# https://aka.ms/obpipelines/easystart/samples # +# Documentation: https://aka.ms/obpipelines # +# Yaml Schema: https://aka.ms/obpipelines/yaml/schema # +# Retail Tasks: https://aka.ms/obpipelines/tasks # +# Support: https://aka.ms/onebranchsup # +################################################################################# + +trigger: none + +parameters: +- name: debug + displayName: Enable debug output + type: boolean + default: false + +variables: + system.debug: ${{ parameters.debug }} + BuildConfiguration: Release + WindowsContainerImage: onebranch.azurecr.io/windows/ltsc2019/vse2022:latest + DOTNET_NOLOGO: true + DOTNET_CLI_TELEMETRY_OPTOUT: true + DOTNET_GENERATE_ASPNET_CERTIFICATE: false + +resources: + repositories: + - repository: templates + type: git + name: OneBranch.Pipelines/GovernedTemplates + ref: refs/heads/main + +extends: + # https://aka.ms/obpipelines/templates + template: v2/OneBranch.Official.CrossPlat.yml@templates + parameters: + globalSdl: # https://aka.ms/obpipelines/sdl + asyncSdl: + enabled: true + forStages: [build] + stages: + - stage: build + jobs: + - job: main + displayName: Build package + pool: + type: windows + variables: + ob_outputDirectory: $(Build.SourcesDirectory)/module + steps: + - pwsh: | + [xml]$xml = Get-Content PowerShellEditorServices.Common.props + $version = $xml.Project.PropertyGroup.VersionPrefix + Write-Output "##vso[task.setvariable variable=version;isOutput=true]$version" + name: package + displayName: Get version from project properties + - task: onebranch.pipeline.version@1 + displayName: Set OneBranch version + inputs: + system: Custom + customVersion: $(package.version) + - task: UseDotNet@2 + displayName: Install .NET 8.x SDK + inputs: + packageType: sdk + version: 8.x + - task: UseDotNet@2 + displayName: Install .NET 7.x runtime + inputs: + packageType: runtime + version: 7.x + - task: UseDotNet@2 + displayName: Install .NET 6.x runtime + inputs: + packageType: runtime + version: 6.x + - task: PowerShell@2 + displayName: Install PSResources + inputs: + pwsh: true + filePath: tools/installPSResources.ps1 + - task: PowerShell@2 + displayName: Build and test + inputs: + targetType: inline + pwsh: true + script: Invoke-Build TestFull -Configuration $(BuildConfiguration) + - task: PublishTestResults@2 + displayName: Publish test results + inputs: + testRunner: VSTest + testResultsFiles: '**/*.trx' + failTaskOnFailedTests: true + - task: PowerShell@2 + displayName: Assert release configuration + inputs: + targetType: inline + pwsh: true + script: | + $assembly = [Reflection.Assembly]::LoadFile("$(Build.SourcesDirectory)/module/PowerShellEditorServices/bin/Core/Microsoft.PowerShell.EditorServices.Hosting.dll") + if ($assembly.GetCustomAttributes([System.Diagnostics.DebuggableAttribute], $true).IsJITOptimizerDisabled) { + Write-Host "##vso[task.LogIssue type=error;]Was not built in release configuration!" + exit 1 + } + - task: onebranch.pipeline.signing@1 + displayName: Sign 1st-party files + inputs: + command: sign + signing_environment: external_distribution + search_root: $(Build.SourcesDirectory)/module + files_to_sign: | + **/*.ps1; + **/*.psd1; + **/*.psm1; + **/*.ps1xml; + **/Microsoft.PowerShell.EditorServices*.dll; + !Plaster/*; + - task: onebranch.pipeline.signing@1 + displayName: Sign 3rd-party files + inputs: + command: sign + signing_environment: 135020002 + search_root: $(Build.SourcesDirectory)/module + files_to_sign: | + **/MediatR.dll; + **/Nerdbank.Streams.dll; + **/Newtonsoft.Json.dll; + **/OmniSharp.Extensions*.dll; + **/Serilog*.dll; + **/System.Reactive.dll; + Plaster/**/*.ps1; + Plaster/**/*.psd1; + Plaster/**/*.psm1; + - stage: release + dependsOn: build + variables: + version: $[ stageDependencies.build.main.outputs['package.version'] ] + drop: $(Pipeline.Workspace)/drop_build_main + jobs: + - job: validation + displayName: Manual validation + pool: + type: agentless + timeoutInMinutes: 1440 + steps: + - task: ManualValidation@0 + displayName: Wait 24 hours for validation + inputs: + notifyUsers: $(Build.RequestedForEmail) + instructions: Please validate the release + timeoutInMinutes: 1440 + - job: github + dependsOn: validation + displayName: Publish draft to GitHub + pool: + type: windows + variables: + ob_outputDirectory: $(Build.SourcesDirectory)/out + steps: + - download: current + displayName: Download artifacts + - task: ArchiveFiles@2 + displayName: Zip signed artifacts + inputs: + rootFolderOrFile: $(drop) + includeRootFolder: false + archiveType: zip + archiveFile: out/PowerShellEditorServices.zip + - task: GitHubRelease@1 + displayName: Create GitHub release + inputs: + gitHubConnection: GitHub + repositoryName: PowerShell/PowerShellEditorServices + assets: out/PowerShellEditorServices.zip + tagSource: userSpecifiedTag + tag: v$(version) + isDraft: true + addChangeLog: false + releaseNotesSource: inline + releaseNotesInline: | + # TODO: Generate release notes on GitHub! diff --git a/.vsts-ci/azure-pipelines-ci.yml b/.vsts-ci/azure-pipelines-ci.yml deleted file mode 100644 index 325009518..000000000 --- a/.vsts-ci/azure-pipelines-ci.yml +++ /dev/null @@ -1,45 +0,0 @@ -name: CI-$(Build.SourceBranchName)-$(Date:yyyyMMdd)$(Rev:.rr) - -# NOTE: This was superceded by the GitHub Actions workflow. -pr: none -trigger: none - -variables: - # Don't download unneeded packages - - name: DOTNET_NOLOGO - value: 'true' - # Improve performance by not sending telemetry - - name: DOTNET_CLI_TELEMETRY_OPTOUT - value: 'true' - # Improve performance by not generating certificates - - name: DOTNET_GENERATE_ASPNET_CERTIFICATE - value: 'false' - -jobs: -- job: windows2022 - displayName: Windows 2022 - pool: - vmImage: windows-2022 - steps: - - template: templates/ci-general.yml - -- job: windows2019 - displayName: Windows 2019 - pool: - vmImage: windows-2019 - steps: - - template: templates/ci-general.yml - -- job: macOS12 - displayName: macOS 12 - pool: - vmImage: macOS-12 - steps: - - template: templates/ci-general.yml - -- job: ubuntu2004 - displayName: Ubuntu 20.04 - pool: - vmImage: ubuntu-20.04 - steps: - - template: templates/ci-general.yml diff --git a/.vsts-ci/azure-pipelines-release.yml b/.vsts-ci/azure-pipelines-release.yml deleted file mode 100644 index e5aa01b2a..000000000 --- a/.vsts-ci/azure-pipelines-release.yml +++ /dev/null @@ -1,68 +0,0 @@ -name: Release-$(Build.SourceBranchName)-$(Date:yyyyMMdd)$(Rev:.rr) - -pr: none - -trigger: - branches: - include: - - release - -variables: - # Don't download unneeded packages - - name: DOTNET_NOLOGO - value: 'true' - # Improve performance by not sending telemetry - - name: DOTNET_CLI_TELEMETRY_OPTOUT - value: 'true' - # Improve performance by not generating certificates - - name: DOTNET_GENERATE_ASPNET_CERTIFICATE - value: 'false' - -resources: - repositories: - - repository: ComplianceRepo - type: github - endpoint: GitHub - name: PowerShell/compliance - - repository: vscode-powershell - type: git - name: vscode-powershell - -stages: -- stage: Build - displayName: Build the release - jobs: - - job: Build - pool: - name: 1ES - demands: ImageOverride -equals PSMMS2019-Secure - steps: - - template: templates/ci-general.yml - -- stage: Sign - displayName: Sign the release - jobs: - - job: Sign - pool: - name: 1ES - demands: ImageOverride -equals PSMMS2019-Secure - variables: - - group: ESRP - steps: - - template: templates/release-general.yml - -- stage: Publish - displayName: Publish the draft release - jobs: - - deployment: Publish - environment: PowerShellEditorServices - pool: - name: 1ES - demands: ImageOverride -equals PSMMSUbuntu20.04-Secure - variables: - - group: Publish - strategy: - runOnce: - deploy: - steps: - - template: templates/publish-general.yml diff --git a/.vsts-ci/misc-analysis.yml b/.vsts-ci/misc-analysis.yml deleted file mode 100644 index 4d1229508..000000000 --- a/.vsts-ci/misc-analysis.yml +++ /dev/null @@ -1,20 +0,0 @@ -name: Misc-$(Build.SourceBranchName)-$(Date:yyyyMMdd)$(Rev:.rr) - -trigger: - - gh-readonly-queue/main/* - -resources: - repositories: - - repository: ComplianceRepo - type: github - endpoint: GitHub - name: PowerShell/compliance - -jobs: -- job: Compliance - pool: - vmImage: windows-latest - steps: - - checkout: self - - checkout: ComplianceRepo - - template: ci-compliance.yml@ComplianceRepo diff --git a/.vsts-ci/templates/ci-general.yml b/.vsts-ci/templates/ci-general.yml deleted file mode 100644 index f18e26ada..000000000 --- a/.vsts-ci/templates/ci-general.yml +++ /dev/null @@ -1,85 +0,0 @@ -steps: -- task: PowerShell@2 - displayName: PowerShell version - inputs: - targetType: inline - pwsh: true - script: $PSVersionTable - -- task: UseDotNet@2 - displayName: Install .NET 8.x SDK - inputs: - packageType: sdk - version: 8.x - -- task: UseDotNet@2 - displayName: Install .NET 7.x runtime - inputs: - packageType: runtime - version: 7.x - -- task: UseDotNet@2 - displayName: Install .NET 6.x runtime - inputs: - packageType: runtime - version: 6.x - -- task: PowerShell@2 - displayName: Install PSResources - inputs: - pwsh: true - filePath: tools/installPSResources.ps1 - -- task: PowerShell@2 - displayName: Build and test - inputs: - targetType: inline - pwsh: true - script: Invoke-Build TestFull -Configuration Release - -- task: PublishTestResults@2 - displayName: Publish test results - inputs: - testRunner: VSTest - testResultsFiles: '**/*.trx' - condition: succeededOrFailed() - -- task: PowerShell@2 - displayName: Assert PowerShellEditorServices release configuration - inputs: - targetType: inline - pwsh: true - script: | - $assembly = [Reflection.Assembly]::LoadFile("$(Build.SourcesDirectory)/module/PowerShellEditorServices/bin/Core/Microsoft.PowerShell.EditorServices.Hosting.dll") - if ($assembly.GetCustomAttributes([System.Diagnostics.DebuggableAttribute], $true).IsJITOptimizerDisabled) { - Write-Host "##vso[task.LogIssue type=error;] PowerShell Editor Services bits were not built in release configuration!" - exit 1 - } - -# NOTE: We zip the artifacts because they're ~20 MB compressed, but ~300 MB raw, -# and we have limited pipeline artifact storage space. -- task: ArchiveFiles@2 - displayName: Zip build output - inputs: - rootFolderOrFile: module - includeRootFolder: false - archiveType: zip - archiveFile: PowerShellEditorServices-Build.zip - verbose: true - -- publish: PowerShellEditorServices-Build.zip - artifact: PowerShellEditorServices-Build-$(System.JobId) - displayName: Publish build output archive - -- task: ArchiveFiles@2 - displayName: Zip sources with `project.assets.json` - inputs: - rootFolderOrFile: src - includeRootFolder: false - archiveType: zip - archiveFile: PowerShellEditorServices-Sources.zip - verbose: true - -- publish: PowerShellEditorServices-Sources.zip - artifact: PowerShellEditorServices-Sources-$(System.JobId) - displayName: Publish sources archive diff --git a/.vsts-ci/templates/publish-general.yml b/.vsts-ci/templates/publish-general.yml deleted file mode 100644 index cb26033b3..000000000 --- a/.vsts-ci/templates/publish-general.yml +++ /dev/null @@ -1,12 +0,0 @@ -steps: -- checkout: self -- checkout: vscode-powershell - -- download: current - artifact: PowerShellEditorServices - displayName: Download signed pipeline artifacts - -- pwsh: | - $(Build.SourcesDirectory)/vscode-powershell/tools/setupReleaseTools.ps1 -Token $(GitHubToken) - New-DraftRelease -RepositoryName PowerShellEditorServices -Assets $(Pipeline.Workspace)/PowerShellEditorServices/PowerShellEditorServices.zip - displayName: Drafting a GitHub Release diff --git a/.vsts-ci/templates/release-general.yml b/.vsts-ci/templates/release-general.yml deleted file mode 100644 index bc4abdfa5..000000000 --- a/.vsts-ci/templates/release-general.yml +++ /dev/null @@ -1,96 +0,0 @@ -steps: -- download: current - displayName: Download unsigned pipeline artifacts - -- task: ExtractFiles@1 - displayName: Extract unsigned artifacts - inputs: - archiveFilePatterns: $(Pipeline.Workspace)/PowerShellEditorServices-Build-*/PowerShellEditorServices-Build.zip - destinationFolder: $(Pipeline.Workspace)/Unsigned - cleanDestinationFolder: true - -- checkout: ComplianceRepo - -# NOTE: The signing templates explicitly copy everything along as they run, so -# the last output path has every signed (and intentionally unsigned) file. -- template: EsrpSign.yml@ComplianceRepo - parameters: - buildOutputPath: $(Pipeline.Workspace)/Unsigned - signOutputPath: $(Pipeline.Workspace)/FirstPartySigned - alwaysCopy: true - certificateId: CP-230012 # Authenticode certificate - shouldSign: true # We always want to sign - useMinimatch: true # This enables the use of globbing - pattern: | - # PowerShellEditorServices Script - PowerShellEditorServices/*.{ps1,psd1,psm1,ps1xml} - PowerShellEditorServices/Commands/**/*.{ps1,psd1,psm1,ps1xml} - # PowerShellEditorServices Binaries - PowerShellEditorServices/**/Microsoft.PowerShell.EditorServices*.dll - -- template: EsrpSign.yml@ComplianceRepo - parameters: - buildOutputPath: $(Pipeline.Workspace)/FirstPartySigned - signOutputPath: $(Pipeline.Workspace)/ThirdPartySigned - alwaysCopy: true - certificateId: CP-231522 # Third-party certificate - shouldSign: true # We always want to sign - useMinimatch: true # This enables the use of globbing - pattern: | - **/MediatR.dll - **/Nerdbank.Streams.dll - **/Newtonsoft.Json.dll - **/OmniSharp*.dll - **/Serilog*.dll - -# The SBOM generation requires our original sources with the `dotnet restore` -# produced `project.assets.json` files. -- task: ExtractFiles@1 - displayName: Extract source artifacts - inputs: - archiveFilePatterns: $(Pipeline.Workspace)/PowerShellEditorServices-Sources-*/PowerShellEditorServices-Sources.zip - destinationFolder: $(Pipeline.Workspace)/Sources - cleanDestinationFolder: true - -- template: Sbom.yml@ComplianceRepo - parameters: - BuildDropPath: $(Pipeline.Workspace)/ThirdPartySigned - Build_Repository_Uri: https://github.com/PowerShell/PowerShellEditorServices.git - packageName: PowerShellEditorServices - packageVersion: $(System.JobId) - sourceScanPath: $(Pipeline.Workspace)/Sources - -- task: ArchiveFiles@2 - displayName: Zip signed artifacts - inputs: - rootFolderOrFile: $(Pipeline.Workspace)/ThirdPartySigned - includeRootFolder: false - archiveType: zip - archiveFile: PowerShellEditorServices.zip - replaceExistingArchive: true - verbose: true - -- checkout: self - -- template: assembly-module-compliance.yml@ComplianceRepo - parameters: - # binskim - AnalyzeTarget: $(Pipeline.Workspace)/*.dll - AnalyzeSymPath: 'SRV*' - # component-governance: requires the `project.assets.json` files - sourceScanPath: $(Pipeline.Workspace)/Sources - # credscan - suppressionsFile: '' - # TermCheck AKA PoliCheck - targetArgument: $(Build.SourcesDirectory)/PowerShellEditorServices - optionsUEPATH: $(Build.SourcesDirectory)/PowerShellEditorServices/tools/terms/UserExclusions.xml - optionsRulesDBPath: '' - optionsFTPath: $(Build.SourcesDirectory)/PowerShellEditorServices/tools/terms/FileTypeSet.xml - # tsa-upload - codeBaseName: PowerShell_PowerShellEditorServices_20210201 - # We don't use any Windows APIs directly, so we don't need API scan - APIScan: false - -- publish: PowerShellEditorServices.zip - artifact: PowerShellEditorServices - displayName: Publish signed pipeline artifacts diff --git a/CHANGELOG.md b/CHANGELOG.md index 8b2ba1b99..10c90056d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,10 @@ # PowerShell Editor Services Release History +## v3.18.1 +### Tuesday, March 19, 2024 + +Servicing release with updated pipeline! + ## v3.18.0 ### Tuesday, March 5, 2024 diff --git a/NuGet.Config b/NuGet.Config index 16746d63c..f04dcd513 100644 --- a/NuGet.Config +++ b/NuGet.Config @@ -1,10 +1,7 @@ - + - - - - - - - + + + + diff --git a/PowerShellEditorServices.Common.props b/PowerShellEditorServices.Common.props index 6e0a04574..80d45b7ba 100644 --- a/PowerShellEditorServices.Common.props +++ b/PowerShellEditorServices.Common.props @@ -1,6 +1,6 @@ - 3.18.0 + 3.18.1 Microsoft © Microsoft Corporation. diff --git a/README.md b/README.md index 1ad6cca03..bb672b7f9 100644 --- a/README.md +++ b/README.md @@ -8,14 +8,17 @@ functionality needed to enable a consistent and robust PowerShell development experience in almost any editor or integrated development environment (IDE). -## PowerShell [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) clients using PowerShell Editor Services +## [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) clients using PowerShell Editor Services: -The functionality in PowerShell Editor Services is already available in the following editor extensions: +The functionality in PowerShell Editor Services is available in the following editor extensions: -- [The VSCode PowerShell extension](https://github.com/PowerShell/vscode-powershell), also available in Azure Data Studio -- [coc-powershell](https://github.com/yatli/coc-powershell), a vim/neovim PowerShell plugin -- [The IntelliJ PowerShell plugin](https://github.com/ant-druha/intellij-powershell) +- [PowerShell for Visual Studio Code](https://github.com/PowerShell/vscode-powershell), also available in Azure Data Studio - [lsp-pwsh](https://github.com/emacs-lsp/lsp-mode/blob/master/clients/lsp-pwsh.el), an Emacs PowerShell plugin +- [intellij-powershell](https://github.com/ant-druha/intellij-powershell), adds PowerShell language support to IntelliJ-based IDEs +- [coc-powershell](https://github.com/yatli/coc-powershell), a Vim and Neovim plugin + +Please note that other than PowerShell for Visual Studio Code, these clients are community maintained and may be very out of date. +It is recommended that you simply use an LSP plugin for your editor and configure it as demonstrated [below](#Usage). ## Features @@ -24,55 +27,67 @@ The functionality in PowerShell Editor Services is already available in the foll - Statement completions (IntelliSense) - Real-time semantic analysis of scripts using PowerShell Script Analyzer - The Debugging Service simplifies interaction with the PowerShell debugger (breakpoints, variables, call stack, etc.) -- The [$psEditor API](https://github.com/PowerShell/PowerShellEditorServices/blob/main/docs/guide/extensions.md) enables scripting of the host editor +- The [$psEditor API](docs/guide/extensions.md) enables scripting of the host editor - A full, Extension Terminal experience for interactive development and debugging ## Usage -If you're looking to integrate PowerShell Editor Services into your [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) compliant editor or client, we support two ways of connecting. +If you're looking to integrate PowerShell Editor Services into your [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) compliant editor or client, +we support two ways of connecting. -### Named Pipes/Unix Domain Sockets (recommended) +### Named Pipes / Unix Domain Sockets If you're looking for a more feature-rich experience, -Named Pipes are the way to go. +named pipes (AKA sockets) are the way to go. They give you all the benefits of the Language Server Protocol with extra capabilities that you can take advantage of: - The PowerShell Extension Terminal - Debugging using the [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/) -The typical command to start PowerShell Editor Services using `stdio` is as follows: +The typical command to start PowerShell Editor Services using named pipes / sockets is as follows: ```powershell -pwsh -NoLogo -NoProfile -Command "./PowerShellEditorServices/Start-EditorServices.ps1 -Stdio" +pwsh -NoLogo -NoProfile -Command "./PowerShellEditorServices/Start-EditorServices.ps1 -SessionDetailsPath ./session.json" ``` -The start script, `Start-EditorServices.ps1` is found in the `PowerShellEditorServices` folder instead the `PowerShellEditorServices.zip` downloaded from the GitHub releases. +The start script, `Start-EditorServices.ps1`, is found in the `PowerShellEditorServices` folder instead the `PowerShellEditorServices.zip` downloaded from the GitHub releases. + +The session details (which named pipes were created) will be written to the given session details path, +and the client needs to point to these in order to connect. + +The Visual Studio Code, Vim, and IntelliJ extensions use named pipes. -Alternatively, the `-Stdio` argument can be removed and the argument `-SessionDetailsPath ./session.json` added to produce a JSON file the client needs to point to in order to connect over a named pipe / socket. -The use stdio is the simplest way to connect with most LSP clients, -but may limit some features (such as the debugger and Extension Terminal). +### Standard Input and Output -Please see the [emacs-simple-test.el](test\emacs-simple-test.el), -[emacs-test.el](test\emacs-test.el), -[vim-simple-test.el](test\vim-simple-test.vim) and [vim-test.vim](test\vim-test.vim) for examples of end-to-end tested configurations. +Alternatively, the `-SessionDetailsPath ./session.json` argument can be replaced with just `-Stdio`. +The use of stdio is the _simplest_ way to connect with most LSP clients, +but will limit some features, such as the debugger and Extension Terminal. +This is because because these two features require their own IO streams and stdio only provides a single pair of streams. + +Please see the [emacs-simple-test.el](test/emacs-simple-test.el), +[emacs-test.el](test/emacs-test.el), +[vim-simple-test.el](test/vim-simple-test.vim) and [vim-test.vim](test/vim-test.vim) for examples of end-to-end tested configurations. +They use [eglot for Emacs](https://github.com/joaotavora/eglot) and [LanguageClient-neovim](https://github.com/autozimu/LanguageClient-neovim). + +### Advanced Usage If you are trying to automate the service in PowerShell, you can also run it under `Start-Process` to prevent hanging your script. -It also gives you access to Process/PID automation features like `$process.Close()` or `$process.Kill()`. -The script takes many more optional arguments, but they no longer _need_ to be specified. +It also gives you access to process automation features like `$process.Close()` or `$process.Kill()`. +The `Start-EditorServices.ps1` script takes many more optional arguments, but they no longer _need_ to be specified. ```powershell $command = @( "$PSES_BUNDLE_PATH/PowerShellEditorServices/Start-EditorServices.ps1", "-BundledModulesPath $PSES_BUNDLE_PATH", - "-LogPath $SESSION_LOGS_PATH", - "-SessionDetailsPath $SESSION_TEMP_PATH/session.json", + "-LogPath ./logs", + "-SessionDetailsPath ./session.json", "-FeatureFlags @()", "-AdditionalModules @()", "-HostName 'My Client'", "-HostProfileId 'myclient'", "-HostVersion 1.0.0", "-LogLevel Diagnostic" -)-join " " +) -join " " $pwsh_arguments = "-NoLogo -NoProfile -Command $command" $process = Start-Process pwsh -ArgumentList $arguments -PassThru @@ -86,63 +101,40 @@ The `session.json` will contain the paths of the named pipes that you will conne There will be one you immediately connect to for Language Server Protocol messages, and once you connect to when you launch the debugger for Debug Adapter Protocol messages. -The Visual Studio Code, Vim, and IntelliJ extensions currently can use named pipes. - -#### PowerShell Extension Terminal +### PowerShell Extension Terminal ![image](https://user-images.githubusercontent.com/2644648/66245084-6985da80-e6c0-11e9-9c7b-4c8476190df5.png) -The PowerShell Extension Terminal uses the host process' Stdio streams for console input and output. Please note that this is mutually exclusive from using Stdio for the language server protocol messages. +The PowerShell Extension Terminal uses the host process' stdio streams for console input and output. +Please note that this is mutually exclusive from using stdio for the Language Server Protocol messages. -If you want to take advantage of the PowerShell Extension Terminal which automatically shares state with the editor-side, -you must include the `-EnableConsoleRepl` switch when called `Start-EditorServices.ps1`. +If you want to take advantage of the PowerShell Extension Terminal, +you must include the `-EnableConsoleRepl` switch when calling `Start-EditorServices.ps1`. This is typically used if your client can create arbitrary terminals in the editor like below: -![Extension Terminal in vscode](https://user-images.githubusercontent.com/2644648/66245018-04ca8000-e6c0-11e9-808c-b86144149444.png) +![Extension Terminal in VS Code](https://user-images.githubusercontent.com/2644648/66245018-04ca8000-e6c0-11e9-808c-b86144149444.png) The Visual Studio Code, Vim, and IntelliJ extensions currently use the PowerShell Extension Terminal. -#### Debugging +### Debugging Debugging support is also exposed with PowerShell Editor Services. -It is handled within the same process as the language server protocol handing. -This provides a more integrated experience for end users but is something to note as not many other language servers work in this way. +It is handled within the same process as the Language Server Protocol. +This provides a more integrated experience for end users but is something to note as not many other language servers work in the same way. If you want to take advantage of debugging, your client must support the [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/). Your client should use the path to the debug named pipe found in the `session.json` file talked about above. Currently, only the Visual Studio Code extension supports debugging. -### Stdio - -Stdio is a simpler and more universal mechanism for the Language Server Protocol. We recommend using it if your editor/client doesn't need to support the PowerShell Extension Terminal or debugging. - -> NOTE: Debugging and the Extension Terminal are not features of the Stdio channel because each feature requires its own IO streams and since the Stdio model only provides a single set of streams (Stdio), -> these features cannot be leveraged. - -The typical command to start PowerShell Editor Services using stdio is as follows: - -```powershell -pwsh -NoLogo -NoProfile -Command "$PSES_BUNDLE_PATH/PowerShellEditorServices/Start-EditorServices.ps1 -BundledModulesPath $PSES_BUNDLE_PATH -LogPath $SESSION_TEMP_PATH/logs.log -SessionDetailsPath $SESSION_TEMP_PATH/session.json -FeatureFlags @() -AdditionalModules @() -HostName 'My Client' -HostProfileId 'myclient' -HostVersion 1.0.0 -Stdio -LogLevel Normal" -``` - -> NOTE: In the example above, -> -> - `$PSES_BUNDLE_PATH` is the root of the PowerShellEditorServices.zip downloaded from the GitHub releases. -> - `$SESSION_TEMP_PATH` is the folder path that you'll use for this specific editor session. - -The important flag is the `-Stdio` flag which enables this communication protocol. - -Currently, the Emacs extension uses Stdio. - -### API Usage +## API Usage Please note that we only consider the following as stable APIs that can be relied on: -- Language server protocol connection -- Debug adapter protocol connection -- Start up mechanism +- Language Server Protocol connection +- Debug Adapter Protocol connection +- Start-up mechanism The types of PowerShell Editor Services can change at any moment and should not be linked against in a production environment. @@ -167,7 +159,20 @@ Install-Module InvokeBuild -Scope CurrentUser Install-Module platyPS -Scope CurrentUser ``` -Now you're ready to build the code. You can do so in one of two ways: +### 4. Delete `NuGet.Config` + +Our NuGet configuration points to a private feed necessary for secure builds, +and it must be committed to the repo as it is. +The easiest way to build without access to that private feed is to delete the file: + +```powershell +Remove-Item NuGet.Config +``` + +Please be careful not to commit this change in a PR. + +Now you're ready to build the code. +You can do so in one of two ways: ### Building the code from PowerShell diff --git a/module/PowerShellEditorServices/PowerShellEditorServices.psd1 b/module/PowerShellEditorServices/PowerShellEditorServices.psd1 index 39b7bca5c..ebeba42f9 100644 --- a/module/PowerShellEditorServices/PowerShellEditorServices.psd1 +++ b/module/PowerShellEditorServices/PowerShellEditorServices.psd1 @@ -19,7 +19,7 @@ RootModule = if ($PSEdition -eq 'Core') } # Version number of this module. -ModuleVersion = '3.18.0' +ModuleVersion = '3.18.1' # ID used to uniquely identify this module GUID = '9ca15887-53a2-479a-9cda-48d26bcb6c47' diff --git a/tools/terms/FileTypeSet.xml b/tools/terms/FileTypeSet.xml deleted file mode 100644 index 82f9f4d09..000000000 --- a/tools/terms/FileTypeSet.xml +++ /dev/null @@ -1,379 +0,0 @@ - - - - - Pure Text Files - - .txt - .des - .pwd - .asm - .cmd - .ini - .poc - .pwt - .hpj - .sql - .inf - .log - .def - .url - .bat - .aspx - .idl - .sys - .resources - .strings - .md - .yml - .yaml - .spelling - .gitignore - .gitattributes - .gitmodules - .csv - .tsv - - - - CodeFiles - - .frm - .inc - .cpp - .cls - .c - .hpp - .vbs - .java - .cs - .cxx - .h - .jav - .bas - .hxx - .js - .pl - .rc - .vb - .json - .resjson - .fs - .fsi - .fsx - .m - .psm1 - .config - .ps1 - .psd1 - .cmake - .sh - .cshtml - .plist - .mof - .mc - - - - XML Files - - .xml - .hxa - .hxk - .hxl - .xsl - .hxc - .hxt - .hxm - .resx - .hxe - .hxf - .hxv - .acctb - .accfl - .xaml - .ttml - .ddue - .sln - .props - .ps1xml - .csproj - .xsd - .svg - .clixml - .nuspec - .cdxml - .manifest - - - - Microsoft Word Documents - - .doc - .dot - .wiz - - - - Microsoft Access Database Compatible - - .mdb - .mda - .mde - .mpd - .mdt - - - - Microsoft PowerPoint Presentation - - .ppt - .pot - .pps - - - - Microsoft Publisher Files - - .pub - - - - Microsoft Excel Workbooks - - .xls - .xlt - - - - Pure Binary Files - - .com - .bin - .tlb - .drv - .fon - .blg - .gif - .png - .icns - .ico - .bmp - .pfx - - - - Localization resource databases - - .edb - .lcl - .xlf - .xliff - - - - Microsoft Project Files - - .mpp - .mpt - - - - Microsoft Visio Files - - .vsd - .vdx - .vss - .vst - - - - Windows Installer databases - - .msi - .msm - - - - Zip Files - - .zip - .accdt - .axtr - - - - Cabinet / MS Compression Files - - .cab - - - - Table driven IME lexicons - - .mb - - - - IME ( IMD ) Files - - .imd - - - - TrueType Font Files - - .ttf - - - - Microsoft Outlook Mail Files - - .msg - .oft - - - - HTML Help 2.0 Files / InfoTech5.x Storage System Files - - .its - .hxh - .hxr - .hxw - .hxi - .hxs - .hxq - - - - Adobe Acrobat PDF Files - - .pdf - - - - HTML Files / Web Page - - .htm - .dtd - .hhk - .htw - .asp - .htc - .htx - .html - .hhc - .css - .stm - - - - Rich Text Files - - .rtf - - - - Windows 3.x Write Files - - .wri - - - - MHTML Files - - .eml - .nws - .mht - - - - Word 2007 Files - - .docx - .docm - .dotx - .dotm - - - - Excel 2007 Files - - .xlsx - .xlsm - .xltx - .xltm - .xlsb - .xlam - - - - Power Point 2007 Files - - .pptx - .pptm - .potx - .potm - .ppsx - .ppsm - .ppam - - - - Access 2007 Files - - .accdb - .accde - .accdr - - - - Win32/64-based executable (image) Files - - .exe - .dll - .ocx - .scr - .acm - .rll - .cpl - .mui - .ax - .ime - - - - HTML Help 1.0 Files - - .chm - - - - LocStudio lsg - - .lsg - - - - Microsoft Office OneNote Files - - .one - .onepkg - - - - Custom Parsers - - - - - Visio 2011 Files - - .vstx - .vsdx - .vssx - - - - - diff --git a/tools/terms/UserExclusions.xml b/tools/terms/UserExclusions.xml deleted file mode 100644 index f7ff9f7b9..000000000 --- a/tools/terms/UserExclusions.xml +++ /dev/null @@ -1,12 +0,0 @@ - - - - - .GIT - - - - - - - diff --git a/tools/updateVersion.ps1 b/tools/updateVersion.ps1 new file mode 100644 index 000000000..e5b94280c --- /dev/null +++ b/tools/updateVersion.ps1 @@ -0,0 +1,45 @@ +# Copyright (c) Microsoft Corporation. +# Licensed under the MIT License. + +param( + [Parameter(Mandatory)] + [semver]$Version, + + [Parameter(Mandatory)] + [string]$Changes +) + +git diff --staged --quiet --exit-code +if ($LASTEXITCODE -ne 0) { + throw "There are staged changes in the repository. Please commit or reset them before running this script." +} + +$v = "$($Version.Major).$($Version.Minor).$($Version.Patch)" + +$path = "PowerShellEditorServices.Common.props" +$f = Get-Content -Path $path +$f = $f -replace '^(?\s+)(.+)(?)$', "`${prefix}${v}`${suffix}" +$f = $f -replace '^(?\s+)(.*)(?)$', "`${prefix}$($Version.PreReleaseLabel)`${suffix}" +$f | Set-Content -Path $path +git add $path + +$path = "module/PowerShellEditorServices/PowerShellEditorServices.psd1" +$f = Get-Content -Path $path +$f = $f -replace "^(?ModuleVersion = ')(.+)(?')`$", "`${prefix}${v}`${suffix}" +$f | Set-Content -Path $path +git add $path + +$path = "CHANGELOG.md" +$Changelog = Get-Content -Path $path +@( + $Changelog[0..1] + "## v$Version" + "### $([datetime]::Now.ToString('dddd, MMMM dd, yyyy'))" + "" + $Changes + "" + $Changelog[2..$Changelog.Length] +) | Set-Content -Encoding utf8NoBOM -Path $path +git add $path + +git commit --edit --message "v$($Version): $Changes"